1. 课程导论：API生命周期管理概述、弃用检测的重要性、Prometheus告警生态简介
1.1 API生命周期管理概述
API从设计到退役并非一次性交付，而是遵循一个可预测的生命周期模型。现代API治理要求团队在每个阶段都建立明确的策略与自动化检查点，否则将陷入“版本地狱”与“兼容性债务”。
| 阶段 | 核心活动 | 治理要点 |
|---|---|---|
| 设计 | 契约定义（OpenAPI / GraphQL Schema） | 命名规范、字段必选/可选、响应码枚举 |
| 开发 | Mock服务、契约测试 | 向后兼容性检查、语义化版本 |
| 发布 | 网关路由、限流、认证 | 版本号注入、变更日志同步 |
| 运营 | 可观测性、SLO监控 | 弃用头（Sunset Header）注入 |
| 弃用 | 通知、迁移窗口、流量切断 | 弃用检测、告警、灰度下线 |
| 退役 | 下线、文档归档 | 残留流量阻断、消费者确认 |
关键认知： 弃用不是终点，而是生命周期中最容易被忽视的断裂点。多数线上故障源于消费者未感知到上游接口即将下线，导致调用突然失败。
1.2 弃用检测的重要性
API弃用检测不是简单的“版本号过期提醒”，而是可观测性数据与治理策略的交叉点。缺乏检测机制时，团队常面临以下问题：
- 消费者失联： 无法识别哪些客户端仍在调用已标记弃用的端点。
- 退役延期： 因担心影响未知消费者，弃用接口长期滞留，增加维护成本。
- 故障被动： 消费者在接口下线后才发现调用失败，引发P0级事故。
- 合规风险： 金融、医疗等行业要求API变更必须有明确的弃用通知窗口。
最佳实践： 在API网关或服务网格层注入
Sunset 与 Deprecation HTTP 头部，结合 Prometheus 指标实时追踪消费者调用行为，实现“可观测的弃用”。
| 检测维度 | 数据来源 | 告警触发条件 |
|---|---|---|
| 端点调用频率 | Prometheus Request Counter | 弃用端点仍有 > 0 QPS 持续超过窗口期 |
| 消费者版本分布 | User-Agent / X-Client-Version | 旧版本客户端占比超过阈值 |
| Sunset Header 缺失 | 网关日志 / 代理注入 | 响应中未携带弃用头部 |
| 迁移进度 | 消费者主动上报 / 灰度流量 | 迁移完成率低于时间线预期 |
1.3 Prometheus告警生态简介
Prometheus 已成为云原生可观测性的事实标准。在API弃用场景中，Prometheus 生态提供从指标采集 → 规则评估 → 告警路由 → 事件响应的完整链路。
在API弃用场景中，Prometheus 生态的核心组件分工如下：
- 指标暴露： 服务或网关通过
/metrics端点暴露弃用相关指标（如api_deprecated_requests_total）。 - 规则评估： Prometheus 定期评估告警规则，检测弃用端点是否仍有流量、消费者版本是否过期。
- 告警路由： Alertmanager 根据标签（如
severity=critical、team=api-gateway）将告警发送到不同接收通道（邮件、PagerDuty、钉钉等）。 - 事件响应： SRE 团队根据告警内容执行迁移加速、消费者通知或紧急下线回滚。
常见误区： 很多团队只配置了“接口错误率”告警，却忽略了“弃用接口仍在被调用”这一前置风险。等到错误率飙升时，消费者已经受损。弃用检测告警应作为预防性告警，而非事后告警。
1.4 课程实战目标
通过本课程，你将掌握以下核心能力：
- 设计 可观测的API弃用策略，包括Sunset Header注入与指标埋点。
- 编写 Prometheus告警规则，精准检测弃用端点的残留流量。
- 集成 Alertmanager路由与通知模板，实现告警分级与自动化响应。
- 升级 现有监控体系，将弃用检测纳入SLO与错误预算治理流程。
课程将基于一个真实的微服务案例，从零搭建API弃用检测与Prometheus告警集成系统，覆盖代码实现、规则配置、告警调试、灰度下线全流程。