API版本号应放在URL路径中（如/v1/users），因其直观、可缓存、便于调试和日志分析；Header方式虽更RESTful但运维成本高，仅在强合规要求下选用。
API 版本号该放在 URL 还是 Header？
Go 的 HTTP 路由库（如 gorilla/mux、chi、原生 http.ServeMux）本身不内置版本路由逻辑，所以得靠你设计分发规则。URL 路径嵌入版本（如 /v1/users）最常见，也最直观——它对客户端友好、可缓存、能被 CDN 和日志系统直接识别。Header 方式（如 Accept: application/vnd.myapi.v2+json）更“RESTful”但实际落地麻烦：调试困难、无法用 curl 直测、Nginx 日志难过滤、OpenAPI 文档生成易出错。
除非你有强合规要求（比如必须保持路径完全稳定），否则优先选 URL 路径版本。别为了“理论正确”牺牲可观测性和运维效率。
用 chi 或 gorilla/mux 实现 v1/v2 路由隔离
核心思路是：为每个版本注册独立的子路由器，避免路由混杂和中间件污染。以 chi 为例，chi.NewRouter() 返回的是干净的路由实例，适合封装成版本模块：
func setupV1(r *chi.Mux) {
r.Get("/users", listUsersV1)
r.Post("/users", createUserV1)
}
func setupV2(r *chi.Mux) {
r.Get("/users", listUsersV2) // 可能返回新增字段
r.Post("/users", createUserV2) // 可能校验更严格
}
func main() {
r := chi.NewRouter()
r.Route("/v1", setupV1)
r.Route("/v2", setupV2)
http.ListenAndServe(":8080", r)
}
关键点：
立即学习“go语言免费学习笔记（深入）”；
-
r.Route("/v1", ...)自动添加前缀，且子路由完全隔离——v2 的中间件不会误入 v1 - 不要把 v1/v2 handler 写在同一个函数里用 if 判断版本，那会快速变成“版本意大利面”
- 每个版本的 handler 应使用独立的请求结构体（如
UserCreateRequestV1/UserCreateRequestV2），避免字段语义漂移
如何共享模型又避免 v1/v2 数据结构互相污染？
共用一个 struct User 看似省事，实则埋雷：v2 加个非空字段，v1 的 JSON 解析可能失败；v1 字段重命名，v2 客户端收不到旧字段。推荐按版本组织 DTO（Data Transfer Object）：
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"`
}
type UserV2 struct {
ID int `json:"id"`
FullName string `json:"full_name"`
CreatedAt string `json:"created_at"`
}
// v1 handler 返回 UserV1，v2 handler 返回 UserV2
// 内部 domain model（如 UserEntity）保留在 service 层，与 API 层解耦
好处：
- Swagger 生成时能准确标注各版本字段
- v2 修改不影响 v1 的单元测试断言
- 数据库模型（domain）变更时，只需调整各版本 DTO 的映射逻辑，而非修改所有 handler
别图省事用 map[string]interface{} 做通用响应体——它会让类型安全、IDE 跳转、静态检查全部失效。
如何优雅下线旧版本？
上线 v2 后，v1 不应立刻删除。真实场景中，总有客户端卡在旧版 SDK 或未更新配置。建议三步走：
- 在 v1 所有 handler 开头加
log.Warn("v1 deprecated, please upgrade to v2")并返回426 Upgrade Required或自定义X-Deprecated-Afterheader - 用 Prometheus + Grafana 监控各版本调用量趋势，确认 v1 流量归零后再删代码
- 在 CI 流程中加入“禁止新增 v1 路由”的检查（比如正则扫描
/v1/新路径）
最容易被忽略的是文档和错误提示：v1 接口的 OpenAPI YAML 必须保留到真正下线那天，并在 description 里写明停用时间；错误响应体也要带迁移指引，比如 {"error": "v1 is deprecated", "next_steps": ["use /v2/users instead"]}。
