路径前缀（如/v1/users）是API版本管理最稳妥方案，因它能统一网关、缓存、监控与文档；Header和Query方式易致缓存失效、路由错配；DTO和proto须按版本严格隔离，避免兼容性风险。
URL路径嵌入版本号（如/v1/users和/v2/users）是当前最稳妥、可维护性最强的方案，其余方式（Header、Query）在真实生产中容易引发缓存失效、路由错配、调试困难等问题。
为什么必须用路径前缀而不是Accept头或X-API-Version
Accept头协商虽符合REST语义，但在Go微服务落地时会显著增加复杂度：gin/chi等框架不原生支持按media type分发handler；CDN、Nginx、Istio VirtualService无法基于Accept头做精准路由；日志和监控里看不到版本标识，排查问题要翻原始请求体。X-API-Version看似简单，但绕过所有基础设施的版本感知能力——你没法用location /v2做灰度，也不能让Prometheus按api_version维度统计错误率。路径前缀是唯一能让网关、缓存、文档、测试、运维全部对齐的方案。
- 别用
?version=v2：违反资源标识原则，GET请求带query参数无法被CDN缓存 - 别在handler里写
if version == "v2"：逻辑混杂，单元测试覆盖难，升级时易漏改某条分支 - Accept头只适合极少数场景，比如同一端点需返回不同序列化格式（JSON/XML），而非API行为变更
如何用chi或gorilla/mux做真正的版本隔离
关键不是“注册两个路由”，而是让v1和v2拥有完全独立的中间件栈、handler生命周期和错误处理逻辑。chi的Mount或gorilla的Subrouter不是语法糖，是隔离边界。
- 每个版本用独立
chi.Router实例，例如v1 := chi.NewRouter()，再r.Mount("/v1", v1) - 不要把
/v1/users和/v2/users注册到同一个router下——这会丢失子路由树结构，导致中间件无法按版本启用（比如v2需要额外JWT校验，v1不需要） - 若用gorilla/mux，必须用
subr := r.PathPrefix("/v1").Subrouter()，而非r.Path("/v1/users")，否则无法复用子路由中间件 - 版本前缀统一小写
v1、v2，避免/api/v1和/v1/api混用造成歧义
DTO必须按版本拆开，不能靠指针字段“凑合”
共用一个User struct加*string字段来模拟v1/v2差异，短期省事，长期必踩坑：OpenAPI生成会混入v2字段到v1文档；JSON序列化时omitempty行为不可控；数据库映射层容易误用字段；单元测试难以隔离验证。
立即学习“go语言免费学习笔记（深入）”；
- v1响应定义
UserV1：字段全为非空值，Name string，无Nickname - v2响应定义
UserV2：新增Nickname string，Name改为*string并加omitempty - 数据库模型（如GORM struct）保持稳定，只负责存储；API层用手动赋值或
mapstructure.Decode做DTO ↔ domain转换 - Swagger注释必须绑定到对应版本group，否则
// @Success 200 {object} UserV2会污染v1文档
protobuf字段变更的硬约束比HTTP更严格
gRPC接口的wire-level兼容性不看Go struct，只认proto tag编号和wire type。随意改字段类型或重用tag，老客户端直接解析失败，且错误堆栈难以定位。
- 新增字段必须设
optional（proto3）或repeated，tag号不能复用旧字段 - 删除字段只能
reserved 3;，不能删掉整行；老客户端发来的数据会被忽略 -
int32 → int64禁止：wire type从varint变成8-byte，解析器直接panic - 重命名字段可以，但tag编号必须不变；生成的Go struct字段名不影响wire兼容
- 用
buf check breaking扫描proto变更，比人工review可靠得多
真正麻烦的从来不是怎么加版本号，而是当v3上线时，v1的DTO还在被某个遗留Android App调用，v2的数据库查询逻辑正被新前端依赖——这时候路径隔离、DTO分离、proto tag守则，每一条都是防止雪崩的护栏。别省那几行代码，也别信“临时兼容一下”的承诺。
