2. API 版本化策略：语义化版本规范、URL路径版本控制、请求头版本控制、兼容性保证

API 版本化是 API 生命周期管理的核心环节，直接决定了弃用检测与告警策略的制定方式。一个清晰、可执行的版本化策略能够帮助团队在引入变更时，准确判断哪些客户端需要被通知、哪些流量需要被标记为“即将弃用”。本节将系统讲解四种主流的版本化实践及其在可观测性场景下的应用。

2.1 语义化版本规范（SemVer）

语义化版本规范（Semantic Versioning，简称 SemVer）为 API 版本号赋予了明确的语义含义，格式为 MAJOR.MINOR.PATCH。在 API 治理中，版本号的变更幅度直接对应兼容性保证的级别。

2.2 URL 路径版本控制

URL 路径版本控制是最直观、最广泛使用的版本化方式。版本号直接嵌入在请求路径中，例如 /api/v2/users。这种方式对客户端开发者友好，便于在日志和监控系统中直接提取版本信息。

# 示例：URL 路径版本控制下的端点结构
GET /api/v1/users          # 旧版本
GET /api/v2/users          # 新版本（新增了 email 字段）
POST /api/v2/users         # 新版本（请求体结构变更）

# Prometheus 指标采集示例（使用 relabel_config）
- source_labels: [__metrics_path__]
  regex: '/api/v(\d+)/.*'
  replacement: 'v${1}'
  target_label: api_version

2.3 请求头版本控制

请求头版本控制将版本信息放在 HTTP 请求头中，例如 Accept: application/vnd.myapi.v2+json 或自定义头 X-API-Version: 2。这种方式保持了 URL 的整洁，但增加了客户端配置的复杂度。

# 请求头版本控制示例（Python Flask）
from flask import request, jsonify

def get_api_version():
    # 优先从 Accept Header 解析
    accept = request.headers.get('Accept', '')
    if 'vnd.myapi.v2' in accept:
        return 2
    # 其次从自定义 Header 获取
    version = request.headers.get('X-API-Version', '1')
    return int(version)

@app.route('/api/users')
def get_users():
    version = get_api_version()
    if version == 1:
        return jsonify(legacy_users())
    elif version == 2:
        return jsonify(new_users())

2.4 兼容性保证策略

兼容性保证是版本化策略的最终目标。在 API 弃用检测中，我们需要明确区分“破坏性变更”和“非破坏性变更”，并据此制定告警阈值。

2.5 版本化策略对比与选型

不同的版本化策略在可观测性、弃用检测和告警集成方面各有优劣。下表从 SRE 和 API 治理角度进行综合对比：

2.6 兼容性保证的自动化检测

在 CI/CD 流水线中集成兼容性检测，可以在变更上线前自动判断是否需要触发弃用流程。以下是一个基于 OpenAPI 规范的兼容性检测示例：

# 兼容性检测伪代码（Go 语言）
func CheckCompatibility(oldSpec, newSpec *openapi3.T) CompatibilityResult {
    result := CompatibilityResult{IsBreaking: false}

    // 检查端点删除
    for path, pathItem := range oldSpec.Paths {
        if _, exists := newSpec.Paths[path]; !exists {
            result.IsBreaking = true
            result.BreakingChanges = append(result.BreakingChanges,
                fmt.Sprintf("端点 %s 已被删除", path))
        }
    }

    // 检查必需字段变更
    for path, pathItem := range newSpec.Paths {
        for method, operation := range pathItem.Operations() {
            oldOp := oldSpec.Paths[path].GetOperation(method)
            if oldOp == nil {
                continue // 新增操作，非破坏性
            }
            // 检查请求体必需字段
            if operation.RequestBody != nil {
                oldRequired := oldOp.RequestBody.Value.Schema.Value.Required
                newRequired := operation.RequestBody.Value.Schema.Value.Required
                for _, field := range newRequired {
                    if !contains(oldRequired, field) {
                        result.IsBreaking = true
                        result.BreakingChanges = append(result.BreakingChanges,
                            fmt.Sprintf("字段 %s 在 %s %s 中变为必需", field, method, path))
                    }
                }
            }
        }
    }
    return result
}