应使用r.group()定义/v1、/v2路由分组，而非拼接字符串；各版本需独立dto（如v1fileuploadrequest/v2fileuploadrequest）、显式转换、db变更兜底兼容，路径前缀是唯一被路由、代理、监控、文档工具一致识别的版本标识。
用 r.Group() 定义 /v1、/v2 路由分组，别拼字符串
直接写 r.GET("/files/v1/upload", handler) 看似省事，但会破坏 Gin 的路由结构感知能力。日志、OpenAPI 生成、Prometheus metrics 都没法按版本聚合，Nginx location /v1/ 规则也会失效——因为真实路径是 /files/v1/upload，前缀不匹配。
正确做法是让 Gin 明确知道“这是一个版本边界”：
-
v1 := r.Group("/v1")，然后所有文件接口挂在这下面：v1.POST("/files/upload", uploadV1)、v1.GET("/files/:id", getFileV1) -
v2 := r.Group("/v2")，同样挂载：v2.POST("/files/upload", uploadV2)，支持新字段（如checksum、tags） - 每个分组可独立加中间件：比如
v2.Use(validateChecksumMiddleware)，而v1不受影响
DTO 必须按版本隔离，别复用同一个 FileUploadRequest struct
很多人图省事，给一个 struct 加 json:",omitempty"，想靠字段空值控制输出。结果 v2 新增了必填字段 policy_id，v1 客户端传过来没这个字段，解析失败或静默丢数据——这不是 bug，是契约违约。
每个版本该有自己专属 DTO：
-
V1FileUploadRequest：只有Name、Content -
V2FileUploadRequest：含Name、Content、Checksum、PolicyID，且PolicyID带binding:"required" - handler 内部做显式转换：
c.JSON(201, V1FileResponse{ID: f.ID, URL: f.URL})，绝不直接 encode domain model
数据库变更必须兜底兼容，尤其 NOT NULL 字段
v2 接口要求存 checksum，DB 字段设为 NOT NULL。但如果 v1 请求进来，没传 checksum，不能直接 500 报错——这等于把版本升级成本转嫁给客户端。
service 层必须做兼容处理：
- 对 v1 请求，允许
checksum为空，DB 存空字符串或默认值（如"sha256:unknown"） - 用 GORM 的
Defaulttag 或插入前手动补缺：if req.Version == "v1" { f.Checksum = "sha256:unknown" } - 避免在 DAO 层硬写
INSERT INTO files (..., checksum) VALUES (..., ?)—— 这会让 v1 调用直接崩掉
别用 Accept 头或 query 参数做版本路由
看似干净的 GET /files?id=123&version=v2 或 Accept: application/vnd.myapi.v2+json，实际踩坑极多：
- CDN 和反向代理（Nginx/Envoy）默认不缓存带 query 的响应，或把 v1/v2 响应混存；
Accept头不参与路由匹配，中间件无法拦截，鉴权/限流逻辑得在每个 handler 里重复判断 - OpenAPI 文档工具（如 swag）无法自动生成带版本区分的 endpoint，Swagger UI 里全挤在一个路径下
- 前端调试时 curl 得反复改 header，Postman 要手动设头，协作成本陡增
路径前缀是唯一能被路由、代理、监控、文档工具一致识别的版本标识。/v1 和 /v2 就是事实标准，别绕路。真正难的是 DTO 隔离和 DB 兼容，不是选路径还是 header。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
