路径前缀式版本路由（/v1、/v2）是唯一能兼顾调试性、缓存友好性与监控准确性的方案；必须禁用Accept头或query参数做主路由，严格隔离DTO结构体、中间件及路由实例，并通过显式转换确保API契约稳定。
路径前缀是唯一能兼顾调试、缓存和监控的方案
别用 Accept 头或 X-API-Version 做主路由，也别拼 ?version=v2。这些方式会让 CDN 缓存失效、Prometheus 指标混杂、Nginx 日志无法按版本聚合、Postman 测试要反复确认 header 是否传对。真实线上故障里，70% 的版本问题源于 header 解析逻辑分散在多个中间件中，而 /v1/users 一眼就能从 access log 和 Grafana 中定位到流量归属。
必须统一用小写路径前缀：/v1、/v2，禁止混用 /api/v1 和 /v1/api —— 否则 chi.Mount() 会挂载失败，路由树结构直接乱掉。
chi.Router 必须物理隔离 v1/v2 实例
常见错误是把所有 handler 写在一个 router 里：r.Get("/v1/users", ...) 和 r.Get("/v2/users", ...) 并列注册。这会让路由树扁平化，失去分组能力，中间件也无法按版本启用。
正确做法是：
立即学习“go语言免费学习笔记（深入）”；
- 每个版本调用
chi.NewRouter()新建独立实例 - 用
r.Mount("/v1", v1Router)和r.Mount("/v2", v2Router)挂载 - v1 和 v2 的中间件必须分开注册，比如
v2.Use(rateLimitV2)不能复用 v1 的鉴权中间件 - handler 函数名带版本标识：
v1GetUsersHandler、v2GetUsersHandler，避免误调用
DTO 结构体必须按版本完全隔离
共用一个 User struct 是最隐蔽的兼容性炸弹。Go 的 JSON 序列化没有运行时 schema 校验，v2 加了 Nickname string `json:"nickname"`，如果 v1 handler 不小心用了 User{} 返回，v1 客户端解析就会 panic。
关键约束：
- 哪怕字段完全一样，也要定义
UserV1和UserV2两个 struct - 不要用指针“模拟可选字段”来凑合老版本：v1 的
Name string就该是 string；v2 改成Name *string是它的契约，不能反向污染 v1 - 数据库模型（如 GORM
UserModel）保持稳定，只负责存储；所有 API 层响应都走显式转换：return c.JSON(200, UserV1{...})
错误码语义和字段变更必须跨版本锁定
很多团队在 v2 加新校验后返回新 error code（比如 422 表示“邮箱格式过期”），但老客户端没处理，直接 crash。这不是功能问题，是契约破坏。
必须守住四点：
-
HTTP status code含义不能变：404 永远表示“资源不存在”，不能某天改成 400 - 新增字段只能是
optional或repeated，且 tag 编号不能复用旧字段 - 废弃字段只能
reserved，不能真删；老客户端发来的数据仍需被忽略而非报错 - 错误 detail 里用
google.rpc.Status嵌入 machine-readablereason（如reason: "EMAIL_FORMAT_DEPRECATED"），HTTP 状态码仍用通用值
最易被忽略的是：路径前缀不只是加个 /v1，它是整个行为契约的锚点——包括字段是否必填、409 表示什么、甚至日志字段命名规则。一旦挂载，就再也不能靠中间件“动态切版本”。
