如何在Golang中组织公共工具包_Golang公共包设计思路 返回列表

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），且不依赖其他子包（杜绝循环引用）。

导出函数必须无隐式状态，禁止全局变量污染

常见错误是写一个 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 序列化逻辑、带业务规则的金额计算——它们看起来“可复用”，但实际耦合了上下文假设。宁可重复两行代码，也不要引入一个半成品抽象。