4. 请求头版本控制：通过自定义 Header 传递版本信息

请求头版本控制（Header-based Versioning）是微服务架构中最推荐的版本策略之一。客户端在 HTTP 请求的头部携带版本标识，服务端根据该头部路由到对应的处理逻辑。这种方式将版本信息从 URL 中剥离，保持了资源标识的纯净性。

4.1 两种主流实现方式

4.2 Go 中间件实现示例

以下是一个基于自定义 Header Accept-Version 的版本路由中间件，使用 Go 标准库 net/http 实现：

// versionMiddleware 从请求头中提取版本号并注入上下文
func versionMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        version := r.Header.Get("Accept-Version")
        if version == "" {
            // 默认使用最新版本
            version = "v1"
        }
        // 将版本号存入请求上下文
        ctx := context.WithValue(r.Context(), "api_version", version)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// versionHandler 根据版本号分发到不同处理函数
func versionHandler(w http.ResponseWriter, r *http.Request) {
    version := r.Context().Value("api_version").(string)
    switch version {
    case "v1":
        handleV1(w, r)
    case "v2":
        handleV2(w, r)
    default:
        http.Error(w, "Unsupported API version", http.StatusNotAcceptable)
    }
}

func handleV1(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"version":"v1","message":"Hello from API v1"}`))
}

func handleV2(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"version":"v2","message":"Hello from API v2","new_field":"added"}`))
}

// 路由注册
func main() {
    mux := http.NewServeMux()
    mux.Handle("/api/users", versionMiddleware(http.HandlerFunc(versionHandler)))
    http.ListenAndServe(":8080", mux)
}

4.3 请求头版本控制流程

下图展示了客户端通过 Accept-Version 头部与服务端交互的完整流程：

4.4 优缺点分析

4.5 使用 Accept 媒体类型版本控制

除了自定义头部，更标准的方式是使用 Accept 头中的媒体类型参数。这种方式遵循 HTTP 内容协商规范，语义更清晰：

// 解析 Accept 头中的 vendor 媒体类型
func acceptVersionMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        accept := r.Header.Get("Accept")
        version := extractVersionFromAccept(accept)
        ctx := context.WithValue(r.Context(), "api_version", version)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func extractVersionFromAccept(accept string) string {
    // 示例：application/vnd.myapi.v2+json
    // 使用正则或字符串解析提取 v2
    if strings.Contains(accept, "v1") {
        return "v1"
    }
    if strings.Contains(accept, "v2") {
        return "v2"
    }
    return "v1" // 默认
}

4.6 版本头部与缓存策略

请求头版本控制对缓存的影响需要特别关注。下图展示了不同缓存层对版本头部的处理差异：

4.7 适用场景与决策建议

• 推荐使用：微服务内部调用、移动端 API、需要长期维护多版本的公共 API。
• 谨慎使用：面向浏览器的 API（调试不便）、老旧 CDN 环境（缓存问题）。
• 组合策略：可将请求头版本控制与 URL 前缀版本控制结合，内部服务用头部，外部公开 API 用 URL。