core

package module
v1.6.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

core

core 是个人使用的 Go 基础类库,模块路径为 github.com/go-sdk/core。项目用于统一常见基础能力和默认行为,包括配置加载、错误处理、生命周期、全局日志、环境变量、构建版本、HTTP 客户端、JSON 与 YAML 编解码、零拷贝类型转换、序列生成和测试辅助。

环境要求

  • Go 1.27 或更高版本

安装

go get github.com/go-sdk/core

包概览

包 用途
cmdx 创建 cobra 根命令并包装命令入口
codec/json 基于 encoding/json/v2 的 JSON 编解码
codec/yaml 基于 go.yaml.in/yaml/v3 的 YAML 编解码
config 加载文件和环境变量配置
conv string 与 []byte 零拷贝互转、基础类型与指针转换
errx 创建、包装和判断错误
lifex 管理信号、初始化和解构的进程生命周期
logx 配置并使用进程级全局日志
osx 读取系统、路径、环境变量和构建信息
restx 创建带统一默认配置的 resty 客户端
seq 生成 Snowflake ID 和 UUID v7
testx 提供常用测试断言、假数据和输出辅助

使用示例

配置

config 支持 YAML 和 JSON 文件,并使用 . 访问嵌套配置:

database:
  type: postgres
  port: 5432
dsn: "postgres://${database.type}:${database.port}/app"
cfg := config.New(
	config.WithFile("config.yaml"),
	config.WithFileWatch(true),
)
if err := cfg.Load(); err != nil {
	return err
}

databaseType, ok := cfg.Get[string]("database.type")
databasePort := cfg.MustGet[int]("database.port")
databaseHost := cfg.MustGet("database.host", "localhost")
raw := cfg.Raw()

MustGet 在配置存在时返回转换后的值;配置不存在且传入默认值时返回第一个默认值,未传默认值时触发 panic。配置存在但转换失败时返回目标类型零值,不回退到默认值。

WithFile 的第二个参数可以在文件没有标准扩展名时显式指定格式,例如 config.WithFile("config.data", "json")。文件监听默认关闭;启用后由 lifex 在进程解构时关闭,文件重载失败会保留最后一次有效配置。

环境变量只读取 APP__ 前缀,移除前缀后将 key 转为小写,并使用 __ 表示层级。例如 APP__DATABASE__TYPE=mysql 覆盖 database.type。环境变量优先于文件配置,${database.type} 使用与 Get 相同的路径;缺失引用或循环引用会使加载失败。

Raw 返回嵌套数据的深拷贝。DecodeTo 使用 json tag,并允许将环境变量字符串弱类型转换到目标字段;字符串会按 Go duration 格式解析到 time.Duration,按 RFC3339 格式解析到 time.Time。解码后使用 validate tag 校验字段:

type AppConfig struct {
	Database struct {
		Type string `json:"type" validate:"required"`
		Port int    `json:"port" validate:"min=1,max=65535"`
	} `json:"database"`
}

var appConfig AppConfig
if err := cfg.DecodeTo(&appConfig); err != nil {
	return err
}

DecodeTo 的目标必须是结构体指针;没有 validate tag 的结构体仍只执行解码。校验失败时返回的错误链保留 validator.ValidationErrors,调用方可按需提取具体字段错误;非结构体目标返回 validator.InvalidValidationError。

包级默认实例在初始化时解析配置文件,任何失败都会直接 panic。CONFIG_PATH 一经设置即直接采用该路径且不回退,空值、文件不存在或不可读均视为失败;未设置 CONFIG_PATH 时,按测试进程所在模块(go.work 下为当前目录所属模块)根目录的 config.yaml、可执行文件同名的 .yaml、.yml、.json 顺序读取第一个存在的文件,全部不存在时仅加载环境变量。默认实例可通过 SetDefault 替换:

databaseType, ok := config.Get[string]("database.type")
databasePort := config.MustGet[int]("database.port")
databaseHost := config.MustGet("database.host", "localhost")
hasDatabase := config.Exists("database")
raw := config.Raw()

config.SetDefault(cfg)

var appConfig AppConfig
if err := config.DecodeTo(&appConfig); err != nil {
	return err
}
命令行
root := cmdx.NewRoot("app")
root.AddCommand(&cmdx.Command{
	Use: "run",
	RunE: cmdx.WrapRunE(func(cmd *cmdx.Command, args []string) error {
		return nil
	}),
})

if err := root.Execute(); err != nil {
	logx.Error().Err(err).Msg("执行失败")
}

NewRoot 隐藏 help 和 completion 子命令,--version 输出来自 osx.GetVersion 的单行版本描述。cobra 自身的错误输出被丢弃,命令错误由 Execute 直接返回,调用方自行处理;WrapRunE 将 errx.Nil 哨兵错误视为无错误,其余错误原样返回。

cmdx 直接暴露 Cobra 常用的位置参数校验器,可通过 Args 配置:

root.AddCommand(&cmdx.Command{
	Use:  "get <name>",
	Args: cmdx.ExactArgs(1),
})

root.AddCommand(&cmdx.Command{
	Use:  "delete <name> [name]...",
	Args: cmdx.MatchAll(cmdx.MinimumNArgs(1), cmdx.OnlyValidArgs),
})

NoArgs、OnlyValidArgs、ArbitraryArgs 分别限制为无参数、仅允许 ValidArgs 中的参数和任意参数;MinimumNArgs、MaximumNArgs、ExactArgs、RangeArgs 按数量限制参数;MatchAll 可组合多个校验器。Cobra 的 ExactValidArgs 已弃用,新的代码使用 MatchAll(ExactArgs(n), OnlyValidArgs)。

命令输出可使用 Print、Printf 和 Println,它们统一写入 cmd.OutOrStdout(),不返回写入结果:

cmdx.Println(cmd, "执行完成")
JSON 编解码
s, err := json.Marshal[string](data)
bs, err := json.Marshal[[]byte](data)
s, err = json.Marshal[string](data, json.WithIndent("  "))
s, err = json.MarshalIndent[string](data, "  ", json.Deterministic(true))
s, err = json.MarshalOmitZero[string](data)
s = json.MustMarshalIndent[string](data, "  ")
bs = json.MustMarshalOmitZero[[]byte](data)

var out Data
err = json.Unmarshal(s, &out)
value := json.MustUnmarshal[Data](bs)

err = json.MarshalWrite(w, data, json.Deterministic(true))
err = json.UnmarshalRead(r, &out, json.RejectUnknownMembers(true))

Marshal 和 Unmarshal 通过泛型参数支持 string 与 []byte 两种载体,内部经 conv 零拷贝互转;Must 前缀版本在出错时直接 panic。MarshalWrite 和 UnmarshalRead 直接面向 io.Writer 和 io.Reader 编解码;StringifyNumbers、Deterministic 等选项继承自 encoding/json/v2,其中 StringifyNumbers 和 MatchCaseInsensitiveNames 对序列化和反序列化都生效,RejectUnknownMembers 仅对反序列化生效,其余仅对序列化生效。

Value 是 jsontext.Value 的类型别名,用于原始 JSON 内容。另提供七个 jsontext 选项别名:WithIndent、WithIndentPrefix、Multiline、EscapeForHTML、EscapeForJS、SpaceAfterColon 和 SpaceAfterComma,均仅影响序列化。WithIndent 和 WithIndentPrefix 隐含开启多行输出,参数只能包含空格和制表符;WithIndent("") 仍然输出多行,关闭多行需使用 Multiline(false)。后面的同名选项覆盖前面的选项。

MarshalIndent 和 MustMarshalIndent 接受 indent string,默认应用 WithIndent(indent);MarshalOmitZero 和 MustMarshalOmitZero 默认应用 OmitZeroStructFields(true),按上游零值语义省略结构体字段。四个函数均支持 string 与 []byte,接受 opts ...json.Options(来自 encoding/json/v2),调用方选项在默认选项之后生效,可覆盖缩进、关闭多行或关闭零值省略。

YAML 编解码
s, err := yaml.Marshal[string](data)
bs, err := yaml.Marshal[[]byte](data)
s, err = yaml.Marshal[string](data, yaml.WithIndent(2), yaml.WithCompactSeqIndent(true))

var out Data
err = yaml.Unmarshal(s, &out)
err = yaml.Unmarshal(s, &out, yaml.WithKnownFields(true))
value := yaml.MustUnmarshal[Data](bs)

enc := yaml.NewEncoder(w) // 使用后必须 Close 才能刷出剩余数据
enc.SetIndent(2)
err = enc.Encode(data)
err = enc.Close()

codec/yaml 同样通过泛型参数支持 string 与 []byte 两种载体并复用 conv 零拷贝互转。Marshal、MustMarshal、Unmarshal 和 MustUnmarshal 接受统一的 opts ...Options,后面的同名选项覆盖前面的选项,不适用于当前编解码方向的选项被忽略。不传选项时直接使用上游函数,保持原有默认行为;增加可变参数不影响原有直接调用,但会改变函数类型,赋给固定签名函数变量的调用方需要适配。

  • WithIndent(spaces int):仅序列化生效,设置缩进空格数。通常使用 2 或 4;0 使用上游默认的 4,负数在序列化时触发 panic,其余超出 2–9 的正数由上游回退为 2。
  • WithCompactSeqIndent(enabled bool):仅序列化生效,控制序列标记 - 是否计入缩进,默认关闭;设为 false 恢复默认模式。
  • WithKnownFields(enabled bool):仅反序列化生效,检查映射键是否对应目标结构体字段,默认关闭,不限制 map 的键。带选项的解码仍只读取首个文档,空输入或只有注释时不修改目标值且不返回错误。

Node、Kind、Style、Encoder 和 Decoder 是上游类型别名,同时暴露全部节点类型和样式常量。可以仅依赖本包构造和修改语法树、声明 UnmarshalYAML(*yaml.Node) error 回调,类型身份和方法集保持一致。

NewEncoder 和 NewDecoder 保持为 yaml/v3 的别名,可按文档流顺序读写多个 YAML 文档,流式配置直接使用 SetIndent、CompactSeqIndent、DefaultSeqIndent 和 KnownFields 方法。上游对 chan、func 等无法表示的类型会直接 panic 而非返回错误。

类型转换
bs := conv.StringToBytes("starudream")
s := conv.BytesToString(bs)

n, err := conv.ToE[int]("123")
n = conv.To[int]("123") // 失败时返回 0

v := 123
s := conv.PtrValue(&v)       // 123
z := conv.PtrValue[int](nil) // 0

StringToBytes 和 BytesToString 基于 unsafe 实现零拷贝互转,空输入返回对应零值(nil 或空串);由 string 转出的 []byte 底层只读,不可修改。

ToE 和 To 基于 github.com/spf13/cast 将任意值弱类型转换为基础类型,支持 string、bool、各类数字、time.Time 和 time.Duration;ToE 转换失败时返回错误和类型零值,To 转换失败时返回类型零值。

PtrValue 返回指针指向的值,指针为 nil 时返回类型零值。

错误处理
cause := errx.New("操作失败")
err := errx.Wrap(cause, "保存数据")

if errx.Is(err, cause) {
	// 处理目标错误
}

joined := errx.Join(errA, errB)
if errx.Is(joined, errA) {
	// 命中合并中的任一错误
}

target, ok := errx.AsType[*MyError](joined)

New、Newf、Wrap、Wrapf、Unwrap 和 Cause 基于 eris;Join、Is、As 和 AsType 使用标准库 errors,其中 Is 和 As 可以遍历 Join 合并的多错误链,AsType 通过类型参数提取指定类型的错误。Unwrap 和 Cause 只沿单链展开,遇到 Join 合并的错误时停在该节点。As 沿用标准库契约,目标必须是合法的非空指针。

生命周期
initialize := func() error {
	// 建立资源连接
	return nil
}

deinitialize := func() {
	// 释放资源
}

lifex.OnInit(initialize)
lifex.OnDeinit(deinitialize)

if err := lifex.Init(); err != nil {
	logx.Error().Err(err).Msg("初始化失败")
	return
}

if err := lifex.Wait(); err != nil {
	logx.Error().Err(err).Msg("进程异常退出")
}

OnInit 和 OnDeinit 均接受 func()、func() error、func(context.Context) 与 func(context.Context) error,普通函数、方法值和函数字面量都可以直接注册;带上下文参数时传入 context.Background()。Init 按注册顺序执行初始化函数,任一失败立即停止后续执行并返回该错误。Wait 阻塞等待 SIGINT/SIGTERM 信号或 Shutdown 触发退出,然后按注册逆序执行解构函数:信号触发视为正常退出返回 nil,主动退出返回 Shutdown 携带的原因;Shutdown 幂等,多次调用只触发一次退出。解构函数自身的错误经默认 slog 记录,不影响其余解构执行和 Wait 的返回值;解构期间再次收到退出信号时跳过剩余解构强制退出,避免解构卡死导致进程无法终止。

全局日志

logx 在包初始化时创建默认控制台日志。控制台默认写入标准输出;APP__LOG__CONSOLE 忽略大小写等于 stderr 时写入标准错误,其他值(包括空值)仍写入标准输出。应用读取配置后可以再次初始化,将日志同时写入滚动文件:

logx.Init("logs/app.log")

logx.Info().Str("service", "example").Msg("服务已启动")

重新调用 Init 会先刷新并关闭此前创建的文件 Writer。logx 会向 lifex 注册关闭函数,使用 lifex.Wait 时在进程解构阶段自动刷新并关闭文件 Writer;未使用 lifex 的程序仍应在退出前调用 logx.Close()。Close 后全局日志保留控制台输出,供生命周期完成日志和后续诊断使用。日志资源按进程统一管理,不使用独立 Logger 生命周期。控制台输出经 go-colorable 包装,在 Windows 终端下也能正常显示颜色。

SetGlobalKV 维护进程级全局键值,之后所有日志事件都会附带该键值,适合注入 service、version、instance、environment 等进程级标识:

logx.SetGlobalKV("service", "example")
logx.SetGlobalKV("version", "v1.0.0")

logx.Info().Msg("服务已启动")
// {"level":"info","service":"example","version":"v1.0.0","message":"服务已启动"}

logx.DeleteGlobalKV("version") // 删除指定键
logx.ClearGlobalKV()           // 清空全部键

全局键值只在写入时加锁,日志输出通过不可变快照无锁读取,可并发调用;对所有由 logx.New 创建的 Logger 生效,不影响调用方自行创建的 zerolog Logger。全局键与事件字段同名时会产生重复 JSON key,调用方应保证全局键不与日志字段冲突。

trace、request、user 等请求级字段会随请求并发变化,不应使用全局键值,应通过上下文 Logger 传递:

logger := logx.With().Str("trace", "abc123").Logger()
ctx := logger.WithContext(context.Background())

logx.Ctx(ctx).Info().Msg("处理请求")

默认配置加载前会先安装 zerolog 控制台 Handler,因此 config 使用的 slog、zerolog 和标准库 log 从启动阶段起采用相同的时间、级别和字段格式。logx 随后读取默认 config 实例,默认日志参数可以写入配置文件,也可以通过 APP__ 环境变量覆盖:

配置键 环境变量 含义 默认值
log.file.path APP__LOG__FILE__PATH 默认日志文件路径 空
log.no_color APP__LOG__NO_COLOR 禁用控制台颜色 自动检测
log.file.size APP__LOG__FILE__SIZE 单文件大小(MB) 30
log.file.age APP__LOG__FILE__AGE 旧文件保留天数 90
log.file.backups APP__LOG__FILE__BACKUPS 旧文件保留数量 10
log.file.localtime APP__LOG__FILE__LOCALTIME 使用本地时间轮转 true
log.file.compress APP__LOG__FILE__COMPRESS 压缩旧文件 true

配置项存在但为空或无法转换时返回目标类型零值,不使用默认值。例如 APP__LOG__FILE__SIZE 为空时单文件大小为零,由 lumberjack 回退到其自身的 100MB 默认值。

log.no_color 未配置时根据当前控制台输出是否为支持颜色的终端自动决定;TERM=dumb 或对应输出流被重定向时默认禁用颜色。显式配置始终优先。

环境变量
port := osx.GetEnv(8080, "APP_PORT", "PORT")
debug := osx.GetEnv(false, "APP_DEBUG", "DEBUG")

GetEnv 按名称顺序读取第一个已设置的环境变量。变量即使为空或无法转换也会立即采用,不再尝试后续名称;转换失败时返回目标类型的零值。只有全部变量都未设置时才返回默认值。

异常退出
osx.Panic("unexpected state")
osx.Panicf("unexpected state: %s", reason)

Panic 先将给定值和从调用方开始的调用堆栈以易读格式打印到标准错误输出,再调用内置 panic 保持原有行为;Panicf 按 format 格式化参数后行为一致。

系统与路径信息
hostname := osx.Hostname()
workDir := osx.WorkDir()
exeFull := osx.ExeFull()
exeDir := osx.ExeDir()
exeName := osx.ExeName()
exeExt := osx.ExeExt()
exeLog := osx.WithExeExt("log")

主机名和工作目录在调用时读取;可执行文件完整路径在包初始化时读取一次并缓存。WithExeExt 返回将可执行文件扩展名替换为指定扩展名的完整路径,常用于生成与程序同名的日志等辅助文件,扩展名缺少前导点时自动补齐。

构建与模块版本
version := osx.GetVersion()
coreVersion := osx.GetModuleVersion("github.com/go-sdk/core")

GetVersion 返回当前程序的版本控制和 Go 构建信息,结果只计算一次并缓存;程序版本可通过构建参数注入。GetModuleVersion 按完整模块路径查询当前程序构建信息中的主模块或依赖模块版本;模块使用 replace 时返回替换模块的版本。模块不存在、构建信息不可用、版本为空、开发版本为 (devel) 或替换目标是没有版本的本地目录时,统一返回 v0.0.0。

HTTP 客户端
client := restx.New()
response, err := client.R().Get("https://example.com")

客户端默认支持环境代理、HTTP/2、连接池和 Cookie Jar,请求总超时为五分钟。调试模式下(判定规则见 osx.IsDebug)resty 会输出请求与响应调试日志,内部日志统一由 logx 输出。

序列生成
id := seq.NextID()
uuid := seq.UUID()
shortUUID := seq.UUIDShort()

Snowflake 生成器读取 sonyflake.start_year 和 sonyflake.machine_id,默认值分别为 2020 和 56565;环境变量写法为 APP__SONYFLAKE__START_YEAR 和 APP__SONYFLAKE__MACHINE_ID(机器编号取值范围为 [0, 65535],起始年份须早于当前时间)。机器编号的唯一性范围为同一时间只运行一个生成器实例;非法取值会在包初始化时 panic。UUID 使用 v7 格式,并在包初始化时启用随机池。

测试辅助
func TestExample(t *testing.T) {
	value, err := loadValue()
	testx.P(t, err, value)
	testx.NotEmpty(t, value)

	type User struct {
		Name  string `fake:"{firstname}"`
		Email string `fake:"{email}"`
	}

	var user User
	testx.NoError(t, testx.Struct(&user))

	identifier, err := testx.Generate("user-{uuid}")
	testx.P(t, err, identifier)
}

P 将首个参数视为可选错误:参数为 nil 时忽略,为非空错误时终止当前测试,其余参数使用易读格式写入测试日志。

Generate 根据模板生成字符串,Struct 根据字段类型和 fake tag 填充结构体。需要扩展模板函数时,使用 AddFuncLookup 注册自定义生成函数;注册会修改进程级全局查找表,测试间应避免使用相同名称。

开发约定

修改代码前先阅读 AGENTS.md、PROJECT_MAP.md 和本文件。发现文档与实际代码不一致时,应在同一次修改中自动更新对应文档。

所有新增文档和代码注释使用简体中文。logx/log.go 直接来源于 zerolog 上游实现,保持原样,不在本仓库中修改。

Documentation

Overview

Package core 是个人使用的 Go 基础类库,统一常见基础能力和默认行为, 包括配置加载、错误处理、进程生命周期、全局日志、环境变量、HTTP 客户端、 JSON 与 YAML 编解码、序列生成和测试辅助。

根包本身不提供 API,各能力位于以下子包:

cmdx        创建 cobra 根命令并包装命令入口
config      加载 YAML/JSON 文件和 APP__ 前缀环境变量配置
conv        string 与 []byte 零拷贝互转
errx        创建、包装和判断错误
lifex       管理信号、初始化和解构的进程生命周期
logx        进程级全局日志,支持滚动文件和全局键值
osx         读取系统、路径、环境变量和构建版本信息
restx       创建带统一默认配置的 resty HTTP 客户端
seq         生成 Snowflake ID 和 UUID v7
testx       提供常用测试断言和输出辅助
codec/json  基于 encoding/json/v2 的 JSON 编解码
codec/yaml  基于 go.yaml.in/yaml/v3 的 YAML 编解码

安装:

go get github.com/go-sdk/core

各子包的详细用法和配置项说明见项目 README。

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL