Go Wire 循环依赖:接口为什么定义在消费方
给用户服务加一个权限查询,给权限服务加一个用户信息读取,代码都能编译,wire check 却直接拒绝生成:
wire: cycle for *PermissionService:
*PermissionService (NewPermissionService) ->
*UserService (NewUserService) ->
*PermissionService
这不是 Wire 的毛病,而是依赖图里真的出现了环。手工写初始化代码时,环可能被一个延迟赋值或全局变量掩盖;一旦交给编译期依赖注入,环就无处可藏。
本文用 Wire v0.6.0 的最小复现说明环是怎么形成的,再对照项目里的拆法:把只读接口定义在消费方,提供方只负责绑定实现。
最小复现:两个服务互相要对方
两个服务各自需要对方,构造函数互相引用:
type UserService struct {
perm *PermissionService
}
type PermissionService struct {
user *UserService
}
func NewUserService(p *PermissionService) *UserService {
return &UserService{perm: p}
}
func NewPermissionService(u *UserService) *PermissionService {
return &PermissionService{user: u}
}
Wire 注入点:
func InitApp() *UserService {
wire.Build(NewUserService, NewPermissionService)
return nil
}
运行 wire check .,输出:
wire: cycle for *PermissionService:
*PermissionService (NewPermissionService) ->
*UserService (NewUserService) ->
*PermissionService
依赖图是 PermissionService → UserService → PermissionService,任何一方先构造都需要另一方已经存在。调换 wire.Build 里的顺序没有用,依赖注入解决的是构造顺序,不是构造环。
业务里为什么会长出这个环
项目里的依赖关系不是凭空写的,而是两个需求叠出来的:
- 用户服务要校验权限,所以依赖
PermissionService; - 权限服务要按用户查询角色和数据范围,所以依赖用户信息。
真实构造函数更接近这样:
type userService struct {
userRepo repository.UserRepository
permissionSvc permissionSvc.PermissionService
// ...
}
func NewUserService(
userRepo repository.UserRepository,
permissionSvc permissionSvc.PermissionService,
// ...
) UserService
type permissionService struct {
userApi api.AdminUserApi
// ...
}
PermissionService 需要的不是用户的全部业务能力,只是“按 ID 查用户”和“按 ID 批量查用户”。把整个 UserService 注进去,等于把用户模块的所有方法都暴露给权限模块,也让依赖图形成一个闭环。
拆法:给消费方一个只读接口
项目没有把 UserService 拆成两半,而是增加了一个只读 API:
// UserApi 用户信息只读接口
// 仅依赖仓储层,供其他模块跨模块读取用户数据,避免与用户业务服务形成循环依赖
type UserApi interface {
GetUser(ctx context.Context, id int64) (*domain.SystemUser, error)
GetUserMap(ctx context.Context, ids []int64) (map[int64]*domain.SystemUser, error)
}
type userApi struct {
userRepo repository.UserRepository
}
func NewUserApi(userRepo repository.UserRepository) UserApi {
return &userApi{userRepo: userRepo}
}
它只依赖仓储,不依赖权限服务,所以构造它不会反向要求 PermissionService。权限模块依赖接口:
type permissionService struct {
userApi api.AdminUserApi
}
接口放在中立的 internal/api 包里,方法由消费方按需要挑选。这里的关键不是“接口必须写在调用方的文件名里”,而是“接口的方法集合由消费方决定,而不是把提供方的完整服务接口直接搬过来”。
Wire 里怎么把接口和实现接上
接口是 api.AdminUserApi,实现是 userSvc.UserApi,两者名字不同,Wire 不会自动猜。需要显式绑定:
userSvc.NewUserApi,
wire.Bind(new(api.AdminUserApi), new(userSvc.UserApi)),
wire.Bind 的第一个参数是接口类型标记,第二个参数是实现类型标记。绑定后,任何请求 api.AdminUserApi 的地方都会拿到 NewUserApi 的返回值。
依赖链变成:
UserService → PermissionService → api.AdminUserApi → UserRepository
UserService 仍然依赖权限服务,但权限服务不再回头依赖 UserService,环被切断。用户模块内部需要权限服务时继续用具体接口,跨模块只读数据时走 API,两个方向分开。
接口该定义在哪一侧
这个问题经常被简化成“接口定义在消费方”,但实际判断要看依赖方向和稳定性:
| 场景 | 接口位置 | 原因 |
|---|---|---|
| 跨模块只读数据 | 中立 common/api,按消费方需要裁剪 | 提供方不反向依赖消费方,接口方法少且稳定 |
| 同一模块内业务协作 | 模块自己的 service 接口 | 方法与业务语义强相关,不适合跨模块暴露 |
| 需要替换实现 | 消费方定义最小接口 | 消费方只关心自己用到的方法,测试也容易替换 |
| 框架扩展点 | 框架或公共包定义 | 多个实现共享同一契约 |
只读 API 适合“按 ID 查数据”这类稳定操作。如果消费方需要的是“冻结用户”“重置密码”这类业务动作,就不该硬塞进只读接口,应该重新划分模块边界,而不是把接口越扩越大。
另一个坑:wire.Bind 对结构体指针不生效
项目里还遇到过这种写法:
wire.Bind(new(api.ContentSecurityApi), new(commonSecurity.Service))
commonSecurity.Service 是一个结构体,实际提供者返回的是 *commonSecurity.Service。wire.Bind 的第二个参数需要的是“能被赋给接口的类型”,结构体值本身不实现指针接收者定义的方法,绑定不会按预期工作。
正确做法是加一个显式 provider,让返回值类型就是接口:
func provideContentSecurityApi(svc *commonSecurity.Service) api.ContentSecurityApi {
return svc
}
然后把 provideContentSecurityApi 放进 ProviderSet。wire.Bind 适合“接口 → 实现接口的具体类型”,当构造函数返回的是结构体指针、接口方法又定义在指针接收者上时,显式 provider 更直观,也更容易被 Wire 正确解析。
验证:wire check 与启动测试
改完依赖后,先跑静态检查:
wire check ./cmd/api
没有输出就是通过。再生成一次代码,确认 wire_gen.go 的改动符合预期:
wire gen ./cmd/api
go test ./...
wire check 只能证明依赖图能构造,不能证明业务正确。至少再启动一次服务,确认路由注册、数据库连接和定时任务都能正常初始化;有集成测试的模块跑一遍相关用例。
边界与常见错误
- 循环依赖不是“把两个构造函数换个顺序”能解决的,必须改变依赖方向或抽小接口。
- 只读 API 不要暴露
Update、Delete这类写方法,否则消费方会绕过业务规则直接改数据。 UserApi里的查询要显式忽略数据权限(项目里用gormx.SetIgnoreDataPermission),否则跨模块按 ID 拼接数据时可能查不到用户。- 接口方法越多,绑定越难替换。按消费方实际使用的方法裁剪,不要复制整个服务接口。
wire.Bind的两个参数都必须是类型标记,不能传变量或实例;结构体指针与接口的匹配问题优先用 provider 函数解决。
相关工具
需要生成或对照接口结构时,可以用 JSON 代码生成工具 把请求结构转成 Go 类型;Gin 项目的基础分层和启动流程见 Gin 入门笔记,更多后端设计文章在 后端开发分类。
FAQ
Wire 报循环依赖,能不能用 wire.Value 或全局变量绕过去?
能绕过检查,但只是把环藏起来。运行时仍然会出现初始化顺序问题,测试也更难替换依赖。优先改依赖方向。
为什么不让 PermissionService 直接依赖 UserRepository?
仓储属于用户模块的内部实现,权限模块直接依赖它会把两个模块的数据访问耦合在一起。只读 API 只暴露稳定的查询语义,后续用户表结构调整时影响更小。
接口一定要放在 common/api 吗?
不一定。放在消费方自己的包里也可以,只要提供方能引用到、且不形成反向依赖。项目选 common/api 是为了让多个模块共享同一组跨模块契约。
wire check 通过就说明没有循环依赖了吗?
它说明当前 ProviderSet 能构造出所有依赖。动态注册、运行时反射创建的依赖不在检查范围内,仍需要启动验证。
结语:Wire 的循环依赖报错是好事,它把手工初始化时隐藏的环提前暴露了。把跨模块读取收窄成只读接口,用 wire.Bind 绑定实现,依赖图就能保持单向。
Comments
No comments yet — be the first to say something