protobuf升级破坏wire兼容性的操作包括：改字段类型（如int32→int64）、复用已删除字段的tag编号、修改repeated/optional修饰符、变更enum值编号，均会导致二进制解析失败；新增字段必须用optional或repeated且分配新tag，删除字段须用reserved保留编号。
为什么/v1和/v2路径隔离是最稳妥的选择
因为所有基础设施都认这个：Nginx location 能精确匹配，Envoy VirtualService 可按前缀路由，CDN 缓存键天然区分，日志里一眼看出调用版本，curl 和浏览器调试时 URL 清晰可见。Header 或 query 方式在反向代理链中容易被吞、被覆盖、被忽略——尤其当多个中间件（如 CORS、JWT 验证）顺序执行时，header 解析时机错位就会导致版本误判。
常见错误现象：X-API-Version 在 ingress 层没显式透传，到 Go 服务时已丢失；Accept 头被前端 fetch 默认行为忽略，测试时全走 fallback 版本；query 参数 ?version=v2 被 CDN 当作不同 URL 缓存，但语义上它不该影响资源标识。
- 用
chi.NewRouter()或router.Group("/v1")创建独立路由组，不要把/v1/users和/v2/users注册在同一层 - 每个版本 group 绑定专属中间件（如
v2.Use(authMiddlewareV2())），避免 v1 的鉴权逻辑污染 v2 - Swagger 文档生成必须为每个 group 单独打
@Tags v1和@Tags v2，否则@Success 200 {object} UserV1和UserV2会混在一起
struct 字段变更如何不破坏 JSON 兼容
Go 的 json.Marshal 对新增字段默认设零值，但前提是字段必须是**指针类型 + omitempty 标签**。否则 string 类型字段即使为空也会序列化为 "name": ""，v1 客户端可能把它当有效值解析并 panic。
常见错误现象：v2 新增 Email string `json:"email"`，v1 客户端收到 {"email": ""} 后触发空邮箱校验失败；或直接删掉 v1 struct 字段，导致数据库 scan、gob 序列化、反射调用全部报错。
- 新增字段一律用
*string、*int64等指针类型，并加json:",omitempty" - 废弃字段不能删，改成未导出字段，例如
oldName string `json:"old_name,omitempty"`，加注释// deprecated: use FullName instead - 重命名字段时双写：保留旧字段 + 新字段，用自定义
UnmarshalJSON处理过渡期
接口方法变更为何不能直接往旧 interface 加函数
Go 的 interface 是隐式实现的。一旦你把 type UserService interface { Get(); Update() } 改成 Get(); Update(); Notify()，所有只实现了前两个方法的老 service 实例就无法再赋值给该接口变量，编译直接报错：cannot use (*OldService) as type UserService in assignment: *OldService does not implement UserService (missing Notify method)。
常见错误现象：为“兼容”让旧实现返回 nil 或空操作，结果调用方 if err != nil 判定失败后 panic；或 mock 测试因缺失方法而失效，CI 直接挂掉。
- 冻结旧 interface，不再修改其方法签名
- 新增能力用新 interface 表达，例如
UserNotifier，v2 handler 依赖它，v1 handler 不感知 - 拆成小接口：把上帝接口
UserAPI拆成UserReader、UserWriter、UserExporter，v2 只需新增UserExporter - 废弃方法保留签名，内部返回
errors.New("deprecated: use UserNotifier instead")
Protobuf 升级时哪些操作会破坏 wire 兼容性
gRPC 接口升级翻车，90% 出在 wire-level 不兼容：Protobuf 解析器只看 tag 编号和 wire type，不是 Go struct 字段名或类型别名。哪怕你改了 Go 字段名，只要 tag 没变，wire 层就安全。
常见错误现象：把 int32 user_id = 1; 改成 int64 user_id = 1;，老客户端发来的 varint 编码数据被新服务当作 8-byte 解析，直接崩溃；或重用已删除字段的 tag，导致旧数据被错误映射到新字段。
- 新增字段必须设
optional（proto3）或repeated，tag 号不能复用旧字段 - 删除字段只能用
reserved 1;，不能真的删掉那行定义 - 改字段类型（
int32↔int64）、改 repeated/optional、改 enum 值编号，全部禁止 - 用
buf check breaking在 CI 里自动扫描，比人工 review 更可靠
/v2 路径，而是字段零值怎么不出现在响应里、老 client 怎么不因新 error code 崩溃、protobuf tag 编号谁动过谁没动过——这些细节不靠规范约束，光靠人盯，迟早出事。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
