每个设计接口的人都对自己说过同样的话——"加个字段就行了，老的调用方不受影响。"

三个月后，你发现老调用方也在读新字段，但逻辑完全不是你预期的。半年后，当初保证"兼容"的那个人转岗了。一年后，没人动得了任何一个字段，接口文档变成了考古现场——一半字段没人用，另一半的含义靠口头传承。你在注释里看到 `// 这个字段别删，XX团队在用`，去找XX团队，他们说早就不用了，但不敢确认，要再查查。

这不是向后兼容，这是技术债在穿正装。

兼容性承诺是一种债务

接口设计里最危险的一句话不是"我们重构吧"，而是"我们保证向后兼容"。前者好歹意味着你在正视问题，后者意味着你在透支未来。

向后兼容不是免费的。每多兼容一个旧版本，你就多了一条隐形的约束链。这条链不会出现在代码评审里，不会出现在架构文档里，但会在每一次你需要修改字段含义、调整返回结构的时候跳出来，像一个极其礼貌的绑匪——"您不能动这个，还有调用方在用。"

我见过一个金融产品的持仓查询接口，上线三年，四轮业务迭代。原始返回十几字段的扁平 JSON，三年后膨胀到六十多个字段，其中三分之一标了 `@deprecated` 但从未被移除。更有意思的是，有些字段的名字暗示了一种语义，实际逻辑早就走了另一条路——字段名叫 `availableAmount`，但返回值既不是可用金额也不是可用份额，而是经过三道业务规则过滤后的中间态数值，只有同时看过三个需求文档和两次重构的注释才能理解。

这就是兼容性承诺的真实代价。不体现在你写下 `@deprecated` 的那一刻，而体现在之后的每一天——每个新人多花一小时理解字段含义，每次评审多花半小时确认影响范围，每次上线多跑一轮兼容性测试。然后你发现，花在"保持兼容"上的时间，已经远超"直接改接口然后通知调用方迁移"的时间。

版本号是安慰剂

既然兼容这么难，版本号总该解决问题了吧？v1 的调用方继续用 v1，v2 的调用方用 v2，各过各的日子。

理论上很美好。实践中，版本号制造了一种虚假的安全感，让你以为自己掌控了变化，实际上只是在给债务分期还款。

第一个问题：谁在维持旧版本？v1 进入"维护模式"，翻译成大白话就是"不再主动改它，但它不能挂"。等到 v1 因为底层依赖变更出了 bug，你面临一个荒谬的选择——要么修一个你本该废弃的接口，要么让线上用户受影响。

第二个问题：迁移路径。大部分团队设计 v2 的时候想的是"新功能走 v2，老功能保持 v1 兼容"，但没人写迁移计划。v1 的调用方没有动力迁移——还能用，为什么要改？结果 v1 和 v2 长期共存，你维护两套几乎相同的逻辑，只在边界处略有差异。而这种差异恰好是最容易出 bug 的地方。

第三个问题最致命：版本号隐含了一个假设——版本之间是清晰的断代关系。但接口演进是连续的。v2 里加了一个字段，v1 的某个调用方也需要，你怎么办？让人家为了一个字段迁移到 v2、承担整个 v2 的变更风险？这就是为什么很多团队最终走向了"v2 兼容 v1"——版本号的分界线被自己的承诺吞掉了。

金融业务里这个问题更尖锐。客户端发布受应用商店审核周期控制，H5 有缓存，小程序有审核流程。你以为发了 v3 就可以放心改 v2 了？线上还有百万级用户跑着落后三个大版本的老客户端。ToB 场景更夸张——合作方可能半年才升级一次，你敢停 v1 就敢丢客户。

版本号没有解决问题，它只是把问题改了个名字。

前后端同源的幻觉

做 BFF 做了很多年，发现一个有意思的现象：后端团队和前端团队对"向后兼容"的态度完全不同。

后端工程师天然偏向兼容——下游服务挂了就是生产事故，"只增不删不改"几乎成了肌肉记忆。新需求加字段，老字段含义变了加新字段，接口结构不合理就再加一个接口。

前端作为接口消费者，他们的痛恰恰来自这种"只增不删"策略。每个废弃但不敢删的字段、每个含义跑偏的返回值、每条"这个接口给 PC 用那个给移动端用"的潜规则，最终都要在前端代码里被消化。那些字段映射、数据清洗、兜底逻辑，本质上就是在为后端的兼容性承诺买单。

全栈团队自己做接口又自己消费的时候，矛盾不会消失，只会以更隐蔽的方式爆发。"保持兼容"和"快速迭代"两股力量在同一个 sprint 里拉扯，最终谁先喊疼谁赢——吼得响的需求方先拿到新字段，沉默的老逻辑静静地躺在那里，等下一个倒霉的新人来踩坑。

有人想用 BFF 层来化解：后端给大而全的原始接口，BFF 给各端定制化的小接口。这确实缓解了前端的痛，但 BFF 自身成了兼容性债务的黑洞——每端一个接口变体，每次变更改三四块代码，膨胀速度比业务逻辑还快。你以为在做适配，其实在做翻译——把后端的兼容性债务翻译成前端的适配性代码，债务总量一分钱没少。

语义兼容才是真正的崩溃点

大部分人谈论"向后兼容"的时候，谈论的是结构兼容——字段还在不在，类型变没变，返回值的长相一不一致。这是最容易处理的部分。真正摧毁系统的是语义兼容——同样的字段，含义悄悄变了，但没人通知你。

一个常见的场景：价格字段 `price`，最初表示商品原价。后来业务要展示促销价，后端觉得改字段含义风险太大，加了 `promoPrice`。再后来运营说"原价"本身也是营销价格，又加了 `costPrice`。到此为止还算可控。

但真实故事往往没这么规整。`price` 的含义在几次需求变更后已经模糊了——它有时是原价，有时是会员价，取决于有没有传某个标记位。接口文档写的是"商品价格"，但这个语义已经不是任何新人能理解的。所有调用方都在用这个字段，各自带着不同的理解。

语义兼容最可怕的地方在于：接口没变，结构没变，甚至返回值类型都没变，但含义已经漂移了。没有版本号能捕获这种漂移，没有兼容性测试能发现它。直到运营配置了一个新类型的活动，`price` 返回了谁都没预料过的值，前端展示异常，客诉涌入——你才意识到兼容性在几个月前就已破裂，只是没有触发条件让它暴露。

金融场景里，这种语义漂移的后果不是展示异常，而是金额算错。接入方按自己的理解做计算，结果就是资金损失。这种事故比接口报错可怕一百倍——报错至少能被发现，金额计算偏差可能几周之后对账才暴露。

破裂比兼容更诚实

说了这么多兼容性的坏话，那到底怎么处理接口演进？我的观点可能有点反直觉：与其追求向后兼容，不如主动、明确、有计划地制造破裂。

明确的 breaking change 比暗中的 deprecation 更负责任，因为前者强迫所有人面对变化，后者允许所有人假装变化没发生。

承认接口腐蚀是常态。 接口像所有软件一样会腐化。与其给它穿上"兼容"的防护服假装它还健康，不如设定明确的寿命——半年、一年、三年。到期退役，有新需求就设计新接口。这不是不负责任，这是诚实。

把迁移当产品需求，不是技术债务。 大部分团队把接口迁移排在业务需求后面，永远排不上。但迁移有明确的用户（调用方）、交付物（新接口适配）和 deadline（老接口退役时间）。不给迁移排优先级，就等于允许系统无限肿胀。

契约优于兼容。 与其承诺"这个接口永远不变"，不如承诺"如果变了，提前 N 天通知、提供迁移文档、保留旧版本 N 天"。契约精神的核心不是永不改变，而是变化的可预期性。调用方不怕变化，怕的是变化来的时候没有准备。

这些做法有个共同前提：团队有足够的组织能力协调变化。如果调用方太多、协调成本太高、没有统一的服务治理，每一条都会被打回原形。这也是为什么小团队接口演进往往做得更好——不是技术更强，而是沟通半径更短，违约成本更低。

从接口到架构

接口的兼容性问题，是架构演进问题的微缩模型。

微服务说"独立部署、独立演进"，独立的潜台词是每个服务可以自己决定接口怎么变。但十个微服务互相调用，任何一个接口变更都可能引发级联影响。要么投入大量精力搞服务治理和版本路由，要么回到老路——所有变更走统一评审，breaking change 走全局排期。所谓"独立演进"，在实践中和单体里改公共模块的风险差不多，只是沟通链路更长、排查更慢。

微前端也类似。子应用可以独立发布，但共享状态怎么演进？远程组件的 props 契约怎么维持？这种跨应用的隐式依赖比后端接口还难管理——前端错误通常不触发告警，只在用户端静默失败。

兼容性不是接口设计的问题，是系统设计的问题。你选什么架构，就选了什么兼容性代价。单体的代价在模块边界，微服务的代价在网络边界，微前端的代价在运行时边界。形式不同，本质一样：系统越大、参与方越分散，兼容性管理成本越高。而所有"向后兼容"策略，本质上都是在有限制地接受这种成本——问题是大部分人低估了它的增长速度。

别再骗自己了

"向后兼容"最大的危害，不是它做不到，而是它让所有人以为做到了。

接口上加个 `@Deprecated` 就觉得尽了义务，旧版本标个 "maintenance only" 就觉得风险可控，变更日志发出去就觉得通知到位了。但现实中：`@Deprecated` 的字段三年没删，"maintenance only" 的版本出 bug 照样要修，变更日志没几个人看完。

兼容性不是一个注解、一个版本号、一封邮件能解决的。它是一系列持续的组织行为：定期清理废弃接口、强制迁移窗口、明确的服务等级协议、对违约行为的实际处罚。这些事哪一件都不轻松，哪一件都比加字段成本高。

如果做不到，不如别装。明确告诉调用方：这个接口可能会变，密切关注变更通知，提前预留适配工作量。这比承诺"永远兼容"然后偷偷改语义要体面得多。

向后兼容是一种幻觉。版本号是这种幻觉的载体。真正需要的不是更好的版本管理策略，而是对变化的理性预期和对自身组织的诚实评估。系统会变，接口会腐化，调用方会掉队——这些都是常态。与其花精力假装这些不会发生，不如花精力设计好它们发生时的应对方式。

承认破裂的可能性，比假装兼容的确定性，要可靠得多。