角色：你是一位 Go 架构师，正在搭建依赖注入系统。你将容器保留在组合根（composition root）处，依赖接口而非具体类型，并将提供者（provider）错误视为一等公民级的失败。

在 Go 中使用 samber/do 实现依赖注入

基于 Go 1.18+ 泛型构建的类型安全依赖注入工具包。

官方资源：

• pkg.go.dev/github.com/samber/do/v2
• do.samber.dev
• github.com/samber/do/v2

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

请勿使用该库的 v1 版本，请安装 v2 版本：

go get -u github.com/samber/do/v2

核心概念

注入器（容器）

import "github.com/samber/do/v2"

injector := do.New()

服务类型

• Lazy（默认）：首次请求时创建
• Eager：容器启动时立即创建
• Transient：每次请求均创建新实例
• Value：预创建的值，无需实例化

提供者函数

服务必须通过提供者函数注册：

type Provider[T any] func(i Injector) (T, error)

基础用法

1. 定义并注册服务

遵循“接受接口，返回结构体”原则：

// 注册服务（默认为 lazy）
do.Provide(injector, func(i do.Injector) (Database, error) {
    return &PostgreSQLDatabase{connString: "postgres://..."}, nil
})

// 注册预创建的值
do.ProvideValue(injector, &Config{Port: 8080})

// 注册 transient 服务（每次调用均新建实例）
do.ProvideTransient(injector, func(i do.Injector) (*Logger, error) {
    return &Logger{}, nil
})

// 注册 eager 服务（启动时立即创建）
do.ProvideValue(injector, &Config{Port: 8080})

2. 获取服务

容器仅应在组合根处被访问：

// 带错误处理地获取服务
db, err := do.Invoke[Database](injector)

// MustInvoke 在出错时 panic（适用于确信服务一定存在的情形）
db := do.MustInvoke[Database](injector)

3. 服务依赖

func NewUserService(i do.Injector) (UserService, error) {
    db := do.MustInvoke[Database](i)
    cache := do.MustInvoke[Cache](i)
    return &userService{db: db, cache: cache}, nil
}

do.Provide(injector, NewUserService)

4. 隐式别名（推荐方式）

注册具体类型后，可直接以接口类型获取，无需显式别名：

// 注册具体类型
do.Provide(injector, func(i do.Injector) (*PostgreSQLDatabase, error) {
    return &PostgreSQLDatabase{}, nil
})

// 直接以接口类型获取（隐式别名）
db := do.MustInvokeAs[Database](injector)

5. 命名服务

注册同一类型的多个服务：

do.ProvideNamed(injector, "primary-db", func(i do.Injector) (*Database, error) {
    return &Database{URL: "postgres://primary..."}, nil
})

mainDB := do.MustInvokeNamed[*Database](injector, "primary-db")

包组织方式

使用 do.Package() 按模块组织服务注册：

// infrastructure/package.go
var Package = do.Package(
    do.Lazy(func(i do.Injector) (*postgres.DB, error) {
        cfg := do.MustInvoke[*Config](i)
        return postgres.Connect(cfg.DatabaseURL)
    }),
    do.Lazy(func(i do.Injector) (*redis.Client, error) {
        cfg := do.MustInvoke[*Config](i)
        return redis.NewClient(cfg.RedisURL), nil
    }),
)

// main.go
injector := do.New(infrastructure.Package, service.Package)

完整应用初始化

func main() {
    injector := do.New(
        infrastructure.Package,
        repository.Package,
        service.Package,
        transport.Package,
    )

    server := do.MustInvoke[*http.Server](injector)
    go server.ListenAndServe()

    _ = injector.ShutdownOnSignalsWithContext(context.Background(), os.Interrupt)
}

最佳实践

1. 依赖接口而非具体类型——这使你能在测试中替换实现，而无需修改生产代码
2. 每个服务应只承担单一职责——职责过多的服务更难测试、也更难替换
3. 保持依赖树扁平——超过 3–4 层的依赖链会使初始化顺序变得脆弱，且错误更难追踪
4. 在提供者函数中妥善处理错误——静默失败的提供者会导致服务处于损坏状态，进而在意想不到的位置引发崩溃
5. 使用作用域（scopes）按生命周期组织服务——请求作用域（request-scoped）服务可防止内存泄漏，全局作用域（global）服务可避免重复初始化

关于作用域、生命周期管理、结构体注入及调试，请参阅《高级用法》。

关于测试模式（克隆、覆盖、模拟），请参阅《测试》。

速查表

注册

获取

交叉引用

• → 查看 samber/cc-skills-golang@golang-dependency-injection 技能，了解 DI 核心概念、方案对比以及何时引入 DI 库
• → 查看 samber/cc-skills-golang@golang-structs-interfaces 技能，了解接口设计模式
• → 查看 samber/cc-skills-golang@golang-testing 技能，了解通用测试模式