Go 接口放哪:提供方管契约,调用方只要窄角色

Go 接口放哪:提供方管契约,调用方只要窄角色

Hello,我是小兔大白糖。 评审里常听到一句:「接口应该定义在调用方」——口号很干净,落到 Go 单体或多包服务里,却常常变成:每个业务包复制一套 UserService,改一个方法要改 N 处,mock 也跟着散。写成这篇,给要做依赖边界与接口归属调研的初中级后端同学:不是某仓库的改造工单,而是业界可复述的心智模型。

说明:下文的模式名与伪代码均为教学脱敏示意,不是某开源 IM 或某公司的包路径说明书。读完带走的是「谁拥有契约、谁依赖窄角色」,不是可粘贴的内部框架。

估计阅读时间:10 分钟


目录


为什么现在要关心

硬规则先钉三条:稳定契约优先放提供方(或双方共享的契约包);依赖的是角色,不是上帝服务;重复定义同一语义接口 ≠ 解耦。

另一边极端也不少见:提供方甩出一个「什么都能干」的大接口,调用方只想「查用户名」,却被迫依赖「改密码 / 删号」整盘 API。

你听到的口号现场常见痛点
「调用方定义接口」多处复制;实现方不知道该满足谁;签名一改全仓漂移
「提供方定义大接口」调用方过耦合;测试难只 mock 一小块
「完全面向接口」接口爆炸;没有实现方归属,演进没人签字

和「ctx 跟请求走」一样——口号要对上作用域与所有权,不能背成教条。请求级取消怎么传,见 /blog/go_context_pass_not_store/;本文只钉一件事:接口写在哪,取决于谁负责演进,以及调用方真正需要多宽。


问题空间:两件被揉成一句的事

「接口放哪」其实是两件事;揉成一句口号,后面就会用教条代替所有权。

常被揉成一句实际要答的问题
「接口定义在调用方」契约归属:谁拥有并演进 API 形状?谁改签名负责通知谁?
「面向接口编程」依赖隔离:调用方怎样只依赖自己用到的方法?
「依赖倒置(DIP)」高层不直接绑死低层具体类型;双方依赖抽象——抽象放哪仍要单独定

合法两种故事要分开写:

  1. 契约归属故事:实现归提供方;稳定、跨包复用的形状,优先放提供方或 contracts 一类共享包。
  2. 依赖隔离故事:调用方构造函数只收自己用到的窄角色(ISP,接口隔离)——这是「依赖多宽」,不是「再抄一份接口」。

后端选型里「横切约定靠样板还是靠框架」,见 /blog/go_vs_java_backend_choice/。接口归属同样是横切:错放位置,账单是漂移与 mock 成本,不是编译器立刻红灯。


心智模型:插座 vs 窄插头

主比喻:墙上的标准插座,和设备侧只要「两脚供电」的窄插头。

  • 提供方接口 / 共享契约包 ≈ 墙上标准插座——供电规格由供电方(或双方约定的标准)维护。
  • 调用方声明的窄角色 ≈ 设备只要的最小插头形状——声明「我只要读用户」,不要整盘运维 API。
  • 适配 ≈ 大实现满足小插头——Go 里具体类型隐式实现小接口,组装根把大实现塞进窄依赖。
提供方契约插座与调用方窄角色插头
提供方契约插座与调用方窄角色插头 · 点击查看 SVG 原图

类比局限一句说清:插座类比解释「所有权 + 窄依赖」;解释不了跨进程 RPC——那是 protobuf / OpenAPI 等 IDL 契约,另一层合同。


精确定义:契约归属与角色接口

进程内 Go interface 管的是编译期形状与测试缝;跨服务边界的版本合同,通常另有 IDL。

再钉几条边界:

说法对不对人话
稳定、多调用方共享的业务能力 → 契约放提供方或共享契约包对有人签字演进
调用方只依赖自己用到的 3~7 个方法的角色接口对(经验区间)ISP:要 UserReader,别默认要整个 UserService
每个调用包装一份同名接口 = 解耦勋章错重复定义是漂移源
标准库式「小角色抽象」可放共享包(如 io.Reader)对无单一业务域所有权时,共享角色包很常见
跨进程只靠 Go interface、无 IDL 版本合同错进程内缝 ≠ 服务间合同

业界常见归纳(非某厂内幕):Go 社区强调小接口与「接受接口、返回具体类型」一类公开叙述;业务领域服务更常「实现归提供方,角色接口可共享」。两者不矛盾:标准库式抽象往往没有单一业务域所有权;业务服务有明确所有权——所有权在,契约就不宜在每个调用包各抄一份。


模式对照:四种常见做法

多数业务单体 / 模块化单体,主线是「提供方实现 + 窄角色契约」;另三种各有适合面与代价。

Go 接口归属模式 A B C D 对照
Go 接口归属模式 A B C D 对照 · 点击查看 SVG 原图
模式做法适合代价 / 边界
A. 提供方大接口完整 UserService 定义在 user 域包同域内实现清晰、调用方也在同域易滑成上帝接口;跨域注入后测试与耦合变重
B. 调用方各定义一套每个消费包自己 type UserAPI interface{…}极窄、一次性、提供方形状不稳定重复与漂移;实现方不知道该满足谁
C. 提供方(或 contracts)+ 角色切片(推荐主线)提供方实现完整能力;契约包导出 UserReader / ChatUpdater;调用方只依赖窄接口多数业务单体 / 模块化单体要治理契约包,防变成 DTO 垃圾桶
D. 仅 IDL跨服务只靠 proto / OpenAPI微服务边界、多语言进程内仍常要 Go interface 做测试缝与本地适配

实践上很少「只选一个」:跨服务用 D 钉版本合同;进程内用 C 做依赖与测试;A 留在域内实现面;B 仅在「真的没有稳定提供方」时短用,并接受漂移账单。

代价先说清:角色切太碎 → 接口文件与 wiring 噪声上升;切太粗 → 又回到上帝接口。稳的是按真实调用面切片,不是按口号「接口越多越整洁」。


可复述做法与组装

五步可复述:完整 API 归提供方 → 抽出窄角色 → 调用方只收角色 → 组装根注入大实现 → 测试只 mock 角色。

  1. 提供方保留完整服务 API(给本域用)。
  2. 抽出调用方真正用到的方法,成角色接口;放契约包,或提供方导出的小接口文件。
  3. 调用方构造函数只收角色接口。
  4. 组装根(main / wire 一类)传入具体实现——大实现满足小接口。
  5. 测试只 mock 角色接口,不为「整盘上帝服务」编剧本。
大实现经窄接口注入调用方
大实现经窄接口注入调用方 · 点击查看 SVG 原图

教学伪流程(脱敏,非生产 API;只说明归属与组装顺序):

# provider owns full API; contracts export narrow roles
UserReader   { GetByID; ListByIDs }
ChatUpdater  { TouchLastMessage }

MessageService(deps: UserReader, ChatUpdater)

# wiring: concrete UserService / ChatService satisfy roles

再给一段极短 Go 示意(教学,非框架粘贴):

type UserReader interface {
    GetByID(ctx context.Context, id string) (User, error)
}
 
func NewMessageService(users UserReader) *MessageService {
    return &MessageService{users: users}
}

副作用也写清:窄接口要求组装根诚实接线;漏接或接口改了一半,编译器帮得有限。换来的是漂移面变小、单测缝变窄——这是账单,不是「最佳实践」空喊。


反模式

从架构视角看,下面几条会把「归属」和「隔离」重新揉坏。

  1. 每个调用包复制同一语义接口
    看起来「调用方定义」了,实际是 N 份漂移源。实现方改一处,通知链断裂。

  2. 注入完整上帝接口,「以后也许用得到」
    测试与耦合账单立刻到期。ISP 要的是当前真实调用面,不是未来幻想。

  3. 契约包变成所有 DTO 的垃圾桶
    谁都可以扔,谁都不愿清。契约包要有所有权与准入,否则模式 C 退化成新的大泥球。

  4. 把「调用方定义」当成教条,忽略所有权
    无稳定提供方时,小接口在使用侧说得通;有明确域所有权时,复制不是勋章。

  5. 跨进程仍只靠 Go interface
    没有 IDL / 版本合同,多语言与多仓协作靠口头对齐——排障时才发现「形状以为一样」。

  6. 为面向接口而面向接口
    没有第二实现、没有测试缝需求,却先抽空接口——噪声上升,收益接近零。


选型结论

  1. 先问所有权:谁改方法签名负责通知谁;稳定契约优先提供方或共享契约包。
  2. 进程内主线:提供方实现完整能力 + 调用方只依赖窄角色接口(模式 C);大实现在组装根满足小接口。
  3. 「调用方定义」有边界:适用于无稳定提供方所有权的抽象,或一次性极窄缝;业务服务慎用多包复制。
  4. 跨服务用 IDL:Go interface 做进程内依赖与测试缝,不替代服务间版本合同。
  5. 治理契约包:防 DTO 垃圾桶;角色按真实调用面切,接受 wiring 与碎片化的代价上限。