角色：你是一位使用 wire 实现编译期依赖注入（DI）的 Go 架构师。你依赖编译器捕获缺失依赖，将 wire_gen.go 视为已提交的源码，并在每次依赖图变更后重新运行 wire ./...。

依赖项：

• wire：go install github.com/google/wire/cmd/wire@latest

在 Go 中使用 google/wire 实现编译期依赖注入

一种基于代码生成的 DI 工具包。wire 在编译期解析依赖图，并生成标准 Go 构造函数调用——不依赖运行时容器，也不使用反射。错误会在你执行 wire ./... 时暴露，而非在首次请求时才出现。

注意：google/wire 已于 2025 年 8 月归档（功能已完成；仍接受 Bug 修复）。

官方资源：pkg.go.dev · github.com/google/wire · 用户指南 · 最佳实践

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

go get -tool github.com/google/wire/cmd/wire@latest
go get github.com/google/wire

wire 与运行时 DI 对比

有关生命周期管理、懒加载及完整能力矩阵，请参阅 samber/cc-skills-golang@golang-dependency-injection。

Provider（提供者）

Provider 是任意 Go 函数：输入参数为依赖项，返回值为被提供的类型。支持三种返回形式：

func NewConfig() *Config                          { return &Config{Addr: ":8080"} }
func NewDB(cfg *Config) (*sql.DB, error)          { return sql.Open("postgres", cfg.DSN) }
func NewRedis(cfg *Config) (*redis.Client, func(), error) { // 清理函数按逆序链式调用
    c := redis.NewClient(&redis.Options{Addr: cfg.RedisAddr})
    return c, func() { c.Close() }, nil
}

Provider Set（提供者集合）

wire.NewSet 将多个 Provider 组合以供复用。集合之间可相互引用。

// infra/wire.go
var InfraSet = wire.NewSet(
    NewConfig,
    NewDB,
    NewRedis,
)

// service/wire.go
var ServiceSet = wire.NewSet(
    NewUserRepo,
    NewUserService,
    wire.Bind(new(UserStore), new(*UserRepo)), // 接口绑定
)

保持集合粒度细小：库级集合应暴露稳定接口（增加输入或移除输出均会破坏下游注入器）。每包一个集合是实用的默认约定。

Injector（注入器）与 //go:build wireinject

注入器文件声明初始化函数。Wire 将其函数体生成到 wire_gen.go 中，并替换原始存根。

//go:build wireinject

package main

import "github.com/google/wire"

// Wire 生成该函数的函数体。
func InitApp() (*App, func(), error) {
    wire.Build(InfraSet, ServiceSet, NewApp)
    return nil, nil, nil // 由代码生成器替换
}

//go:build wireinject 构建标签防止该存根文件被编译进二进制——仅 wire_gen.go（不含此标签）能通过 go build 编译。若缺少该标签，则两个文件均定义同名函数，导致编译错误。

当存根返回值写法不便时，可采用替代语法：

func InitApp() (*App, func(), error) {
    panic(wire.Build(InfraSet, ServiceSet, NewApp))
}

接口绑定（Interface Bindings）

Wire 禁止隐式接口实现——你必须显式声明绑定，确保当多个类型实现同一接口时，依赖图依然明确无歧义。

var Set = wire.NewSet(
    NewPostgresUserRepo,
    wire.Bind(new(UserStore), new(*PostgresUserRepo)), // 告知 Wire：*PostgresUserRepo 满足 UserStore 接口
)

显式绑定可避免因其他位置新增同接口实现类型而导致依赖图意外中断。

结构体 Provider 与值注入

wire.Struct 可直接从依赖图填充结构体字段，无需手动编写构造函数。使用 wire:"-" 标签可排除特定字段。

wire.Struct(new(Server), "Logger", "DB") // 注入指定命名字段
wire.Struct(new(Server), "*")            // 注入所有未被排除的字段
wire.Value(Foo{X: 42})                   // 常量表达式（禁止函数调用 / channel 操作）
wire.InterfaceValue(new(io.Reader), os.Stdin) // 接口类型字面量
wire.FieldsOf(new(Config), "DSN", "Addr")    // 将结构体字段提升为依赖图节点

关于 wire:"-" 排除标签与 wire.FieldsOf 的详细说明，请参阅 advanced.md。

区分重复类型（Disambiguating Duplicate Types）

Wire 禁止为同一类型注册两个 Provider。可通过为底层类型定义不同的具名类型，使每个类型恰好对应一个 Provider：

type PrimaryDSN string
type ReplicaDSN string

完整应用示例

// wire.go — 注入器文件，通过构建标签排除在二进制之外
//go:build wireinject

package main

func InitApp() (*App, func(), error) {
    wire.Build(config.ConfigSet, infra.InfraSet, service.ServiceSet, NewApp)
    return nil, nil, nil
}

// main.go
func main() {
    app, cleanup, err := InitApp()
    if err != nil { log.Fatal(err) }
    defer cleanup()
    app.Run()
}

Wire 会生成 wire_gen.go（纯 Go 代码，需提交，切勿手动编辑）。含分包 Provider Set、复杂清理逻辑及生成结果的完整示例，请参阅 recipes.md。

代码生成工作流

wire ./...           # 为模块中所有注入器重新生成代码
wire check ./...     # 验证依赖图但不生成代码（适用于快速 CI 检查）

每次构造函数签名变更后都需运行 wire ./...。可在注入器文件顶部添加 //go:generate go run github.com/google/wire/cmd/wire，以便 go generate ./... 同样生效。务必提交 wire_gen.go——它必须与源码保持同步，以保障 CI 构建成功。

最佳实践

1. 切勿手动编辑 wire_gen.go——该文件会在每次 wire ./... 运行时被完全覆盖。应将其视为已提交的构建产物；真实可信来源是 Provider 和注入器文件。
2. 务必为所有注入器文件添加 //go:build wireinject 标签——遗漏会导致符号重复的编译错误（存根与生成文件同时定义了相同函数）。
3. 使用具名类型区分相同底层类型的值——Wire 强制要求每种类型至多一个 Provider；例如 type DSN string 可让你共存 PrimaryDSN 与 ReplicaDSN。
4. 保持库级 Provider Set 尽可能精简且向后兼容——新增必需输入参数会破坏下游注入器；移除输出亦然。仅在同一版本中引入全新类型。
5. 清理型 Provider 应返回 (T, func(), error)，交由 Wire 自动链式调用——Wire 会生成正确逆序的清理逻辑，并妥善处理部分失败场景（若构造中途失败，仅已成功构造对象的清理函数会被执行）。
6. 保持注入器文件职责单一——每文件一个函数，一次只导入一个包。包含数十个 wire.Build 参数的臃肿注入器难以理解；应委托给各包专属的 Provider Set。

常见错误

测试

Wire 生成的是标准 Go 构造函数，因此单元测试采用手动注入——无需克隆或重置容器。关于测试模式（如用 fake Provider 替换真实 Provider 的测试注入器、CI 中检查 wire_gen.go 是否过期），请参阅 testing.md。

延伸阅读

• advanced.md —— 清理链、多注入器、集合嵌套、错误分类、代码生成标志、速查表
• recipes.md —— HTTP 服务、多注入器构建、高清理负载依赖图、CLI 嵌入
• testing.md —— 测试注入器、fake 绑定、CI 过期检查

交叉引用

• → 参阅 samber/cc-skills-golang@golang-dependency-injection 技能，了解 DI 概念与各库对比
• → 参阅 samber/cc-skills-golang@golang-uber-dig 技能，了解无生命周期管理的运行时反射型 DI
• → 参阅 samber/cc-skills-golang@golang-uber-fx 技能，了解支持生命周期钩子、模块化及信号感知 Run() 的运行时 DI
• → 参阅 samber/cc-skills-golang@golang-samber-do 技能，了解基于泛型、无需反射的 DI
• → 参阅 samber/cc-skills-golang@golang-structs-interfaces 技能，了解接口设计模式
• → 参阅 samber/cc-skills-golang@golang-testing 技能，了解通用测试模式

如在使用 google/wire 时遇到 Bug 或异常行为，请在 https://github.com/google/wire/issues 提交 Issue。