最稳妥方式是路由注册阶段用独立子路由器按版本隔离，如gin.group("/v1")和group("/v2")，而非中间件动态解析；需结构体、错误响应、文档、sdk全版本切片。
Go 里实现带版本号的 API 路由，最稳妥的方式不是靠中间件动态解析路径段，而是从路由注册阶段就明确分离不同版本的 handler —— 否则很容易在 net/http 或 gin 里踩到路径匹配优先级、参数捕获冲突、文档生成错位这些坑。
用独立子路由器按版本隔离（gorilla/mux 或 gin）
把 v1、v2 当作完全不同的路由树根，而不是在同一个 Router 上拼前缀。这样能避免 /v1/users 和 /v2/users 共享中间件逻辑时互相干扰，也方便单独挂载版本特定的中间件（比如 v1 用 JWT，v2 改用 OAuth2）。
以 gin 为例：
router := gin.Default()
v1 := router.Group("/v1")
v1.GET("/users", getUsersV1)
v1.POST("/users", createUserV1)
v2 := router.Group("/v2")
v2.GET("/users", getUsersV2) // 参数结构、返回字段可能完全不同
v2.POST("/users", createUserV2) // 甚至可能拆成 /v2/users/batch
关键点：
-
Group()返回的是新*gin.RouterGroup，和父 router 状态隔离 - 不要写
router.GET("/v1/users", ...)—— 这会让所有 v1 路由混在主树里，后续加/v1.1或迁移时难收敛 - 如果用
gorilla/mux，对应是subrouter := r.PathPrefix("/v1").Subrouter()
URL 路径中不嵌入语义化版本号（如 /api/v1.2.3/users）
版本号写成 v1、v2 就够了，别用 v1.2.3 或 v1.2。HTTP API 版本本质是契约变更，不是软件发布版本 —— v1.2.3 会误导团队以为可以做向后兼容的小修小补，但实际只要字段删改、状态码调整、必填变可选，就该升 v2。
常见错误现象：
- 上线
/v1.1后，客户端缓存了Accept: application/json; version=1.1，但服务端没做 header 版本路由，直接 404 - 运维配置反向代理时把
/v1.*全部转发，结果/v1.999被误转到 v1 服务，引发未定义行为 - OpenAPI 文档工具（如
swag）无法识别v1.2这类字符串，生成的 tag 乱序或丢失
避免用 Accept header 做版本路由（除非协议强制要求）
虽然 REST 理论上支持 Accept: application/vnd.myapp.v2+json，但 Go 生态里几乎没有成熟中间件能稳定处理这种协商 —— gin 默认不解析 Accept，chi 需手动调 r.Header.Get("Accept") 再分支，容易漏掉 q= 权重、多 type 混合等边界情况。
更实际的做法：
- 路径版本（
/v2/users）作为主路由方式，清晰、可调试、易监控 - 把
Accept或X-API-Version仅用于灰度场景：比如 v2 上线初期，只对特定 header 的请求返回新格式，其余仍走 v1 逻辑 —— 但这属于业务层判断，不在路由注册阶段解决 - 如果真要用 header 版本，别在
http.ServeMux或gin.Router层做分发，放到 handler 内部用r.Header.Get("X-API-Version")判断，避免污染路由树
版本升级时如何平滑过渡
上线 v2 不代表立刻下线 v1。真实场景里，v1 往往要并行运行 6–12 个月。这时候最容易被忽略的是错误响应体结构一致性。
比如 v1 错误返回：
{"error": "user not found", "code": 40401}
而 v2 改成：
{"message": "user not found", "status": "NOT_FOUND", "trace_id": "..."}
客户端 SDK 一旦硬编码解析 error 字段，就会在 v2 接口里 panic。所以：
- 各版本的 error schema 必须独立定义、独立验证（可用
go-playground/validator+ struct tag） - 不要复用同一套
ErrorResponsestruct 给多个版本 —— 看似省事，实则埋雷 - 在网关层（或统一 handler wrapper）里，对 v1 请求强制返回 v1 格式错误，哪怕内部 service 已经用 v2 模型处理
版本不是加个前缀就完事，它本质是接口契约的快照。路由设计只是起点，后续的序列化、错误处理、文档、SDK 生成，都得跟着版本切片走 —— 否则一个 v1 的 time.Time 字段用 "2006-01-02" 格式，v2 改成 RFC3339，前端日期解析就全崩了。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
