如何在Golang模块中合理划分和封装公共辅助函数-Golang-PHP中文网

go项目应按职责边界而非类型堆砌拆分pkg子包，如pkg/strutil仅处理字符串安全操作，pkg/httpx封装http客户端配置，各包禁止依赖业务代码、不读全局状态、导出函数须显式传参，版本破坏性变更必须路径升级。

如何在golang模块中合理划分和封装公共辅助函数

别建 pkg/utils 或 internal/common —— 这类包会在三个月内变成无人敢动的“上帝包”，且无法做细粒度版本控制或独立测试。

按职责边界拆分 pkg/ 子包，而不是按类型堆函数

把字符串处理、HTTP 客户端、错误包装塞进同一个包，等于把螺丝刀、电钻和焊枪装进一个工具箱——用的时候全得翻一遍。Go 项目里真正可维护的公共包，是按“它解决什么问题”来命名的，不是按“它操作什么类型”。

pkg/strutil 只做字符串安全截断、正则提取、模糊匹配，不碰 slice 或 error
pkg/httpx 封装 http.Client 实例创建、超时、重试、trace 注入，不封装具体业务 API 调用逻辑
pkg/errx 提供 Wrap、Is、As 和预定义错误码（如 ErrNotFound），不依赖任何业务 model 或 service
pkg/log 暴露 Logger 接口和带 request_id 的字段注入，不暴露 *zap.Logger 实例，也不调用 os.Getenv

每个子包只 import 标准库或明确声明的第三方（如 go.uber.org/zap），CI 中可用 go list -f '{{.Imports}}' pkg/log | grep -E '(internal|domain)' 自动拦截业务污染。

导出函数必须显式传参，拒绝全局状态和隐式配置

写 func SendEmail(to string) 看似简单，实际绑死了 SMTP 地址、超时、认证方式——测试要 patch 全局变量，线上无法为不同场景设不同 timeout。正确做法是让调用方掌控上下文。

基础函数只接收必要参数：ParseJSON(data []byte) (map[string]interface{}, error)
可选行为用函数选项模式：WithTimeout(30*time.Second)、WithRetry(3)
绝不读环境变量、不读全局 struct、不调用 init() 初始化配置
返回 error，不 panic（启动期配置校验失败除外）

例如 pkg/httpx.NewClient(opts ...ClientOption) 内部默认 timeout 是 5s，但调用方可以自由覆盖：NewClient(WithTimeout(10*time.Second), WithRetry(2))。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

测试辅助函数必须带 `t.Helper()`，且仅限 _test.go 内部或 `pkg/testutil`

把 assertStatus、newTestDB、setupTempDir 放进业务包或通用工具包，会导致非测试代码意外依赖 testing.T，编译失败。测试逻辑和运行时逻辑必须物理隔离。

单元测试中重复出现的断言、数据构造、资源清理，应封装成以 t *testing.T 为第一参数的函数
函数内部第一行必须是 t.Helper()，否则报错行号指向辅助函数内部而非测试用例
临时资源（如文件、端口、数据库连接）要用 t.Cleanup() 注册释放，避免泄漏
若多个包共用同一套测试辅助逻辑，单独建 pkg/testutil，但禁止被非测试代码 import

示例：func assertEqual(t *testing.T, expected, actual interface{}) { t.Helper(); if !reflect.DeepEqual(expected, actual) { t.Fatalf("expected %+v, got %+v", expected, actual) } }。