不推荐在URL路径中硬编码API版本号，应使用HTTP Header（如X-API-Version）进行版本协商，将版本逻辑下沉至handler内部处理，以保持REST原则、支持字段演进、简化路由与文档维护，并确保新旧版本兼容。
Go 服务的 API 版本管理，不推荐在 URL 路径里硬编码 v1、v2 这类版本号——它看似直观，实则破坏 REST 原则、阻碍字段演进、让路由层承担不该有的语义职责。
为什么 /api/v1/users 是个危险信号
URL 是资源标识符，不是协议协商通道。把版本塞进路径，等于默认所有 v1 客户端永远不能访问 v2 字段（哪怕只是新增一个非必填字段），也意味着你必须为每个版本维护一套独立路由、中间件、甚至控制器逻辑。更现实的问题是：
- 前端发请求时写死
/api/v1/，后端想灰度切流？得改客户端或加反向代理重写规则 - Swagger 文档生成时，
v1和v2的 OpenAPI spec 必须完全隔离，无法复用 schema 定义 - 日志和监控里看到
/api/v1/users请求量暴跌，你没法快速判断是客户端下线了，还是新旧版本混用导致路由错配
用 HTTP Header 实现无感版本协商
真正可落地的做法是：所有 API 统一走 /api/users，版本信息由客户端通过 Accept 或自定义 header（如 X-API-Version: 2）声明。服务端解析 header 后，动态选择对应的数据结构、校验逻辑与序列化策略。
-
Accept: application/json; version=1→ 返回UserV1struct，忽略avatar_url字段 -
X-API-Version: 2→ 返回UserV2struct，包含avatar_url且要求email非空 - 未带 version header？走默认版本（比如 v1），但记录 warn 日志提醒客户端补全
关键点在于：版本逻辑应下沉到 handler 内部的 switch 或策略工厂，而不是靠 gorilla/mux 或 gin.Engine 的路径匹配来分流。
gin 和 chi 中的实际处理姿势
以 gin 为例，不要写：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
router.GET("/api/v1/users", userHandlerV1)
router.GET("/api/v2/users", userHandlerV2)
而是统一注册：
router.GET("/api/users", func(c *gin.Context) {
version := c.GetHeader("X-API-Version")
switch version {
case "2":
handleUserV2(c)
default:
handleUserV1(c) // 包含降级兼容逻辑
}
})
对 chi，同样避免用 chi.URLParam(r, "version") 解析路径段；改用 r.Header.Get("X-API-Version")。这样做的好处是：测试时只需改 header，不用构造不同 URL；网关层（如 Kong、Traefik）也能统一做 header 注入或透传，无需重写路径。
版本升级时最容易被忽略的细节
真正的复杂点不在怎么分发，而在「如何让旧版客户端不崩」：
- 数据库 schema 变更（如字段改名、类型扩大）必须兼容旧版 API 的读写逻辑，不能直接删字段
- 如果 v2 引入了新校验（如手机号格式），v1 请求仍需按原规则放行，否则上线即故障
- 错误响应体格式也要保持一致——v1 客户端解析
{"error": "xxx"}，v2 就不能突然改成{"code": 400, "message": "xxx"} - 文档要明确标注每个字段的「首次引入版本」，比如
avatar_url (string, v2+)
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
