17370845950

API版本号应放在URL路径（如/v1/users），因其调试直观、网关路由简单、日志可读性强；Header方案仅适用于URL必须稳定且所有中间件显式透传校验的例外场景。

API 版本号该放在 URL 还是 Header？

绝大多数 G

o 微服务选择 URL 路径嵌入版本号（如 /v1/users），不是因为“标准”，而是因为调试直观、网关路由简单、客户端日志可读性强。用 Accept 或自定义 header（如 X-API-Version: v2）在 Go 中需手动解析、易被中间件忽略、且无法被 OpenAPI 工具直接识别。

例外场景：当必须保持 URL 完全稳定（如嵌入第三方 SDK 的固定回调地址），才考虑 header 方案，但需确保所有中间件（包括反向代理、API 网关、Go 的 http.Handler 链）都显式透传并校验该 header。

用 Gorilla Mux 还是 Gin 实现多版本路由？

两者都能做，但关键区别在路由匹配优先级和中间件作用域。Gorilla Mux 的子路由（subrouter）天然支持按前缀隔离，比如：

router := mux.NewRouter()
v1 := router.PathPrefix("/v1").Subrouter()
v1.HandleFunc("/users", userHandlerV1).Methods("GET")
v2 := router.PathPrefix("/v2").Subrouter()
v2.HandleFunc("/users", userHandlerV2).Methods("GET")

Gin 则依赖 Group，但要注意：Gin 的 gin.Group 本质是路径前缀 + 共享中间件，若在 v1 group 中注册了全局 panic 恢复中间件，它不会自动作用于 v2 group —— 必须分别注册或用 Use() 显式挂载。

• 避免混用 router.GET("/v1/users") 和 v1 := router.Group("/v1")，会导致重复前缀
• 版本 group 内不要直接写死 /v1，否则迁移成本高
• 若用 Gin，推荐统一用 engine.Group("/v{version}") + 正则约束，再由 handler 解析 version 参数分发

如何让 v1 和 v2 共享 DTO 结构体又不互相污染？

别用继承或嵌套结构体模拟“兼容性”——Go 没有字段级版本控制。正确做法是为每个版本定义独立的请求/响应 struct，并用工具同步字段变更：

• v1.UserCreateRequest 和 v2.UserCreateRequest 字段名、类型、tag 可不同
• 用 mapstructure 或 copier 在 handler 内做显式转换，而非靠 JSON tag 自动映射
• 共享的业务逻辑（如密码加密、权限校验）抽成纯函数，接收 interface{} 或具体版本 struct，不依赖字段名一致
• 禁止在 v1 struct 上加 json:",omitempty" 试图“兼容未来字段”——v2 新增字段若未显式声明，JSON 解码会静默丢弃

Swagger 文档怎么按版本生成且不冲突？

swag CLI 默认只生成一份 docs，要支持多版本文档，必须拆开生成：

• 为每个版本维护独立的 docs 目录，如 docs/v1, docs/v2
• 在注释中用 // @BasePath /v1 和 // @title User API v1 明确标识版本上下文
• 启动时按版本加载对应 docs 包：http.Handle("/v1/swagger/", http.StripPrefix("/v1/swagger/", swaggerFiles.Handler))
• 注意：swag init -g ./v1/main.go 必须指定入口文件所在目录，否则扫描不到该版本的 handler 注释

最易被忽略的是错误响应结构——v1.ErrorResponse 和 v2.ErrorResponse 的 code 字段类型（int vs string）、details 字段是否嵌套，都会导致前端解析失败。版本升级时，连错误格式都要当成契约来管理。