Go模块公共库需明确边界、保持正交、拥抱标准、轻量演进；接口先行、功能聚类、零依赖优先、文档即契约，核心是“准”而非“多”。
为Go模块编写可复用的公共库，核心在于明确边界、保持正交、拥抱标准、轻量演进。不是把常用函数堆在一起就叫“公共包”，而是要让每个导入它的项目都感觉“刚好够用、不带负担、不易出错”。
接口先行：用 contract 约束行为，而非实现
公共库的生命力取决于它能否被不同上下文安全替换或模拟。不要暴露结构体字段或内部方法，优先定义 interface，并让导出函数接收接口而非具体类型。
- 例如提供日志能力时，导出
Log(log.Logger, ...)而非Log(*zap.Logger, ...) - 数据库工具类应接受
sql.DB或driver.Conn，而不是绑定gorm.DB - HTTP 工具函数接收
http.RoundTripper或context.Context，而非硬编码http.DefaultClient
功能聚类：一个包只解决一类问题，拒绝“utils”大杂烩
命名含 utils、common、base 的包往往是技术债温床。按领域切分，比如：
-
github.com/yourorg/go-encoding/jsonx—— 带默认 tag 处理、错误包装的 JSON 工具 -
github.com/yourorg/go-time/range—— 时间区间计算、重叠判断、序列生成 -
github.com/yourorg/go-id/xid—— 分布式 ID 生成（兼容 xid 格式，无依赖）
每个子包独立版本、独立测试、可单独 go get，使用者按需引入，不为无关代码买单。
零依赖 + 显式依赖 = 可信度
公共库默认应只依赖 std。若必须引入第三方，需满足三个条件：
- 该依赖本身稳定（发布语义化版本、无 breaking change 历史）
- 只用于特定扩展能力（如
gjson仅在jsonx/gjson.go中使用，不影响主逻辑） - 通过
_导入或构建标签隔离，确保基础功能在禁用该依赖时仍可编译运行
在 go.mod 中避免 require 非直接依赖；用 //go:build 控制可选能力，比 init() 注册更清晰可控。
文档即契约：README + Example + godoc 三位一体
别人第一次打开你的包，应该 30 秒内知道它能做什么、不能做什么、怎么安全用。
- README.md 开头写清适用场景和典型误用（例如：“不适用于高并发计数器，请用 atomic.Int64”）
- 每个导出符号配
ExampleXXX函数，go test -run=Example可验证 - godoc 注释里写明参数约束（如 “
timeout > 0”）、panic 条件、返回错误含义（如 “io.EOF表示流已结束，非错误”）
不写“高级用法”，先确保最朴素的调用路径 100% 可靠。
基本上就这些。可复用不是靠“多”，而是靠“准”——准确定义问题、准确划清职责、准确表达意图。Go 的简洁性，本就是公共库最好的设计约束。
