4、请求头版本控制：自定义Header版本协商(Accept-Version)、Go中间件实现版本解析、与路径版本的对比

在 REST API 的版本演进实践中，将版本信息放在 HTTP 请求头（Header）中是一种比路径版本更符合 REST 语义的做法。本章深入讲解基于自定义请求头 Accept-Version 的版本协商机制，以及如何在 Go 中通过中间件优雅地解析版本号，并与路径版本方案进行全面的对比分析。

4.1 请求头版本控制的核心原理

请求头版本控制的核心思想是：URL 只标识资源，版本信息通过 HTTP 头部传递。客户端在发起请求时，在自定义的请求头中声明期望的 API 版本，服务端根据该头部路由到对应的处理逻辑。

4.1.1 常见的请求头版本协商方式

本章重点讨论第一种方式——自定义 Accept-Version 头，因为它实现简单、可读性强，且与 Go 中间件模式高度契合。

4.2 Go 中间件实现版本解析

在 Go 中，通过中间件模式可以优雅地拦截所有请求，解析 Accept-Version 头，并将版本信息注入到请求上下文中，供后续处理器使用。

4.2.1 中间件架构设计

4.2.2 中间件代码实现

以下是一个完整的 Go 中间件实现，它从请求头中提取版本号，并支持默认版本和版本格式校验。

package middleware

import (
    "context"
    "net/http"
    "regexp"
)

// 定义 context key 类型，避免冲突
type contextKey string

const VersionKey contextKey = "api_version"

// 版本号格式：v + 数字，如 v1, v2, v3
var versionPattern = regexp.MustCompile(`^v\d+$`)

// VersionMiddleware 解析 Accept-Version 请求头
func VersionMiddleware(defaultVersion string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            version := r.Header.Get("Accept-Version")

            // 如果请求头为空，使用默认版本
            if version == "" {
                version = defaultVersion
            }

            // 校验版本号格式
            if !versionPattern.MatchString(version) {
                http.Error(w, "Invalid API version format. Use v1, v2, etc.",
                    http.StatusBadRequest)
                return
            }

            // 将版本号注入到请求上下文中
            ctx := context.WithValue(r.Context(), VersionKey, version)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

// GetVersion 从上下文中获取版本号
func GetVersion(ctx context.Context) string {
    version, ok := ctx.Value(VersionKey).(string)
    if !ok {
        return "v1" // 安全默认值
    }
    return version
}

4.2.3 在路由中使用中间件

package main

import (
    "encoding/json"
    "net/http"
    "your-project/middleware"
)

func main() {
    mux := http.NewServeMux()

    // 用户资源处理器
    userHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        version := middleware.GetVersion(r.Context())
        switch version {
        case "v1":
            handleUserV1(w, r)
        case "v2":
            handleUserV2(w, r)
        default:
            handleUserV1(w, r) // 默认回退到 v1
        }
    })

    // 应用中间件
    mux.Handle("/api/users", middleware.VersionMiddleware("v1")(userHandler))

    http.ListenAndServe(":8080", mux)
}

func handleUserV1(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{
        "version": "v1",
        "name":    "User API v1",
    })
}

func handleUserV2(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{
        "version": "v2",
        "name":    "User API v2",
        "email":   "user@example.com",
    })
}

4.3 请求头版本 vs 路径版本：全面对比

路径版本（如 /api/v1/users）和请求头版本（如 Accept-Version: v1）是两种最主流的版本控制策略。以下从多个维度进行对比分析。

4.3.1 对比维度表格

4.3.2 适用场景分析

4.3.3 混合策略：最佳实践

在实际项目中，很多团队采用混合策略：

• 对外公开 API：使用路径版本（/api/v1/users），便于第三方开发者理解和使用。
• 内部微服务通信：使用请求头版本（Accept-Version: v2），保持内部接口的灵活性和 REST 纯度。
• 版本过渡期：同时支持两种方式，通过中间件统一处理，逐步迁移。

4.4 请求头版本控制的进阶技巧

4.4.1 版本范围与协商

支持版本范围可以让客户端更灵活地指定兼容版本：

// 版本范围解析示例
func parseVersionRange(header string) (minVer, maxVer string, err error) {
    // 支持格式：
    // "v2"          - 精确版本
    // "v2-v4"       - 版本范围
    // ">=v2"       - 最小版本
    // "<=v4"       - 最大版本
    // 实现细节略...
}

4.4.2 版本降级与兼容性

当客户端请求的版本不存在时，可以自动降级到最近的兼容版本：

func resolveVersion(requested string, supported []string) string {
    // 如果请求的版本在支持列表中，直接返回
    for _, v := range supported {
        if v == requested {
            return v
        }
    }
    // 否则降级到最新的低于请求版本的版本
    // 例如请求 v5，但只支持到 v3，则返回 v3
    // 实现细节略...
    return supported[len(supported)-1]
}

4.5 本章小结

• 请求头版本控制 通过 Accept-Version 头传递版本信息，保持 URI 纯净，更符合 REST 语义。
• Go 中间件实现 可以优雅地解析版本号并注入上下文，支持默认版本回退和格式校验。
• 与路径版本对比：路径版本适合公开 API 和缓存场景，请求头版本适合内部服务和 REST 纯化场景。
• 混合策略 可以在不同场景下灵活选择，但需注意控制复杂度。