3. API 版本管理基础：API 版本号语义化规范与版本控制策略

在行情数据灰度发布过程中，API 升级是不可避免的环节。为了确保客户端在服务端升级期间不受破坏性变更影响，必须建立一套严谨的 API 版本管理机制。本章将围绕版本号语义化规范（SemVer）以及三种主流的版本控制策略展开，为后续灰度发布中的 API 兼容性设计打下基础。

3.1 版本号语义化规范（SemVer）

语义化版本控制（Semantic Versioning，简称 SemVer）是目前业界最广泛采用的版本号管理标准。它通过 主版本号.次版本号.修订号 的三段式结构，清晰传达每次变更的兼容性影响。

除了基础的三段式，SemVer 还支持预发布版本号和构建元数据，这在灰度发布中尤为实用：

• 预发布版本号： 使用连字符附加，如 2.0.0-alpha.1、2.0.0-beta.2、2.0.0-rc.1。灰度环境中的 API 版本可以携带此类标签，明确标识其非正式状态。
• 构建元数据： 使用加号附加，如 2.0.0+20250315。可用于记录构建时间或 CI 构建编号，便于追溯。

3.2 三种主流 API 版本控制策略

在 RESTful API 设计中，将版本信息暴露给客户端主要有三种方式：URL 路径、请求头、请求参数。每种策略在可读性、缓存友好性、路由灵活性上各有优劣。

3.3 策略详解与代码示例

3.3.1 URL 路径版本控制

这是最直观、最常用的方式。版本号作为 URL 路径的第一段，例如 /api/v2/quote/BTCUSDT。在网关或路由层即可根据路径前缀分发到不同版本的后端服务。

// Go 示例：使用 Gin 框架实现 URL 路径版本路由
package main

import (
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    // v1 版本路由组
    v1 := r.Group("/api/v1")
    {
        v1.GET("/quote/:symbol", handleQuoteV1)
    }

    // v2 版本路由组
    v2 := r.Group("/api/v2")
    {
        v2.GET("/quote/:symbol", handleQuoteV2)
    }

    r.Run(":8080")
}

func handleQuoteV1(c *gin.Context) {
    symbol := c.Param("symbol")
    c.JSON(200, gin.H{"version": "v1", "symbol": symbol, "price": "old_format"})
}

func handleQuoteV2(c *gin.Context) {
    symbol := c.Param("symbol")
    c.JSON(200, gin.H{"version": "v2", "symbol": symbol, "price": "new_format"})
}

3.3.2 请求头版本控制

通过自定义 HTTP 请求头或标准 Accept 头来传递版本信息。这种方式保持了 URL 的整洁，更符合 RESTful 设计理念，但调试时不如 URL 路径直观。

// 客户端请求示例
// 方式一：自定义请求头
GET /api/quote/BTCUSDT HTTP/1.1
Host: api.example.com
X-API-Version: 2

// 方式二：使用 Accept 头（媒体类型协商）
GET /api/quote/BTCUSDT HTTP/1.1
Host: api.example.com
Accept: application/vnd.quote.v2+json

// Go 示例：通过请求头解析版本号
func versionMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 优先从自定义头获取
        version := c.GetHeader("X-API-Version")
        if version == "" {
            // 回退到 Accept 头解析
            accept := c.GetHeader("Accept")
            version = parseVersionFromAccept(accept)
        }
        if version == "" {
            version = "1" // 默认版本
        }
        c.Set("api_version", version)
        c.Next()
    }
}

func handleQuote(c *gin.Context) {
    version := c.GetString("api_version")
    symbol := c.Param("symbol")
    // 根据 version 执行不同逻辑
    c.JSON(200, gin.H{"version": "v" + version, "symbol": symbol})
}

3.3.3 请求参数版本控制

将版本号作为查询参数传递，例如 ?version=2。这种方式实现最为简单，但容易导致缓存失效（同一个 URL 可能因参数不同而返回不同内容），且参数容易被客户端忽略或遗忘。

// Go 示例：通过查询参数获取版本号
func handleQuoteWithParam(c *gin.Context) {
    version := c.DefaultQuery("version", "1")
    symbol := c.Param("symbol")

    switch version {
    case "1":
        c.JSON(200, gin.H{"version": "v1", "symbol": symbol, "price": "old_format"})
    case "2":
        c.JSON(200, gin.H{"version": "v2", "symbol": symbol, "price": "new_format"})
    default:
        c.JSON(400, gin.H{"error": "unsupported version"})
    }
}

3.4 策略选择建议

3.5 灰度发布中的版本兼容性矩阵

在灰度发布期间，服务端可能同时运行多个 API 版本。以下矩阵展示了不同版本变更类型与客户端兼容性的关系：