📚 课程目录第4章迁移策略制定

迁移策略制定：全量替换 vs 灰度迁移，兼容层策略，版本控制与回滚计划

接口迁移这事儿，说白了就是“换轮子”。但轮子能不能在车跑着的时候换，怎么换，换坏了怎么装回去——这才是团队拉开差距的地方。我个人习惯，判断迁移策略时先看三个要素：兼容性、风险面、回滚耗时。这三个要素定下来，策略就八九不离十了。

全量替换就是把旧接口一刀切，某个时间点之后，新流量全部走新协议。这个方法我最早用在一个内部RPC网关升级上，结果凌晨两点被电话叫醒——所有下游超时，紧急回滚。

什么场景适合全量替换？

我曾经…… 把全量替换用在面向第三方开发者的开放平台上。结果合作方没有按约定时间更新SDK，线上业务中断了两小时。从那以后，只要涉及外部调用方，我绝不用全量替换。

灰度迁移是“让一部分用户先跑起来”。你可以按流量比例、按用户ID哈希、或者按机房来逐步切量。我个人觉得，灰度迁移才是生产级别的迁移方式。

实现灰度迁移有几种常见模式：

小经验
灰度比例建议从1%开始。为什么？因为1%出问题，影响面小，你可以从容翻日志、查监控。我通常观察一个完整业务周期（比如24小时）再往上加比例。

兼容层的核心思想是“新旧并存，内部转译”。你在新旧接口之间放一层适配器，让两端各说各话，适配器来负责翻译。

实现上有几种方式：

方案	做法	代价	适合场景
透明代理模式	网关拦截旧请求，转成新协议再转发	增加一跳网络延迟，约1-3ms	调用方多且无法统一升级
协议转换网关	独立网关服务专门做协议翻译	额外维护一个中间层服务	协议差异特别大（如SOAP→gRPC）
SDK双栈支持	SDK内部同时实现新旧协议，按配置切换	SDK包体积增大，维护两套逻辑	客户端SDK分发，无法强制更新

我记得在做一个即时通讯SDK迁移时，用了SDK双栈方案。新旧两套连接同时在底层存活，应用层只感知到一个统一接口。这样迁移时客户端无需发版，全靠服务端下发的开关来控制走哪套协议。

  兼容层的底线：

  无论你用哪种方案，兼容层必须保证两件事——数据完整性不丢失、超时重试机制一致。我曾经遇到过，兼容层把旧接口的二进制报文转成新接口的JSON时，丢失了其中一个字段，导致下游解析失败。这种错误隐蔽性极高，上线后三天才被发现。

版本控制不只是给SDK打个tag。更重要是的，协议本身要有版本标识。我见过太多团队只在代码层面维护版本，结果新老两个SDK实例对上话，两边都不知道对方在用什么版本。

建议在协议头部嵌入以下信息：

版本协商逻辑：连接建立时，双方交换版本号，取两者都支持的最高版本作为本次会话的协议版本。我习惯在握手阶段多做一次“版本能力集”的交换，比如客户端支持v2-v4，服务端支持v3-v5，那么选v4。

注意：
版本控制最容易被忽略的一点——版本号必须和API组绑定。不同路由组可以有不同的版本演进节奏。我见过一个项目把整个网关所有接口放在同一个版本下，结果一个接口升级，所有接口都被迫跟着升级。版本控制建议做细分：/api/v1/users、/api/v2/orders 这样来组织。

回滚不是“把代码切回去”那么简单。你得考虑数据一致性、正在处理的请求、客户端缓存的残留。

一个合格的回滚计划要包含：

我之前的做法是，每次灰度迁移都预先搭好一个“回滚沙箱”——把旧版本服务保持待机状态，旧数据库连接不释放，配置中心里保留旧路由表。一旦决定回滚，只需在网关层切一下路由，全程不需要重新部署。

回滚后的检查清单：
- 旧协议的日志是否恢复正常写入
- 监控指标是否回到基线
- 调用方是否有大量超时或重试
- 如果涉及数据库，检查双写的一致性差值

下面这张图，是我每次做迁移决策时都会走的流程。你直接拿去做方案评审也没问题。

你看这个流程，其实核心就是三个判断点：调用方能统一升级就全量替换，不能就先灰度走兼容层，不管走哪条路，版本控制和回滚都是最后一道保险。

  一句话把策略说清楚：

  全量替换是理想，灰度迁移是现实，兼容层是底线，版本控制和回滚是你的安全带。任何迁移方案只要少了其中任何一环，线上出事的概率都不会低。