旧版API v1现状分析：接口列表、调用量、错误率、延迟基线数据采集方法

在制定弃用迁移方案之前，必须对旧版API v1进行全面的现状分析。本章将系统梳理v1接口清单、核心指标基线（调用量、错误率、延迟）以及数据采集方法，为后续的迁移策略和监控联动升级提供数据支撑。

1. v1接口列表与功能分类

旧版API v1共包含12个公开接口，按业务功能划分为以下四类：

2. 核心指标基线：调用量、错误率、延迟

基线数据采集周期为过去30天（生产环境），采样粒度为1分钟。以下为各接口的聚合基线：

3. 数据采集方法：Prometheus + 自定义Exporter

基线数据通过Prometheus监控体系自动采集，无需人工统计。采集架构如下：

具体采集方案分为三个层次：

1. API Gateway层（Nginx）： 通过nginx-lua-prometheus模块暴露指标，采集每个v1接口的请求总数、状态码分布、响应时间直方图。
2. 应用层（Java/Python）： 使用Micrometer或Prometheus客户端库，在业务代码中埋点，采集业务错误码、数据库查询耗时、外部依赖调用延迟。
3. 基础设施层： 采集Pod/容器级别的CPU、内存、网络IO，用于关联分析延迟和错误是否由资源瓶颈引起。

核心Prometheus指标定义示例：

# HELP api_v1_requests_total Total number of v1 API requests
# TYPE api_v1_requests_total counter
api_v1_requests_total{method="GET",path="/v1/users",status="200"} 86400

# HELP api_v1_request_duration_seconds Request latency histogram for v1 APIs
# TYPE api_v1_request_duration_seconds histogram
api_v1_request_duration_seconds_bucket{method="GET",path="/v1/users",le="0.1"} 72000
api_v1_request_duration_seconds_bucket{method="GET",path="/v1/users",le="0.3"} 84000
api_v1_request_duration_seconds_bucket{method="GET",path="/v1/users",le="1.0"} 86300
api_v1_request_duration_seconds_bucket{method="GET",path="/v1/users",le="+Inf"} 86400

# HELP api_v1_errors_total Total number of v1 API errors by error type
# TYPE api_v1_errors_total counter
api_v1_errors_total{method="POST",path="/v1/orders",error_type="5xx"} 84
api_v1_errors_total{method="POST",path="/v1/orders",error_type="4xx"} 1411

4. 基线数据采集架构图

下图展示了从API请求到Prometheus指标存储的完整采集链路：

5. 基线数据采集步骤

以下为生产环境基线数据采集的标准操作流程：

6. 基线数据质量保障

为确保基线数据的准确性和完整性，需执行以下校验：

• 数据完整性： 检查30天内是否有采集断点（Prometheus target up/down事件），缺失时段超过1%需标记并说明原因。
• 异常值过滤： 排除因部署、回滚、故障演练等非正常流量产生的数据点，避免基线被污染。
• 多维度交叉验证： 将Prometheus指标与API Gateway访问日志（ELK）中的请求数、状态码进行比对，误差应小于2%。
• 延迟基线校准： 确认P99延迟计算使用的histogram bucket边界设置合理（如0.1s、0.3s、1.0s、3.0s），避免因bucket过少导致精度失真。