接口废弃的 90 天倒计时：我管过 47 个 API 下线的完整流程、回滚预案与踩坑记录

一、现象与背景：没人敢删接口，但没人记得它为什么还在

先给一组数字。我所在团队 2022–2024 年累计对外暴露了 213 个 REST 接口（Spring Boot 3.2 + Spring Cloud Gateway 4.1），其中 47 个被标记为「待废弃」，但真正走完下线流程的只有 29 个——剩下 18 个以「再观察一下」为由挂了 8 到 14 个月。

代价很具体：

每多养一个废弃接口，平均多 1.2 小时/月的回归测试时间（QA 的接口用例集从 1200 条膨胀到 1860 条）；
2023 年 11 月一次 JDK 17 升级，因为 v1 接口里还有 3 个用了已移除的 sun.misc.BASE64Encoder，导致灰度环境直接 ClassNotFound，回滚耗时 47 分钟；
最痛的一次：2024 年 3 月，一个标了 @Deprecated 的 v1 订单查询接口在 Day 90 被「顺手」删掉，结果一个下游 SDK（某合作方自研，版本 2.3.1）的自动重试逻辑在收到 404 后疯狂打日志，3 分钟内刷出 12 万条 ERROR，触发了告警风暴，值班同学花了 2 小时才定位到根因。

核心问题不是「该不该删」，而是没人有一套可执行、可回滚、可追踪的下线 SOP。

二、原理与根因：为什么「加个 @Deprecated 然后删」一定会翻车

我把它拆成三个机制层面的原因：

1. 耦合是隐性的。 OpenAPI spec 里写了 47 个接口，但真正调用方散落在：网关路由表、下游 SDK 的硬编码 URL、定时任务配置、数据同步脚本、甚至某个运营的 Airflow DAG。你删了路由，但 Airflow 那个 DAG 没人知道它还在跑。

2. 废弃信号不可观测。 @Deprecated 注解和 410 Gone 状态码是「单向广播」——你发了，但没人听。没有流量侧的确认（「确实没人调了」），你只能靠猜。

3. 回滚没有预案。 绝大多数团队的「回滚」就是 git revert + 重新部署，但如果废弃动作已经涉及：数据库字段删除、网关路由规则变更、SDK 主版本升级——这三件事里任何一件回滚成本都远高于「重新加一个接口」。

三、具体做法：90 天倒计时的五步流程（可直接复用）

下面是我沉淀下来的 SOP，47 个接口里 29 个按这个流程走完，0 次 P2 以上事故。

Step 0：废弃前 2 周——盘点与公告（Day -14 到 Day -1）

# 废弃清单（Confluence / 内部 wiki），每个接口必填以下字段：
- api: GET /api/v1/orders/{id}
  version: v1
  successor: GET /api/v2/orders/{id}
  deprecationDate: 2024-09-01   # Day 0
  sunsetDate: 2024-11-30        # Day 90
  owner: zhang.wei
  known_consumers:
    - 合作方A（SDK v2.3.1，已确认升级到 3.0）
    - 内部数据同步 job（cron: 0 2 * * *，已切到 v2）
    - 未知（需流量确认）

同时在接口响应头加上标准 HTTP 废弃头（RFC 8594 + Deprecation 头）：

Deprecation: true
Sunset: Sat, 30 Nov 2024 00:00:00 GMT
Link: <https://docs.internal.example.com/api/v2/orders>; rel="successor-version"
Warning: 299 - "This API is deprecated. Use /api/v2/orders/{id} instead. Sunset: 2024-11-30."

为什么不用 410？410 会让部分 HTTP 客户端（包括 OkHttp 3.x 默认配置）直接抛异常而不是走重试逻辑。用 200 + Warning 头，对下游最温和。

Step 1：Day 0–30——只读 + 流量监控

接口仍正常返回 200，但响应体里加一个 X-Deprecation-Notice 字段：

{
  "data": { "...": "..." },
  "X-Deprecation-Notice": "This endpoint will be removed on 2024-11-30. Migrate to GET /api/v2/orders/{id}."
}

在网关层（Spring Cloud Gateway 4.1）加一个 DeprecationFilter，记录每个调用方的 X-Client-Id 和 IP 段：

@Component
public class DeprecationFilter implements GlobalFilter, Ordered {
    private final DeprecationMetrics metrics; // Prometheus

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getURI().getPath();
        if (deprecationRegistry.contains(path)) {
            String clientId = exchange.getRequest().getHeaders().getFirst("X-Client-Id");
            metrics.deprecatedCall(path, clientId); // 打点
        }
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() { return -200; }
}

Prometheus 指标 deprecated_api_calls_total{api="/api/v1/orders/{id}", client="partner-a"}，Grafana 看板每天看一次。

Step 2：Day 31–60——灰度降级

对内部调用方（已确认迁移的）：网关层将 v1 路由指向 v2 后端（透明代理），但响应头保留 Warning: 299。
对外部调用方：保持 v1 独立运行，但开始发送邮件/IM 通知（每 7 天一次，自动触发）。
关键指标：v1 接口日调用量应从 Day 0 的基线（比如 12,000 次/天）降到 <500 次/天。

Step 3：Day 61–80——只返回 Warning，数据降级

接口仍返回 200，但 data 字段开始返回空对象 {}（如果 v2 的数据结构兼容）或直接返回 {"error": "DEPRECATED", "message": "..."}。
这一步是回滚窗口：如果任何调用方出问题，只需把网关路由切回 v1 后端，5 分钟内生效。

Step 4：Day 81–90——观察期 + 最终下线

Day 85：如果日调用量 <10 次且无新增调用方，进入下线倒计时。
Day 90：
- 网关路由删除（配置中心 Nacos 2.2 推送，秒级生效）；
- 后端 Controller 保留但加 @Hidden（SpringDoc 不再生成到 OpenAPI）；
- 数据库相关字段/表再保留 30 天（别急着 DDL）；
- 删除后返回 410 Gone + JSON body 指引。

回滚预案（必须提前写好，不是事后补）

## 回滚触发条件（满足任一即回滚）
1. 下游 P1/P2 告警且 15 分钟内无法定位非我方原因
2. v1 接口日调用量突然从 <10 反弹到 >100（说明有未知调用方被触发）
3. 合作方书面反馈「升级后业务中断」

## 回滚步骤（目标 <10 分钟）
1. Nacos 恢复 v1 路由 → 生效（~30s）
2. 确认 v1 接口 200 → 通知合作方
3. 如果是数据层问题：执行 `git revert <commit> + redeploy`（~5min）
4. 事后 24h 内出 RCA

四、踩过的坑与反直觉之处

坑 1：@Deprecated 注解对 HTTP 调用方毫无意义。 Java 的 @Deprecated 只在编译期给 IDE 一个黄色警告。对方用 HTTP 调你的接口，根本看不到这个注解。必须用 HTTP 头（Deprecation、Warning）或响应体字段来传达。

坑 2：410 Gone 比 404 更危险，不是更安全。 反直觉点：很多团队觉得「返回 410 比 404 更正式，下游应该能识别」。实际上：OkHttp 3.12 默认对 404 不重试、对 410 也不重试，但自研 SDK 里经常写 if (code == 404) retry()——你返回 410，它不重试了，但你的日志里会少一条「这个调用方还在调」的证据。用 404 反而能触发对方的重试和告警，帮你发现漏网之鱼。

坑 3：数据同步 job 是最大的隐形调用方。 47 个接口里，有 6 个的「未知调用方」最终都是 Airflow / DataX 的定时同步任务。它们的特征：调用时间固定（凌晨 2:00）、IP 是内网堡垒机、没有 X-Client-Id 头。解法：在网关层对 User-Agent 为空且 IP 在 10.x 段的请求，强制打一个 internal-batch 标签。

坑 4：Day 90 不是终点，是起点。 下线接口后，真正的风险在 Day 91–120：某些低频调用（每月 1 次、每季度 1 次）还没触发。所以数据库 DDL（删字段/删表）至少等到 Day 120，且删之前要跑一次 EXPLAIN 确认没有遗留视图依赖。

五、结论与可复用清单

核心原则

废弃不是「删代码」，是管理一个 90 天的流量衰减曲线，直到它趋近于 0 且可证明为 0。

可复用清单（Checklist）

| 阶段 | 动作 | 完成标准 | |------|------|----------| | Day -14 | 废弃清单 + 公告 + 响应头 | 所有已知调用方确认收到 | | Day 0 | 上线 DeprecationFilter + Grafana 看板 | 能看到每个 client 的调用量 | | Day 30 | 内部调用方切 v2 | v1 日调用量 < 50% 基线 | | Day 60 | 数据降级（返回空/错误体） | 无 P2+ 告警 | | Day 85 | 最终确认 | 日调用量 < 10，无新增 client | | Day 90 | 路由删除 + 410 响应 | Nacos 推送成功 | | Day 120 | DDL 清理（删字段/表） | EXPLAIN 无遗留依赖 | | Day 180 | 代码删除（Controller/Service/DTO） | 回归测试通过 |

工具链

废弃注册表：deprecation-registry.yaml（Git 管理，CI 检查是否有接口漏注册）
流量监控：Prometheus + Grafana（指标名 deprecated_api_calls_total）
通知：自动邮件（每 7 天）+ IM webhook
回滚：Nacos 2.2 配置中心（路由变更 <30s 生效）
OpenAPI：SpringDoc 2.3 + @Hidden 控制文档可见性

最后一句话总结：接口不会自己死，它只会「被遗忘地活着」，直到某天你不该删的时候被删了。 90 天倒计时 + 可观测流量 + 提前写好的回滚预案，三件套缺一不可。

赞 0 · 收藏 0 · 评论 0 · 浏览 0

暂无评论。