老接口改造怎么做：新增接口、灰度切换和领域边界

接口改造最怕一上来就改老接口。老接口背后可能有很多调用方、脚本、缓存和历史数据。更稳的做法通常是新增接口，再逐步切换。

老接口先保持稳定

老接口如果还在线上被使用，第一原则是保持行为稳定。

不要轻易改：

• 入参字段。
• 返回字段。
• 错误码。
• 排序规则。
• 分页语义。
• 默认值。

即使新设计更合理，也要先确认调用方是否能同步改造。

新增接口承载新模型

当老接口模型已经不适合继续扩展，可以新增一个新接口。

新接口可以重新整理：

• 请求模型。
• 响应模型。
• 字段命名。
• 校验规则。
• 错误语义。
• 领域边界。

这样不会把历史包袱继续叠到老接口上。

上游配置切换

新增接口后，不要马上一次性全量切。

可以先让上游支持配置切换：

1. 默认继续走老接口。
2. 测试环境切到新接口。
3. 小范围灰度。
4. 观察日志和指标。
5. 确认无误后扩大范围。
6. 最后下线旧接口。

这个过程要有回退开关。接口改造不只是代码问题，也是发布和运营问题。

领域边界要现实

按领域划分接口是好方向，但前提是底层领域模型足够清楚。

如果底层表、服务和业务边界本来就混乱，接口设计时强行套领域名，反而会显得别扭。

比较务实的做法是：

• 先识别核心实体。
• 再识别主要流程。
• 最后再确定接口边界。

不要为了“看起来领域化”而让调用方更难理解。

维护建议

老接口改造可以按这个模板推进：

1. 明确老接口调用方。
2. 写出新接口契约。
3. 保留老接口。
4. 增加配置切换。
5. 测试环境运行一段时间。
6. 灰度发布。
7. 记录下线条件。

这样改造风险小，也方便后续复盘。