3. 主流API版本策略对比：URI路径、请求头与查询参数

在金融特征平台中，API版本管理是保障服务连续性与向前兼容的核心手段。业界主流版本策略主要分为三类：URI路径版本、请求头版本和查询参数版本。每种策略在可缓存性、路由灵活性、客户端升级成本等方面存在显著差异，需要根据金融场景的稳定性要求与运维习惯进行权衡。

3.1 三种策略核心对比

3.2 URI路径版本策略（/v1/features）

将版本号作为URL路径的第一段，例如 /v1/features/risk-score。这是金融行业最广泛采用的版本策略，也是本课程推荐的首选方案。

• 优势：
  • 路由清晰：网关、负载均衡可直接基于路径前缀分发流量。
  • 缓存友好：不同版本视为独立资源，CDN/反向代理无需额外配置。
  • 可读性强：开发者在浏览器、curl、日志中一眼识别版本。
• 劣势：
  • URL膨胀：每个版本都需要维护完整路径。
  • 版本迁移成本：客户端需更新所有请求URL。

# 请求示例：获取v1版本的风险评分特征
GET /v1/features/risk-score HTTP/1.1
Host: api.feature-platform.com
Authorization: Bearer <token>

# 请求示例：获取v2版本的风险评分特征（新增模型版本字段）
GET /v2/features/risk-score HTTP/1.1
Host: api.feature-platform.com
Authorization: Bearer <token>

3.3 请求头版本策略（Accept: version=1.0）

通过HTTP请求头传递版本信息，常见方式包括自定义头（X-API-Version: 1.0）或标准Accept头（Accept: application/vnd.feature.v1+json）。该策略将版本信息与资源URI解耦。

• 优势：
  • URI纯净：资源路径不包含版本信息，符合RESTful资源标识原则。
  • 内容协商灵活：可同时指定格式与版本（如 Accept: application/vnd.feature.v1+json）。
• 劣势：
  • 调试困难：浏览器地址栏无法直接测试，需借助Postman或curl。
  • 缓存复杂度高：需配置Vary头，否则CDN可能返回错误版本。
  • 客户端改造成本：需修改请求头构造逻辑，对老旧系统不友好。

# 请求示例：使用自定义请求头指定版本
GET /features/risk-score HTTP/1.1
Host: api.feature-platform.com
X-API-Version: 1.0
Authorization: Bearer <token>

# 请求示例：使用标准Accept头指定版本与格式
GET /features/risk-score HTTP/1.1
Host: api.feature-platform.com
Accept: application/vnd.feature.v2+json
Authorization: Bearer <token>

3.4 查询参数版本策略（?version=1）

将版本号作为URL查询参数传递，例如 /features/risk-score?version=1。该策略实现简单，但存在较多隐患，不推荐在生产环境使用。

• 优势：
  • 实现简单：服务端只需解析查询参数，无需修改路由配置。
  • URL可书签化：用户可保存带版本参数的链接。
• 劣势：
  • 缓存污染：不同版本共享同一URI，CDN/反向代理可能返回错误版本。
  • SEO不友好：搜索引擎可能将不同版本视为重复内容。
  • 参数冲突：版本参数可能与其他业务参数混淆。
  • 安全风险：查询参数容易被篡改或记录在日志中。

# 请求示例：通过查询参数指定版本
GET /features/risk-score?version=1 HTTP/1.1
Host: api.feature-platform.com
Authorization: Bearer <token>

# 请求示例：版本参数与业务参数混合（易混淆）
GET /features/risk-score?version=2&user_id=12345 HTTP/1.1
Host: api.feature-platform.com
Authorization: Bearer <token>

3.5 三种策略架构对比图

下图展示了三种版本策略在API网关层的路由处理流程差异，帮助理解不同策略对基础设施的影响。

3.6 策略选择决策矩阵

根据金融特征平台的不同场景，下表提供策略选择的决策参考：