1. 课程导论：API 弃用迁移的背景与挑战
1.1 为什么 API 弃用迁移是 SRE 的必修课
在微服务与云原生架构快速迭代的今天，API 版本更迭已成为常态。一个被广泛忽视但风险极高的问题是：旧版 API 的优雅退场。据统计，超过 60% 的生产级事故与未妥善处理的 API 废弃直接相关，包括客户端兼容性崩溃、流量黑洞、监控数据断层等。
API 弃用迁移的核心挑战可归纳为以下四个维度：
| 挑战维度 | 典型问题 | 影响范围 |
|---|---|---|
| 兼容性 | 旧客户端未升级、硬编码端点、SDK 版本锁定 | 外部用户、合作伙伴集成 |
| 可观测性 | 旧 API 监控指标未保留、告警规则失效 | SRE 值班、故障定位 |
| 流量迁移 | 灰度比例失控、回滚路径缺失 | 线上稳定性、SLO 达成 |
| 数据一致性 | 新旧 API 响应格式差异、字段映射遗漏 | 下游数据管道、业务逻辑 |
关键认知： API 弃用不是一次性的"删除操作"，而是一个需要可观测性驱动、渐进式执行、可回滚保障的迁移工程。Prometheus 监控体系在其中扮演着"仪表盘"与"安"的双重角色。
1.2 Prom 监控在迁移中的关键作用
Prometheus 作为云原生监控的事实标准，在 API 迁移过程中提供了三个不可替代的能力：
- 流量基线建立： 在迁移前，通过
http_requests_total、http_request_duration_seconds等指标建立旧 API 的黄金信号基线。 - 灰度对比观测： 利用
relabel_configs和metric_relabel_configs将新旧版本流量打上不同标签，实现实时对比。 - 异常自动熔断： 基于 PromQL 的告警规则（如错误率突增 > 5%、P99 延迟翻倍）触发自动回滚或人工介入。
实战要点： 在迁移期间，务必为旧 API 和新 API 的
http_requests_total 指标保留相同的 label 结构（如 method、endpoint、status），仅在 version label 上区分。这能确保 PromQL 对比查询的简洁性和准确性。
1.3 课程目标与学习路径
本课程旨在培养 SRE 工程师在真实生产环境中，安全、可观测、可回滚地完成 API 版本迁移，并同步升级 Prometheus 监控体系的能力。完成本课程后，你将能够：
- 设计并实施一套完整的 API 弃用迁移方案，包含灰度策略、流量切换、回滚预案。
- 利用 Prometheus 指标和 Grafana 看板，实时量化迁移进度与风险。
- 编写 PromQL 告警规则，在迁移异常时自动触发熔断或通知。
- 通过
relabel_configs和 Recording Rules 优化迁移期间的指标成本与查询性能。
前置要求： 本课程假设学员已具备基本的 Prometheus 部署与 PromQL 查询能力，了解 Kubernetes 与微服务架构。如果你对 PromQL 的
rate()、histogram_quantile() 等函数尚不熟悉，建议先完成基础课程或查阅官方文档。