8.1 版本兼容与依赖治理：术后排异清单
8.1 版本兼容与依赖治理：术后排异清单
摘要：出院之后第一道坎是"变起来不停机、升级起来不打架"。本文讲两件事：接口怎么做到新版上线老版照常，以及第三方依赖怎么治理——升级驱动、风险面评估、接入 SCA 扫描，别让自己在"不敢升级囤技术债"和"一升就炸"之间两头赌。
系统上线后，每天都有改动在发生：客户端升级了要新的接口协议、加了新字段；依赖库出了新安全补丁要不要升。但微服务的世界里，每一处"改"都牵扯着"别把别的服务带崩"。这一节把"变"变成一件能受控的事。
接口版本兼容：新版上线，老版照常
跨服务依赖最大的雷，就是"我给你升级版本，结果你按老协议的调用在线上自爆"。做接口兼容性，先想清楚三件事：
兼容粒度：接口要不要带版本号？常见的三种做法——
- 在 URL 里带（
/v1/orders、/v2/orders），路由清晰、新旧并存直观。 - 在请求头里带版本，URL 保持干净，但防御性差、依赖约定。
- 在消息/payload 内部带版本字段，适合内部服务，灵活但不直观。
兼容性原则：尽量向后兼容——加字段不加兼容风险，删字段、改字段类型、改响应结构才是真正需要版本跳动的破坏性变更。团队要养成"破坏性变更必带版本升级"的纪律，没有这个纪律，版本号只是摆设。
弃用节奏：老版本不是一律永久保留，而是"有节奏地退出"——明确弃用公告期、统计调用方是否升级、到期再淘汰。既别"新版一上老版就删"（老的调用方直接炸），也别"老版本永远躺着"（没人敢清，技术债越积越多）。
依赖治理：升级该不该升、该怎么升
第三方依赖是另一座雷区。很多系统挂了，是因为一个底层库被悄悄升级，篇了所有人。依赖治理要做的是：把"升级"从"看心情"变成"有驱动、有评估、有回滚的表态"。
- 升级驱动：给升级分优先级——安全补丁/高危漏洞>影响使用的 bug>功能增强>紧跟大版本。驱动不同，热度不同。
- 风险面评估：别只看"依赖清单里这条在第几版"，要看"我到底用到了它的哪部分、这条升级动到了我用的接口没"。一个你只用了一个函数的库，升级对你不一定是风险。
- 与 SCA 扫描挂钩：把依赖漏洞扫描（我们在 7.2 提过）接进 CI，高危漏洞一冒头就红，逼着团队"及时还债"，而不是囤成一座大山。
陷阱一：为"省心"躺平不升
"反正没人动，别乱升"是最危险的心态。安全漏洞不会因为你不升级就放过你，它只会让那笔债滚雪球，最后变成一次"不得不一次性升大版本"的高危操作。技术债是要利息的，不还只会越欠越多。依赖治理的目标不是"永不升级"，而是"升级可控、永不爆雷"。
陷阱二：把"升级"当"重写"
另一个极端是升级大版本时顺手"重写一遍"，把修依赖搞成改架构。升级依赖和重构代码要分开管理：一次只改一件事。混在一起，出问题你分不清是依赖的锅还是你重写拆掉的锅。分离变更，让每次回滚的边界都清晰。
把"兼容"当成一种协议思维，而不是一句口号
接口要不要挂版本、怎么挂，真正该练的是能否把"兼容"具象到协议的每一个粒度。有三个小动作，最能检验一个团队有没有把兼容当回事：
- 枚举和字段的加法要"可辨识"。给接口加字段时，别随手塞个够得上的默认值，而要用"该字段的缺席意味着什么"来定义语义。比如允许空值并带一个显式的"未提供"标志，会让新旧调用方对同一条数据得出不冲突的解读——这是兼容最容易踩的暗坑。
- 对"未知字段"要有宽容策略。新版本多加的字段，老版本收到后应该忽略而不是报错；老版本调用新接口多传的字段，新接口也该有合理的兜底。宽容未知，是协议演进能平滑的根基。
- 破坏性变更有一张"显式清单"。把"删字段、改类型、改默认值、改错误码"这类一改就炸的动作，白纸黑字列成清单，任何要触发它们的改动都必须带版本升级，且要过评审。有了这张清单，"这版 能不能升"就从一个反复争论的问题，变成一查便知的查表题。
这一小节想把一个容易被低估的东西讲实：接口兼容不是"尽量别改",而是"改的时候，有一套大家都会遵守的、可验证的纪律"。有了纪律，跨服务升级就从"提心吊胆"变成"按步骤走"。这也正好和我们在第 2 章强调的"契约即边界"、第 7 章的"契约测试"接成一个闭环——边界靠契约、契约靠验证、验证靠这节说的兼容纪律去兜底。
一个冷门的断代节点：老版本什么时候才算"真能退役"
我们把弃用节奏讲成了"有公告期、到期淘汰"，但执行时最难的不是起头，而是那个"什么时候才算真没人用"的分界。很多团队卡在总担心还有人在调老的，于是一拖再拖，版本号堆成山。这里有个可操作的办法：不要用"时间"做退役判据，要用"调用量的归零曲线"做判据。 给每个老版本挂一个调用埋点，看它的流量随公告期推进的下降曲线——当某老版本的调用量连续一段（比如一个月）低到可忽略、且没有对应告警，才允许进入淘汰程序；若还有零散调用，就逐个把调用方升级排期，而不是继续无限等待。这样退役就从"感觉可以了"变成"曲线到点了"，既不会误杀还有调用方的版本，又不会让老版本因为没人胆敢清而永久占用心智。末了补一句：版本退役和依赖升级其实是同一件事的两面——都怕感觉和侥幸，都靠数据和曲线拍板，这也是第 8 章反复强调"让治理有可验证依据"的原因。
本节要点
- 接口兼容：加字段不破坏，改结构才需要版本跳动；破坏性变更必带新版
- 三种版本粒度（URL/头/内部字段）按需选，灰度切换让新旧共存
- 弃用要有节奏，别"新版上老版删"也别"老版本躺着"
- 依赖按"驱动+风险面+SCA 扫描"管理，安全高危优先还
- 别躺平不升，也别把升级变重写：一次只改一件事，回滚边界清晰