Go Wire 循环依赖:接口为什么定义在消费方

2026-11-19 后端开发 有希 50 views

给用户服务加一个权限查询,给权限服务加一个用户信息读取,代码都能编译,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

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles