凌晨两点半，手机在床头柜上震。不是闹钟。
支付组的同学在群里扔了一句：订单中心调我们接口全 500。我坐起来开电脑，脑子还是糊的。前一天下午他们刚发过一版，把 orderStatus 改成了 status，理由写得挺漂亮——更简洁。联调没做，灰度也没有。他们的负责人白天还跟我说，不就换个字段名嘛。
真就出事了。
版本号不是护身符
很多团队对「兼容」的理解停留在路径上。URL 里挂个 /v2，心里就踏实了。但那次炸掉的接口，路径一个字没动，炸的是字段语义。
所以先把话说清楚：微服务接口版本兼容策略的核心，不是怎么编号，而是你怎么定义一个变更会不会伤到调用方。
我的判断标准很土，但好用。问三个问题。
老的调用方如果不改代码，还跑得通吗？这叫向后兼容。
新的调用方如果连上老版本的服务，会不会崩？这叫向前兼容。这个大部分人压根不考虑，可滚动发布的时候它就是事故来源——新客户端打到旧实例上，一瞬间的事。
最后一个：字段还在，意思变没变？这个最阴。
加字段通常是安全的，前提是调用方用宽松解析（比如 Jackson 默认忽略未知字段）。删字段、改类型、改枚举含义，基本都要命。改默认值这个最容易被忽略，默认值一变，等于灰度期间同一个请求会返回两种结果，排查起来能让人掉头发。
三种活法 各有各的代价
并行版本，也就是 /v1 和 /v2 同时跑。听着最稳，实际上最容易烂尾。为什么？因为没人愿意删旧版本。你写完 v2，说好三个月下线 v1，三个月后去查，v1 的调用量还剩 3%，但那 3% 是哪个业务，没人说得清。于是 v1 就永远活着，代码里到处是 if version == 1 的分支。
字段级扩展，就是在同一个接口上做加法，靠可选字段承载新语义。代价小，改起来快。但它有个天花板：一旦业务模型本身变了，比如从「单次支付」变成「分次支付」，加字段就撑不住了，硬加只会造出一个谁都不敢动的怪物结构。
还有一种是用协议头协商版本，Accept 里带版本号，或者自定义 header。优雅是优雅，问题是调试的时候容易忘。你拿 curl 手搓请求，忘了带头，打到的可能是默认版本，然后开始怀疑人生。所以这条路必须配一个明确的默认版本，并且把它写进文档最显眼的地方。
说实话，这三种没有优劣，只有适不适合。调用方少的内部服务，字段扩展就够了。对外或者跨部门、跨公司暴露的接口，老老实实并行版本，别省这个事。
网关能兜住的 和兜不住的
网关是个好东西。路由、限流、协议转换、字段补全，它都能干。我见过有团队在网关里做老字段映射，v2 的响应出去，网关自动补一个 orderStatus，把新老调用方都喂饱。
但别把网关当万能药。
它兜得住结构变化，兜不住语义漂移。假如 status 在 v1 里 1 表示已支付，在 v2 里 1 表示待支付，网关能做什么？它只能原样转发。这种变更必须换字段名，或者换枚举值空间，没有别的办法。
还有个坑：网关里的转换写得越多，它就越像一个没人敢碰的祖传中间层。半年后改需求，谁都不知道那段映射逻辑是干什么的。所以转换规则要有注释，要有单测，要有人认领。
我们最后落下来的几条土规矩
契约放 git，OpenAPI 或者 protobuf 都行，别放在某个人电脑里。CI 流水线上跑一次 breaking change 检测，检出破坏性变更就直接卡住合并。这步投入很小，收益极高。
废弃要有倒计时。响应头里带 Deprecation，同时在网关记调用来源，看清到底是谁还在调老版本。没有数据支撑的下线，永远下不掉。
删字段分两步走。先停止返回，观察两个发布周期，再真正删掉。中间这段观察期，日志里那些反序列化失败的报错就是你的信号。
版本号写进响应头。出事的时候一眼能看出请求打到了哪个版本，省下大量扯皮时间。
还有一条，是那次凌晨事故之后加的：任何字段改名，一律视为破坏性变更。不管它看起来多无害。
麻烦吗？麻烦。但总比凌晨两点半爬起来看堆栈强。