URL路径带版本号最稳妥，如/v1/users和/v2/users，便于路由隔离、中间件分治及文档管理；应避免query或header做主版本路由，需结构体分离、handler解耦、OpenAPI与SDK同步更新。
URL路径里带版本号最稳妥
绝大多数 Go Web 服务用 echo、gin 或 net/http 路由时，直接把版本塞进路径是最不容易出错的方式。比如 /v1/users 和 /v2/users，路由层就能天然隔离，中间件、handler、甚至 Swagger 文档都能按版本分开管理。
常见错误是试图用 query 参数（如 ?version=v2）或 header（如 Accept: application/vnd.myapi.v2+json）做主版本路由——这会让路由逻辑变重、调试困难，还容易漏掉某条路径的版本判断。
- 用
gin时，直接分组：r.Group("/v1").Handler(...)；r.Group("/v2").Handler(...) -
echo同理：e.Group("/v1")和e.Group("/v2")，各自挂独立的 middleware - 避免在 handler 里用
if v == "v2"分支处理——逻辑混杂，测试难覆盖，升级时易漏改 - 路径版本要和实际发布节奏对齐：没发 v2 就别提前写好
/v2/xxx路由，否则会暴露未完成接口
同一份代码支持多版本的关键是结构体分离
Go 没有运行时类型擦除，版本差异常体现在请求/响应结构上。比如 v1 返回 User.Name，v2 加了 User.Nickname 且 Name 变成可选。这时候不能共用一个 struct User，否则 JSON 序列化、OpenAPI 生成、数据库映射全会打架。
正确做法是每个版本定义自己的 DTO（Data Transfer Object）：
立即学习“go语言免费学习笔记（深入）”；
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"`
}
type UserV2 struct {
ID int `json:"id"`
Name *string `json:"name,omitempty"`
Nickname string `json:"nickname"`
}
注意点：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 不要用指针“模拟可选字段”来凑合老版本结构——v1 的
Name是必填，就该是string，不是*string - 数据库模型（如 GORM struct）应保持稳定，只做存储；API 层用版本专属 struct 做转换，靠手动赋值或轻量工具（如
mapstructure）桥接 - 如果用
swagger生成文档，每个版本 group 要绑定各自的swaggo注释，否则 v1 接口文档里会混进 v2 字段
路由复用但 handler 不复用：别硬套“一个 handler 处理所有版本”
有人想写一个 GetUser(c echo.Context, version string) 然后里面 if-else 分流，这在小项目初期看似省事，但很快就会失控。v1 逻辑要查 A 表，v2 要连 B 表+加缓存策略，v3 还要兼容旧字段别名——全塞进一个函数，可读性、单元测试、性能优化全完蛋。
更合理的做法是：路由指向不同 handler，但共享底层 service 层。
- 定义统一 service 接口：
type UserService interface { GetUser(ctx context.Context, id int) (*UserModel, error) } - v1 handler 调
svc.GetUser()+ 映射到UserV1；v2 handler 同样调svc.GetUser()+ 映射到UserV2 - service 层不感知 API 版本，专注业务逻辑；版本差异只发生在 transport 层（HTTP handler）和 DTO 层
- 这样既避免重复查库，又让各版本行为完全解耦，上线 v3 时删 v1 handler 不会影响 v2
别忽略 OpenAPI 和客户端 SDK 的版本同步成本
写了 /v2/users 路由、定义了 UserV2，但如果没更新 openapi.yaml 或没重新生成 client SDK，前端或第三方集成根本不知道新字段存在，或者收到 v2 响应却用 v1 的解析逻辑，结果是 undefined 或 panic。
真实痛点往往不在服务端代码，而在配套资产滞后：
- 每次新增版本路由，必须跑一遍
swag init（或对应工具），确认生成的docs/docs.go包含新路径和新 struct - 如果用
oapi-codegen生成 Go client，得为每个版本输出独立 package，比如client/v1和client/v2，避免 import 冲突 - Swagger UI 部署时，别只扔一个
/docs页面——要能切版本，或至少在页面顶部标清当前文档对应的是v1还是v2 - 最常被跳过的一步：在 CHANGELOG 或内部文档里写明“v2 接口废弃了 v1 的
/users/{id}/profile，请改用/v2/users/{id}”，否则运维和前端永远在猜
版本控制最难的从来不是怎么写代码，而是让所有人——包括半年后接手的自己——一眼看清哪条路径属于哪个版本、字段变更是否已落地、文档和客户端有没有跟上。路径前缀只是起点，后面每一步漏掉，都会变成线上 bug 的伏笔。
