路径前缀是最稳妥的接口版本控制方式，需用gin.group或gorilla/mux.subrouter在注册阶段隔离路由、中间件、文档及dto，禁止混用结构体、动态解析路径或共享handler/struct，必须按版本声明dto、分离文档与测试并覆盖跨版本契约。

路径前缀是最稳妥的接口版本控制方式，Header 或 Query 参数容易被中间件丢弃、日志不可见、调试困难，不建议作为主方案。

用 gin.Group 或 gorilla/mux.Subrouter 隔离路由

版本必须在路由注册阶段就明确分离，而不是靠 handler 内部 if 判断。Gin 的 Group 和 gorilla/mux 的 Subrouter 能保证路径前缀、中间件作用域、文档生成都彼此隔离。

• v1 := r.Group("/v1") 后注册的所有 handler 自动带 /v1 前缀，r.Walk 可查到完整路径树
• 每个 Group 可绑定专属中间件，比如 v2.Use(validateNewAuth())，不影响 v1 流量
• 禁止把版本写进 handler 名（如 listUsersV2），函数名应保持业务语义（如 listUsers）
• 哪怕 v1 和 v2 逻辑目前一致，也必须声明两个独立函数——否则无法单独灰度、回滚或加字段校验

DTO 必须按版本声明，禁止共用 struct

v1 客户端不能收到 v2 新增字段，哪怕字段值为空；v2 也不能意外继承 v1 废弃字段。JSON 序列化是契约核心，结构体混用等于埋雷。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。

下载

• 定义 UserV1 和 UserV2 两个 struct，即使字段名和类型当前完全一样
• handler 中禁止直接 json.Marshal(userDomain)，必须显式转换：json.Marshal(UserV1{...})
• 新增字段一律加 json:",omitempty"，并设合理零值（string 默认 ""，int 默认 0）
• 废弃字段不要删，改为未导出字段 + 注释标记：oldName string `json:"old_name,omitempty"` // deprecated: use FullName instead

Swagger 文档和测试必须按 Group 分离

swaggo/swag 等工具若没为每个 Group 单独打 @tags，@version 注释会覆盖或失效，导致文档里 v1/v2 接口混在一起，前端无法区分。

• 在每个 Group 的 handler 上方加 // @Tags v1 和 // @Tags v2
• 运行 swag init -g api/v1/main.go 和 swag init -g api/v2/main.go 分别生成文档
• 单元测试要按版本目录组织：api/v1/handlers/user_test.go 和 api/v2/handlers/user_test.go
• contract test 必须覆盖 v1 请求是否只返回 v1 字段、v2 是否能兼容接收 v1 请求体等边界场景

别在中间件里动态解析 r.URL.Path 提取版本

看似省事，实则破坏可维护性：子路由已剥离前缀，r.URL.Path 拿到的是 /users 而非 /v1/users；反向代理重写路径后逻辑直接失效；router.Walk 查不到真实注册路径。

• 正确做法是在创建 Group 时就注入版本信息：v1.Use(versionMiddleware("v1"))
• versionMiddleware 内部用 context.WithValue(r.Context(), versionKey, ver) 存值
• 后续 handler 通过 c.Request.Context().Value(versionKey) 安全读取，不受代理干扰
• 如果非要 fallback 到路径提取（如兼容旧客户端），应在中间件里对原始 c.Request.URL.Path 切分，而非依赖子路由后的路径

最易被忽略的是 DTO 隔离和 contract test —— 路由分组只是入口，真正让版本“活下来”的，是每个版本独立的序列化结构和跨版本验证机制。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！