接口契约变更到底要不要走版本号？聊聊我见过的三种流派

背景

我 3 年中间件研发下来，发现团队里对「接口变更要不要上版本号」这个问题，几乎没有两个团队答案一样。有的团队所有接口永远 /v1，改字段就加个 Deprecated 硬扛三年；有的团队每个新需求都开一个 /v2、/v3，网关上挂了一堆同名字段不同版本的接口；还有一种是「能兼容就兼容、不兼容就硬改、下游自己改」的野生流派。三种做法都能活，但维护成本、事故率、新人上手曲线差别非常大。

我自己在中间件侧接口的经验是：网关层、开放平台、跨团队 RPC 这三类接口，我倾向于强制走语义化版本 + 兼容期；而内部微服务之间、同一个 owner 的接口，我反而反对动不动开 v2——因为版本一多，回归测试矩阵和 mock 维护成本是指数级上涨的，很多 v2 上线半年就没人调了，反而成了垃圾接口。

三种流派和他们的痛点

1. 永久 v1 派：优点是下游零迁移成本，缺点是接口字段只增不减、语义漂移，最后没人敢删老字段，接口变成一个巨型对象。
2. 激进 v2 派：优点是契约清晰、破坏性变更有明确边界，缺点是接口爆炸、网关路由复杂、mock 和文档维护量翻倍。
3. 野生派：优点是灵活，缺点是下游永远在追上游的变更，联调返工率高，事故追溯时责任扯皮。

我的倾向

我倾向「按接口边界分级」：

• 对外 / 跨团队 → 强制版本号 + 明确 deprecation 周期（比如 2 个迭代或 3 个月，取较短）；
• 对内 / 同 owner → 用 feature flag + 字段级兼容（加字段不删字段、枚举加值不删值），不到「语义不可兼容」不开 v2；
• 任何一层都要有契约测试（contract test），把「我改了这个字段不影响你」变成 CI 里的硬约束，而不是靠 Code Review 自觉。

想听大家聊

1. 你们团队现在实际是哪种流派？有没有因为「版本策略选错」踩过具体的坑（比如网关上挂了 5 个同名接口、或者下游一直不敢升级 v2）？
2. 你们怎么定 deprecation 周期？是按迭代、按月、还是按下游迁移进度？
3. 契约测试你们用 Postman/Newman、Pact、还是自己写？在 CI 里怎么跑才不至于慢到没人愿意等？
4. 有没有「明明可以兼容但就是开了 v2」或者「明明应该开 v2 但硬扛了两年」的案例？

欢迎贴具体案例，越具体越好，最好带接口 diff 或网关路由片段（脱敏后）。