Go公共工具包本质是跨模块复用的契约，需保障向后兼容、清晰语义与可控副作用；路径须独立稳定（如github.com/yourorg/go-tools），按领域拆分子包，函数无隐式状态，错误类型结构化且不panic。
Go 项目里所谓“公共工具包”，不是放一堆 utils 就完事；它本质是跨模块复用的契约——一旦暴露，就要承担向后兼容、清晰语义和可控副作用的责任。
包路径必须反映稳定接口，而非物理位置
很多人把工具函数塞进 github.com/yourorg/project/internal/utils，结果其他服务想复用时发现无法 import：因为 internal 是 Go 的私有约束机制，外部项目根本看不到。真正可复用的包，路径必须以组织域名开头、独立于任何主项目：
-
github.com/yourorg/go-tools（推荐）——完全独立仓库，版本可控 -
github.com/yourorg/shared——若暂不拆仓，至少放在主 repo 根目录，且不含internal或cmd - 避免
github.com/yourorg/project/pkg/utils这类路径——project名称绑定业务，未来迁移或分拆时路径即失效
按领域而非功能粒度拆分子包，拒绝 mega-utils
一个叫 utils 的包，三个月后大概率变成没人敢改的“黑洞”。Go 的包系统天然适合垂直切分，应按问题域组织，例如：
-
github.com/yourorg/go-tools/strutil—— 仅处理字符串编码、截断、模糊匹配等，不碰 JSON 或正则编译 -
github.com/yourorg/go-tools/timeutil—— 封装时区转换、持续时间格式化，但不包含 cron 解析 -
github.com/yourorg/go-tools/httputil—— 提供RoundTripFunc、ResponseWriterWrapper等测试/中间件辅助，不实现完整 client
每个子包的 go.mod 应声明最小 Go 版本（如 go 1.20），且不依赖其他子包（杜绝循环引用）。
立即学习“go语言免费学习笔记（深入）”；
导出函数必须无隐式状态，禁止全局变量污染
常见错误是写一个 Config 全局变量 + Init() 函数，然后所有工具函数都读它——这会让调用方无法并行使用、难以单元测试，也违反 Go “显式优于隐式” 原则。
- 所有参数必须显式传入：
ParseJSON(data []byte, opts ...JSONOption)而非ParseJSON(data []byte)默读全局配置 - 避免包级变量缓存：
var cache = map[string]string{}是并发不安全的源头；如需缓存，用sync.Map或要求调用方传入*cache.Cache - 时间相关函数不依赖
time.Now()，而是接收time.Time或func() time.Time作为参数，方便测试冻结时间
错误处理统一用自定义 error 类型，不裸露底层错误
工具包返回 fmt.Errorf("json: %w", err) 是危险的——调用方无法用 errors.Is() 判断类型，也无法提取结构化信息。
type ParseError struct {
Input string
Code string // e.g., "invalid_base64"
}
func (e *ParseError) Error() string {
return fmt.Sprintf("parse error (%s): %q", e.Code, e.Input)
}
func DecodeBase64(s string) ([]byte, error) {
data, err := base64.StdEncoding.DecodeString(s)
if err != nil {
return nil, &ParseError{Input: s, Code: "invalid_base64"}
}
return data, nil
}
这样调用方可精确判断：if errors.As(err, &ParseError{}) { ... }。同时避免在工具包中调用 log.Fatal 或 panic——错误必须可捕获、可重试、可忽略。
最难的不是写工具函数，而是决定哪些不该放进公共包：比如某个项目专用的 Redis 序列化逻辑、带业务规则的金额计算——它们看起来“可复用”，但实际耦合了上下文假设。宁可重复两行代码，也不要引入一个半成品抽象。
