角色：你是一位 Go 架构师，正使用 dig 编排应用依赖图。你将容器保留在组合根（composition root），依赖接口而非具体类型，并将构造函数错误视为头等失败（first-class failure）。

在 Go 中使用 uber-go/dig 进行依赖注入

基于反射的依赖注入（DI）工具包，专为支撑应用框架而设计（它是 uber-go/fx 的底层引擎），并在启动时解析对象依赖图。

官方资源：

• pkg.go.dev/go.uber.org/dig
• github.com/uber-go/dig

本技能内容并非详尽无遗。请参考库的文档与代码示例获取更多信息。Context7 可作为可发现性平台提供辅助。

go get go.uber.org/dig

dig 与 fx 的对比

fx 建立在 dig 之上，共享同一容器引擎 —— DI 基元（Provide、Invoke、In/Out 结构体、命名值、值组）完全一致。fx.In/fx.Out 即是对 dig.In/dig.Out 的重新导出。

fx 在 dig 基础上额外提供的能力：

选择 dig 当你仅需依赖图编排能力时：命令行工具、向调用方暴露容器的库、测试桩（test harnesses），或在已有自行管理生命周期的应用中嵌入 DI。

选择 fx 用于长期运行的服务（如 HTTP 服务器、Worker、守护进程）—— 此类场景下生命周期管理与信号处理是不可或缺的。详见 samber/cc-skills-golang@golang-uber-fx 技能。

容器

import "go.uber.org/dig"

c := dig.New()

常用选项：dig.DeferAcyclicVerification()（加快启动速度）、dig.RecoverFromPanics()（将 panic 转换为 dig.PanicError）、dig.DryRun(true)（仅校验不执行构造函数）。

Provide 与 Invoke

// 注册一个构造函数 — 懒加载，仅在其输出被需要时才执行
err := c.Provide(func(cfg *Config) (*sql.DB, error) {
    return sql.Open("postgres", cfg.DSN)
})

// 通过将其作为函数参数声明，从容器中提取服务
err = c.Invoke(func(db *sql.DB) error {
    return db.Ping()
})

构造函数是懒加载且记忆化的：每种输出类型仅构建一次，并在容器内共享（即单例）。若构造函数签名非法，Provide 会在注册时立即报错；Invoke 则返回构造函数自身的错误，并附带触发该错误的完整依赖路径。

dig 构造函数可以是任意函数。输入参数代表依赖项，返回值代表被提供的类型。error（最后一个返回值）表示构造失败。遵循“接受接口，返回结构体”原则。

使用 dig.In 的参数对象

当构造函数依赖项达到 4 个及以上时，建议嵌入 dig.In，将依赖项组织为结构体字段并添加结构体标签：

type HandlerParams struct {
    dig.In

    Logger *zap.Logger
    DB     *sql.DB
    Cache  *redis.Client `optional:"true"`           // 若未提供则使用零值
    DBRO   *sql.DB       `name:"readonly"`           // 命名依赖项
    Routes []http.Handler `group:"routes"`           // 值组
}

func NewHandler(p HandlerParams) *Handler { /* ... */ }

支持的标签：name:"..."、optional:"true"、group:"..."。

使用 dig.Out 的结果对象

从单个构造函数返回多个值，并为各返回值附加 name/group 标签：

type ConnResult struct {
    dig.Out

    ReadWrite *sql.DB `name:"primary"`
    ReadOnly  *sql.DB `name:"readonly"`
}

func NewConnections(cfg *Config) (ConnResult, error) { /* ... */ }

命名值

同类型存在两个提供者时会发生冲突。使用 dig.Name 显式区分：

c.Provide(NewPrimaryDB,  dig.Name("primary"))
c.Provide(NewReadOnlyDB, dig.Name("readonly"))

消费时，在 dig.In 字段上添加 name:"primary" 或 name:"readonly" 标签即可。

值组

多个提供者，一个消费者接收切片 —— 典型适用于 HTTP 处理器、健康检查、数据库迁移等场景：

type RouteResult struct {
    dig.Out
    Handler http.Handler `group:"routes"`
}

func NewUserHandler(db *sql.DB) RouteResult { /* ... */ }
func NewPostHandler(db *sql.DB) RouteResult { /* ... */ }

type ServerParams struct {
    dig.In
    Routes []http.Handler `group:"routes"`
}

Flatten（展平） —— 在标签末尾追加 ,flatten（例如 group:"routes,flatten"），可将切片解包而非嵌套。值组中元素的顺序不保证；若顺序敏感（如中间件链、迁移序列），应由单个构造函数显式提供有序切片。

以接口方式提供（dig.As）

注册一个具体类型的构造函数，并直接将其暴露为一个或多个接口，无需额外编写适配器：

c.Provide(NewPostgresDB, dig.As(new(Database), new(io.Closer)))
// 消费者可按需请求 Database 或 io.Closer；*PostgresDB 实现细节对外隐藏。

完整应用示例

func main() {
    c := dig.New()

    must(c.Provide(NewConfig))
    must(c.Provide(NewLogger))
    must(c.Provide(NewDatabase))
    must(c.Provide(NewServer))

    err := c.Invoke(func(srv *http.Server) error {
        return srv.ListenAndServe()
    })
    if err != nil {
        log.Fatal(err)
    }
}

func must(err error) { if err != nil { panic(err) } }

dig 不内置生命周期管理。若需 OnStart/OnStop 钩子、信号处理及优雅关闭，请使用 fx —— 参见 samber/cc-skills-golang@golang-uber-fx 技能。

关于 Decorate、作用域（Scopes）、可选依赖、错误辅助工具以及可视化（Visualize），请参阅 advanced.md。

最佳实践

1. 将容器保留在组合根（composition root）—— 切勿将 *dig.Container 作为参数传递；应视其为 main() 函数内部的“管道细节”。服务定位器（Service Locator）模式会削弱 DI 带来的可测试性优势。
2. 依赖接口而非具体类型 —— 这使你能在测试中无缝替换实现，而无需修改生产代码；也便于使用 dig.As 从宽泛结构体中暴露窄接口。
3. 当构造函数依赖项达 4 个及以上时，优先采用参数对象（dig.In 结构体）—— 调用点保持清晰易读，新增依赖只需一行字段定义，无需破坏函数签名。
4. 按模块分组注册依赖 —— 每个模块对应一个独立文件，其中集中调用 c.Provide 注册本模块所需类型。这使审查与重构成为模块级职责，未来也可轻松将模块迁移到 fx.Module 而无需重写依赖配置逻辑。
5. 在测试中尽早验证依赖图 —— 在 CI 中对组合根调用 c.Invoke，确保缺失提供者问题在启动阶段即暴露，而非首次请求时才浮现。DryRun(true) 可跳过构造函数实际执行，仅做静态校验。
6. 构造函数应返回错误而非 panic —— dig 会自动将错误包装并附带完整的依赖路径，从而明确失败根源。

常见错误

测试

dig 容器开销极低 —— 推荐为每个测试构建全新容器，通过 Decorate 替换特定提供者，并调用 Invoke 驱动整个系统。关于完整测试模式（按测试粒度配置依赖、共享辅助函数、CI 中依赖图校验、断言依赖注入阶段错误、恢复构造函数 panic），请参阅 testing.md。

延伸阅读

• advanced.md —— Decorate、作用域（Scopes）、可选依赖、错误辅助工具、可视化（Visualize）、完整速查表（Quick Reference）
• recipes.md —— 端到端示例：带路由组的 HTTP 服务器、双数据库配置、请求作用域、装饰器、dry-run 校验
• testing.md —— 测试模式与依赖图校验方法

交叉引用

• → 参见 samber/cc-skills-golang@golang-uber-fx 技能，了解基于 dig 构建的应用生命周期管理、模块系统与信号感知型 Run()
• → 参见 samber/cc-skills-golang@golang-dependency-injection 技能，了解 DI 核心概念与主流库横向对比
• → 参见 samber/cc-skills-golang@golang-samber-do 技能，了解一种基于泛型、无需反射的 DI 替代方案
• → 参见 samber/cc-skills-golang@golang-google-wire 技能，了解编译期 DI（无运行时容器）
• → 参见 samber/cc-skills-golang@golang-structs-interfaces 技能，了解接口设计模式
• → 参见 samber/cc-skills-golang@golang-testing 技能，了解通用测试模式

若你在使用 uber-go/dig 时遇到 Bug 或非预期行为，请在 https://github.com/uber-go/dig/issues 提交 Issue。