必须用 gin.Group() 而非手动拼路径，因其构建显式版本路由树，支撑监控聚合、OpenAPI 识别、Nginx 配置及中间件隔离；手动注册破坏路由结构，导致指标无法打标、文档混乱、缓存失效、权限失控。
直接用 gin.Group() 按路径前缀注册独立路由组，是 Gin 中唯一可运维、可监控、可文档化的多版本路由实现方式。其他方案（header、query）在日志聚合、CDN 缓存、OpenAPI 生成、反向代理配置上都会出问题。
为什么必须用 Group() 而不是手动拼路径
硬编码 r.GET("/v1/users", handler) 看似省事，但会破坏 Gin 的路由树结构：
-
router.Walk()扫不到真实分组关系，Prometheus 指标无法按version="v1"标签聚合 - OpenAPI 工具（如 swag）无法识别版本边界，生成的文档 tag 混乱或丢失
- Nginx 的
location /v1/规则会失效——因为实际路径可能是/users/v1，前缀不匹配 - v1 和 v2 中间件无法隔离：你没法只给 v2 加 OAuth2，而 v1 保留 JWT
Group() 的正确写法和常见错误
正确结构是让每个版本成为显式的子路由树根：
router := gin.Default()
v1 := router.Group("/v1")
v1.GET("/users", getUsersV1)
v1.POST("/users", createUserV1)
v2 := router.Group("/v2")
v2.GET("/users", getUsersV2)
v2.POST("/users", createUserV2)
常见错误包括：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 写成
router.GET("/v1/users", ...)—— 这不是 Group，只是普通路由，不带中间件隔离能力 - 路径嵌套成
/api/v1或/v1/api—— 版本段必须是路径第一级，且无冗余前缀 - 用
v1.2或v1.2.3当版本号 —— HTTP API 版本是契约变更标识，不是软件发布号；v1升v2才表示不兼容变更
DTO 和 handler 必须按版本严格分离
别指望靠 json:"name,omitempty" 复用同一个 struct。v2 新增字段会导致 v1 客户端解析失败，这不是 bug，是契约破坏：
- 为每个版本声明独立 DTO：
V1User、V2User，哪怕字段名完全一致 - handler 内必须显式转换：
c.JSON(200, V1User{...})，不能传 domain model 直接 encode - 数据库变更要兜底：v2 加了 NOT NULL 字段，v1 接口不能因此返回 500，service 层得做兼容处理
- 字段语义变更更危险：比如
status从"active"改成"published"，v1 客户端 if 判断会静默失效
最易被忽略的一点：版本分组不是“写完就完”，它要求整个工程链路对齐——DTO、错误响应格式、文档、SDK 生成、监控指标标签、反向代理 location 配置，都得按 v1/v2 显式切片。漏掉任意一环，线上就会出现缓存错乱、告警失焦或客户端静默降级。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
