必须用 r.group("/v1") 和 r.group("/v2") 定义版本路由，因其保障可维护性、可观测性与部署隔离；硬编码路径破坏路由语义，导致 walk() 失效、openapi 文档混乱、中间件无法按版本挂载、nginx 前缀匹配失败。
直接用 r.Group("/v1") 和 r.Group("/v2") 定义版本路由，是 Gin 中唯一能兼顾可维护性、可观测性和部署隔离的方案。其他方式——比如拼接路径、用 query 或 header 控制版本——都会在调试、监控或网关配置上出问题。
为什么必须用 Group() 而不是手写 r.GET("/v1/users", ...)
硬编码路径前缀看似省事，但会破坏 Gin 的路由语义，导致三类实际故障：
-
router.Walk()扫不出真实分组结构，OpenAPI 工具生成文档时混入 v2 字段，v1 客户端看到不该有的字段 - 中间件无法按版本启用：你想给 v2 加 JWT 校验，但没地方挂，只能在每个 handler 里重复写
if strings.HasPrefix(c.Request.URL.Path, "/v2/") - Nginx location /v1/ 规则失效——因为 handler 实际注册的是
/users，而你拼的是/v1/users，前缀不一致
Group() 下的子路由路径怎么写才不出错
子路由路径必须以 / 开头，且不含版本前缀；Group() 已自动剥离前缀，c.Request.URL.Path 拿到的是 /users，不是 /v1/users：
- ✅ 正确：
v1 := r.Group("/v1"); v1.GET("/users", handler)→ 实际匹配/v1/users，handler 内c.Request.URL.Path是/users - ❌ 错误：
v1.GET("users", handler)→ 匹配/v1users（无斜杠，路径粘连） - ❌ 错误：
v1.GET("/v1/users", handler)→ 匹配/v1/v1/users（重复前缀）
DTO 结构体必须按版本拆开，哪怕字段一模一样
共用 User struct 是最大陷阱。v2 新增 Nickname string 字段后，v1 客户端收到该字段，前端 JSON.parse() 直接报错——这不是 bug，是契约断裂。
- 定义
UserV1和UserV2两个独立 struct，即使当前字段名、类型完全相同也分开声明 - handler 内统一调用 service 层获取 domain model，再显式转换：
c.JSON(200, UserV1{...})或c.JSON(200, UserV2{...}) - 禁止用
json:",omitempty"控制字段输出——它无法表达“v1 绝对不返回，v2 必须返回”的强契约
中间件挂载位置决定作用域
中间件是否生效，取决于你把它挂在哪一级 RouterGroup 上：
- 只挂
v2.Use(JWTV2Middleware())→ v1 不受保护，裸奔 - 挂根路由
r.Use(LogMiddleware(), TraceIDMiddleware())→ 所有版本共享日志和 trace 注入 - 想让 v1 用 session、v2 用 JWT？必须分别挂：
v1.Use(SessionAuth())和v2.Use(JWTV2Auth())
最容易被忽略的是：路由注册顺序影响匹配。如果 r.GET("/v1/:id", ...) 写在 v1 := r.Group("/v1") 之前，它会截获所有 /v1/xxx 请求，导致 v1.GET("/users", ...) 永远不执行。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
