3. URI路径版本控制

URI路径版本控制是REST API中最直观、最广泛使用的版本策略。它将版本标识直接嵌入资源路径中，形成 /v1/resource 或 /api/v1/resource 的访问模式。本节将深入剖析该模式的设计规范、Go语言实现路径以及其适用场景与潜在风险。

3.1 路径版本设计模式

路径版本模式的核心思想是将API版本作为URI路径的第一段（或第二段，取决于是否包含 /api 前缀）。客户端通过显式指定版本来访问特定版本的接口。

3.1.1 标准路径格式

3.1.2 版本号命名规范

• 整数版本：v1、v2、v3 —— 简洁、递增、易于理解。
• 语义化版本：v1.0、v1.1 —— 粒度更细，但路径过长，不推荐。
• 日期版本：v2024-01 —— 适合按时间线发布的内部API。

3.2 Go中基于路径的路由实现

Go标准库 net/http 提供了基础的路由能力，但处理路径版本控制时，更推荐使用成熟的第三方路由库，如 gorilla/mux 或 Go 1.22+ 增强后的标准库 http.ServeMux。

3.2.1 使用 Go 1.22+ 标准库实现

Go 1.22 引入了增强的模式匹配，支持路径前缀匹配和HTTP方法限定，非常适合路径版本控制。

package main

import (
    "fmt"
    "net/http"
)

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

    // v1 版本路由
    mux.HandleFunc("GET /v1/users", v1GetUsers)
    mux.HandleFunc("POST /v1/users", v1CreateUser)

    // v2 版本路由
    mux.HandleFunc("GET /v2/users", v2GetUsers)
    mux.HandleFunc("POST /v2/users", v2CreateUser)

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

func v1GetUsers(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "v1: list users")
}

func v2GetUsers(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "v2: list users with pagination")
}

3.2.2 使用 gorilla/mux 实现

gorilla/mux 提供了更灵活的路由分组和中间件支持，适合大型项目。

package main

import (
    "fmt"
    "net/http"

    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    // v1 路由组
    v1 := r.PathPrefix("/v1").Subrouter()
    v1.HandleFunc("/users", v1GetUsers).Methods("GET")
    v1.HandleFunc("/users", v1CreateUser).Methods("POST")

    // v2 路由组
    v2 := r.PathPrefix("/v2").Subrouter()
    v2.HandleFunc("/users", v2GetUsers).Methods("GET")
    v2.HandleFunc("/users", v2CreateUser).Methods("POST")

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

3.2.3 路由分组与中间件集成

路径版本控制天然适合与中间件结合，例如版本日志、鉴权隔离、限流策略等。

// 版本日志中间件
func versionMiddleware(version string) mux.MiddlewareFunc {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            log.Printf("API Version: %s, Path: %s", version, r.URL.Path)
            next.ServeHTTP(w, r)
        })
    }
}

// 应用中间件到 v1 路由组
v1.Use(versionMiddleware("v1"))

3.3 路径版本控制流程示意图

下图展示了客户端请求经过路径版本路由分发到不同版本处理器的完整流程。

3.4 优缺点分析

3.4.1 优点

3.4.2 缺点

3.5 适用场景与避坑指南

3.5.1 推荐使用场景

• 对外公开API：需要明确告知客户端版本信息，降低沟通成本。
• 移动端API：移动端版本碎片化严重，路径版本控制便于长期维护多个版本。
• 第三方集成API：合作伙伴需要稳定的版本契约，路径版本是最直观的承诺。

3.5.2 避坑指南

3.6 路径版本 vs 其他版本策略对比