4. API 版本管理策略：URL路径版本、请求头版本、兼容性处理

在贷后预警系统中，API 的迭代速度与业务规则变更紧密相关。版本管理不仅是技术规范，更是保障存量客户端（如催收 APP、数据中台、外部监管接口）不受破坏性变更影响的核心手段。本章聚焦三种主流版本策略及其在低延迟场景下的选型考量。

4.1 三大版本策略对比

4.2 URL 路径版本策略

将版本号直接嵌入 URI 路径，是最直观、最稳定的版本标识方式。网关或负载均衡器可直接基于路径前缀进行路由，无需解析请求体或头部。

# 贷后预警 API 路径版本示例
GET /api/v1/early-warning/overdue-tags
GET /api/v2/early-warning/overdue-tags
POST /api/v1/early-warning/trigger-rules
POST /api/v2/early-warning/trigger-rules

实施要点：

• 路由隔离： 每个版本独立部署，避免代码分支混乱。
• 默认版本： 网关层配置 /api/early-warning 自动重定向至最新稳定版。
• 废弃周期： 至少保留两个大版本（如 v1、v2），v1 标记废弃后仍运行 6 个月。

4.3 请求头版本策略

通过自定义 HTTP 请求头或 Accept 头传递版本信息，保持 URL 的纯净性。贷后预警系统内部微服务间通信常采用此方式。

# 请求头版本示例
GET /api/early-warning/overdue-tags
Headers:
  Accept: application/vnd.early-warning.v2+json
  X-API-Version: 2

优势与代价：

• 优势： URL 简洁，符合 RESTful 资源定位语义；版本变更不影响缓存键。
• 代价： 网关需额外解析 HTTP 头，增加约 1-3μs 延迟；浏览器调试不便。

4.4 兼容性处理策略

当无法强制客户端升级时，服务端必须提供向后兼容。贷后预警系统常见的兼容性场景包括字段新增、字段废弃、枚举值扩展。

// 兼容性适配层伪代码（Java）
public class EarlyWarningAdapter {
    public V1Response adaptToV1(V2Response v2Resp) {
        V1Response v1 = new V1Response();
        v1.setOverdueDays(v2Resp.getOverdueDuration());  // 字段映射
        v1.setRiskLevel(null);  // 新增字段默认值
        v1.setOldScore(v2Resp.getScore());  // 废弃字段保留
        return v1;
    }
}

4.5 版本策略选型决策树

4.6 贷后预警版本管理最佳实践

1. 对外接口统一使用 URL 路径版本，如 /api/v2/early-warning/overdue-list，降低客户端接入成本。
2. 内部服务间通信使用请求头版本，保持 URL 纯净，便于服务网格（Service Mesh）统一治理。
3. 兼容层采用适配器模式，在网关或 BFF 层完成版本转换，避免业务逻辑污染。
4. 版本废弃时，在响应头中加入 Sunset: Sat, 31 Dec 2025 23:59:59 GMT，明确告知客户端截止时间。
5. 监控每个版本的调用量、错误率、延迟，当旧版本调用量低于阈值时，主动推动客户端升级。