
Hello,我是小兔大白糖。 评审里常听到一句:「接口应该定义在调用方」——口号很干净,落到 Go 单体或多包服务里,却常常变成:每个业务包复制一套 UserService,改一个方法要改 N 处,mock 也跟着散。写成这篇,给要做依赖边界与接口归属调研的初中级后端同学:不是某仓库的改造工单,而是业界可复述的心智模型。
说明:下文的模式名与伪代码均为教学脱敏示意,不是某开源 IM 或某公司的包路径说明书。读完带走的是「谁拥有契约、谁依赖窄角色」,不是可粘贴的内部框架。
估计阅读时间:10 分钟
目录
为什么现在要关心
硬规则先钉三条:稳定契约优先放提供方(或双方共享的契约包);依赖的是角色,不是上帝服务;重复定义同一语义接口 ≠ 解耦。
另一边极端也不少见:提供方甩出一个「什么都能干」的大接口,调用方只想「查用户名」,却被迫依赖「改密码 / 删号」整盘 API。
| 你听到的口号 | 现场常见痛点 |
|---|---|
| 「调用方定义接口」 | 多处复制;实现方不知道该满足谁;签名一改全仓漂移 |
| 「提供方定义大接口」 | 调用方过耦合;测试难只 mock 一小块 |
| 「完全面向接口」 | 接口爆炸;没有实现方归属,演进没人签字 |
和「ctx 跟请求走」一样——口号要对上作用域与所有权,不能背成教条。请求级取消怎么传,见 /blog/go_context_pass_not_store/;本文只钉一件事:接口写在哪,取决于谁负责演进,以及调用方真正需要多宽。
问题空间:两件被揉成一句的事
「接口放哪」其实是两件事;揉成一句口号,后面就会用教条代替所有权。
| 常被揉成一句 | 实际要答的问题 |
|---|---|
| 「接口定义在调用方」 | 契约归属:谁拥有并演进 API 形状?谁改签名负责通知谁? |
| 「面向接口编程」 | 依赖隔离:调用方怎样只依赖自己用到的方法? |
| 「依赖倒置(DIP)」 | 高层不直接绑死低层具体类型;双方依赖抽象——抽象放哪仍要单独定 |
合法两种故事要分开写:
- 契约归属故事:实现归提供方;稳定、跨包复用的形状,优先放提供方或
contracts一类共享包。 - 依赖隔离故事:调用方构造函数只收自己用到的窄角色(ISP,接口隔离)——这是「依赖多宽」,不是「再抄一份接口」。
后端选型里「横切约定靠样板还是靠框架」,见 /blog/go_vs_java_backend_choice/。接口归属同样是横切:错放位置,账单是漂移与 mock 成本,不是编译器立刻红灯。
心智模型:插座 vs 窄插头
主比喻:墙上的标准插座,和设备侧只要「两脚供电」的窄插头。
- 提供方接口 / 共享契约包 ≈ 墙上标准插座——供电规格由供电方(或双方约定的标准)维护。
- 调用方声明的窄角色 ≈ 设备只要的最小插头形状——声明「我只要读用户」,不要整盘运维 API。
- 适配 ≈ 大实现满足小插头——Go 里具体类型隐式实现小接口,组装根把大实现塞进窄依赖。
类比局限一句说清:插座类比解释「所有权 + 窄依赖」;解释不了跨进程 RPC——那是 protobuf / OpenAPI 等 IDL 契约,另一层合同。
精确定义:契约归属与角色接口
进程内 Go interface 管的是编译期形状与测试缝;跨服务边界的版本合同,通常另有 IDL。
再钉几条边界:
| 说法 | 对不对 | 人话 |
|---|---|---|
| 稳定、多调用方共享的业务能力 → 契约放提供方或共享契约包 | 对 | 有人签字演进 |
| 调用方只依赖自己用到的 3~7 个方法的角色接口 | 对(经验区间) | ISP:要 UserReader,别默认要整个 UserService |
| 每个调用包装一份同名接口 = 解耦勋章 | 错 | 重复定义是漂移源 |
标准库式「小角色抽象」可放共享包(如 io.Reader) | 对 | 无单一业务域所有权时,共享角色包很常见 |
| 跨进程只靠 Go interface、无 IDL 版本合同 | 错 | 进程内缝 ≠ 服务间合同 |
业界常见归纳(非某厂内幕):Go 社区强调小接口与「接受接口、返回具体类型」一类公开叙述;业务领域服务更常「实现归提供方,角色接口可共享」。两者不矛盾:标准库式抽象往往没有单一业务域所有权;业务服务有明确所有权——所有权在,契约就不宜在每个调用包各抄一份。
模式对照:四种常见做法
多数业务单体 / 模块化单体,主线是「提供方实现 + 窄角色契约」;另三种各有适合面与代价。
| 模式 | 做法 | 适合 | 代价 / 边界 |
|---|---|---|---|
| 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 角色。
- 提供方保留完整服务 API(给本域用)。
- 抽出调用方真正用到的方法,成角色接口;放契约包,或提供方导出的小接口文件。
- 调用方构造函数只收角色接口。
- 组装根(
main/ wire 一类)传入具体实现——大实现满足小接口。 - 测试只 mock 角色接口,不为「整盘上帝服务」编剧本。
教学伪流程(脱敏,非生产 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}
}副作用也写清:窄接口要求组装根诚实接线;漏接或接口改了一半,编译器帮得有限。换来的是漂移面变小、单测缝变窄——这是账单,不是「最佳实践」空喊。
反模式
从架构视角看,下面几条会把「归属」和「隔离」重新揉坏。
-
每个调用包复制同一语义接口
看起来「调用方定义」了,实际是 N 份漂移源。实现方改一处,通知链断裂。 -
注入完整上帝接口,「以后也许用得到」
测试与耦合账单立刻到期。ISP 要的是当前真实调用面,不是未来幻想。 -
契约包变成所有 DTO 的垃圾桶
谁都可以扔,谁都不愿清。契约包要有所有权与准入,否则模式 C 退化成新的大泥球。 -
把「调用方定义」当成教条,忽略所有权
无稳定提供方时,小接口在使用侧说得通;有明确域所有权时,复制不是勋章。 -
跨进程仍只靠 Go interface
没有 IDL / 版本合同,多语言与多仓协作靠口头对齐——排障时才发现「形状以为一样」。 -
为面向接口而面向接口
没有第二实现、没有测试缝需求,却先抽空接口——噪声上升,收益接近零。
选型结论
- 先问所有权:谁改方法签名负责通知谁;稳定契约优先提供方或共享契约包。
- 进程内主线:提供方实现完整能力 + 调用方只依赖窄角色接口(模式 C);大实现在组装根满足小接口。
- 「调用方定义」有边界:适用于无稳定提供方所有权的抽象,或一次性极窄缝;业务服务慎用多包复制。
- 跨服务用 IDL:Go interface 做进程内依赖与测试缝,不替代服务间版本合同。
- 治理契约包:防 DTO 垃圾桶;角色按真实调用面切,接受 wiring 与碎片化的代价上限。