基础包应按职责拆分为 pkg/log、pkg/config、pkg/errx、pkg/httpx 四个子包，严禁 common 大杂烩；所有包仅依赖标准库或指定第三方，禁止引入业务代码；通过 CI 检查、单元测试隔离、语义化版本（如 v2 新路径）管控升级风险。
Go 语言中没有“公共基础包”的官方概念，但团队协作时必须统一处理日志、配置、错误、HTTP 客户端等共性能力——关键不是建一个叫 common 或 utils 的包，而是按职责边界拆分、避免循环依赖、禁止在基础包里引入业务逻辑。
基础包该拆成哪些子包？
按 Go 的惯用法和实际维护成本，建议划分为：
-
pkg/log：封装zap或zerolog，暴露Logger接口和预设字段（如request_id），不暴露底层 logger 实例 -
pkg/config：支持 YAML/TOML/环境变量多源加载，返回结构体而非 map，校验失败应 panic（启动期错误） -
pkg/errx：定义ErrorCode枚举、Wrap/Is等函数，错误值必须可序列化（不带闭包或指针） -
pkg/httpx：封装http.Client，内置超时、重试、trace 注入，不封装具体 API（那是 domain/client 层的事）
不要建 pkg/common 这种大杂烩包——它会迅速变成循环依赖的温床，且无法做细粒度版本控制。
如何防止基础包被业务代码污染？
最常见问题是：有人在 pkg/log 里加了个 LogUserAction()，结果这个函数依赖了 user.Service，导致整个日志包强耦合用户模块。
立即学习“go语言免费学习笔记（深入）”；
- 所有基础包只能依赖标准库或明确声明的第三方（如
go.uber.org/zap），禁止 import 任何业务路径（如internal/service、domain/model） - CI 中加入检查：对
pkg/下每个包执行go list -f '{{.Imports}}' pkg/log，grep 出现internal/或domain/就报错 - 基础包的单元测试不能启 HTTP server 或连 DB——它只负责行为契约，不负责集成
版本管理与升级风险怎么控？
基础包一旦发布 v1，所有下游服务都会隐式依赖它的 ABI。Go 没有语义导入版本，所以：
- 用
go.mod的replace在本地验证 breaking change，但上线前必须删掉 - 修改
pkg/errx.ErrorDetail()返回类型属于 breaking change，需升 v2 并新建路径pkg/errx/v2（Go Modules 规范） - 小修如新增
log.WithField("trace_id", id)是安全的；但把log.Info()改成接收context.Context就不是——已有调用处会编译失败
真正难的不是写代码，是守住边界：基础包不是功能集合，而是协议定义者。它越薄、越不可变，项目后期越不容易因为一次“加个简单工具函数”引发雪崩式重构。
