Go微服务版本兼容核心是守住接口契约：protobuf字段变更需遵守wire兼容规则，HTTP路径须用/v1、/v2前缀隔离，错误码语义跨版本对齐，服务发现需支持多版本实例共存。
Go 微服务的版本兼容管理，核心不在“加版本号”，而在“接口契约不破坏”——只要 protobuf 定义、HTTP 路径语义、错误码含义、字段可选性这四点守住了，v1 和 v2 服务就能共存且平滑升级。
Protobuf 字段变更必须遵守 wire 兼容性规则
gRPC 接口升级最常翻车的地方是随意删字段、改类型或重用 tag。Protobuf 的 wire-level 兼容性只认 tag 编号和 wire type，不是 Go struct 标签。
- 新增字段：必须设
optional（proto3）或repeated，tag 号不能复用旧字段 - 删除字段：只能标记为
reserved，不能真的删掉 tag 行；老客户端发来的该字段数据会被忽略 - 改字段类型：比如
int32→int64，wire type 不同（varint vs. 8-byte），会解析失败，禁止 - 重命名字段：可以，但 tag 编号必须不变；生成的 Go struct 字段名可变，不影响 wire
验证方式：用 protoc 的 --descriptor_set_out 导出 descriptor，再用 buf check breaking 扫描兼容性。
HTTP API 版本路径应隔离而非覆盖
别用查询参数或 header 做版本路由（如 ?version=v2），它会让网关/监控/日志全部失效。路径前缀才是唯一靠谱的方式。
立即学习“go语言免费学习笔记（深入）”；
- 正确：
/v1/users和/v2/users是两个独立 endpoint，可分别部署、灰度、下线 - 错误：
/users?api_version=2—— 无法被 Istio VirtualService 或 Nginx location 精确路由 - 注意：
/v1不代表“只支持旧协议”，而是“该路径下所有行为契约锁定”，包括 status code 含义（比如404表示用户不存在，不能某天改成400）
Go 中用 gorilla/mux 或 chi 时，建议按版本分 router 实例：v1Router := chi.NewRouter()，避免路由混杂。
【极品模板】出品的一款功能强大、安全性高、调用简单、扩展灵活的响应式多语言企业网站管理系统。 产品主要功能如下： 01、支持多语言扩展（独立内容表，可一键复制中文版数据） 02、支持一键修改后台路径； 03、杜绝常见弱口令，内置多种参数过滤、有效防范常见XSS； 04、支持文件分片上传功能，实现大文件轻松上传； 05、支持一键获取微信公众号文章（保存文章的图片到本地服务器）； 06、支持一键
错误码与业务语义必须跨版本对齐
很多团队在 v2 加了新校验，返回了新 error code（比如新增 422 表示“邮箱格式过期”），但老客户端没处理，直接 panic 或静默失败。
- 新增错误码：必须确保老客户端能安全 fallback（例如统一当
400处理，或至少不 crash） - 重定义已有 code：禁止。比如把原来
409 Conflict改成表示“配额超限”，老前端会误判为“资源冲突” - 推荐做法：在 error detail 中用
google.rpc.Status嵌入 machine-readable reason（如reason: "EMAIL_FORMAT_DEPRECATED"），HTTP status 仍用通用 code
Go 服务中，建议封装统一的 WriteError(w, err) 函数，内部根据 error 类型映射 status code，并始终写入 X-Error-Reason header 供调试。
服务发现与客户端需支持多版本实例共存
Kubernetes Service 或 Consul 默认只按 service name 负载均衡，如果 user-service-v1 和 user-service-v2 都注册到同一个逻辑名下，流量就不可控。
- 方案一（推荐）：用不同 service name + label，如
user-service+version:v1，客户端通过服务发现拿到带 label 的实例列表 - 方案二：用 Istio VirtualService 按 header（如
apiversion: v2）路由，但要求所有调用方显式携带，运维成本高 - Go 客户端 SDK 必须支持传入 version hint，例如
userClient.Get(ctx, id, WithAPIVersion("v2"))，底层自动拼路径或设 header
最容易被忽略的是健康检查路径：/health 必须保持无版本语义，而 /v1/health 和 /v2/health 应返回各自版本的内部状态——否则 k8s readiness probe 会误杀 v2 实例。
