golang微服务版本控制需实现v1与v2共存、隔离且互不破坏，核心是路径前缀（/v1、/v2）显式分组、protobuf wire兼容变更、服务注册携带version metadata、k8s滚动更新+go优雅关闭协同，全链路对齐版本语义。
HTTP 路径前缀必须用 /v1、/v2 隔离
别用 X-API-Version header 或 ?version=v2 做路由依据，它们在真实链路中极易丢失或被忽略。
- Nginx、Envoy、Istio VirtualService 等只认路径，
/v1/users和/v2/users是两个完全独立的 endpoint，可分别配置路由、限流、监控和灰度策略 - 用
chi.NewRouter()或gin.Group("/v1")显式分组，避免 handler 里写if version == "v2"这种混杂逻辑 - Swagger 文档工具（如 swaggo）需为每个 group 单独加
@Tags v1，否则生成的 OpenAPI 会把所有版本混在一起，调试和 SDK 生成全乱套
Protobuf 字段变更必须遵守 wire 兼容规则
gRPC 接口升级翻车最多的地方，就是以为改个 Go struct 字段名或类型没关系——其实 wire 层根本不看 Go 名字，只认 tag 编号和 wire type。
- 新增字段：必须声明为
optional（proto3）或repeated，且tag号不能复用已删除字段的编号 - 删除字段：只能写
reserved 3;，不能删整行；老客户端发来的该字段数据会被忽略，但解析不会失败 - 禁止改类型：比如
int32→int64，wire type 从 varint 变成 8-byte，直接解析 panic - 验证方式：
protoc --descriptor_set_out=api.pb --include_imports *.proto+buf check breaking api.pb
Kubernetes 滚动更新 + Go 优雅关闭是平滑升级底线
没这俩，谈不上“平滑”。K8s 控节奏，Go 控连接生命周期。
- Deployment 中必须设
strategy.rollingUpdate.maxSurge: 1和maxUnavailable: 0，确保新 Pod 就绪后才下掉旧 Pod - 就绪探针（
readinessProbe）必须指向真实业务健康接口（如/healthz），不能只是进程存活 - Go 服务要监听
SIGTERM，调用srv.Shutdown(ctx)，并设置合理超时（建议 15–30s）；别忘了在 shutdown 前关闭数据库连接池、取消 long-polling 上下文等资源 - 常见坑：
srv.Shutdown后没等 goroutine 清理完就 exit，导致日志丢、metric 没上报、连接强制断开
服务注册中心必须带 version metadata
光靠路径和 protobuf 不够，实例层也得能区分版本，否则网关或 client SDK 根本没法做灰度路由。
- 注册到 Consul/Nacos/Etcd 时，必须传
metadata["version"] = "v2.1.0"，不是写在 service name 里（如user-service-v2） - 客户端负载均衡器（如 kit/kit 的 selector 或自研 client）要支持按 metadata 过滤，例如只选
version=v2.1.0 & stage=canary的节点 - 错误做法：用环境变量或 flag 控制启动哪个 handler 版本——这会让单个 Pod 承载多版本逻辑，无法单独扩缩、无法精准灰度、无法快速回滚
srv.Shutdown 或配个 /v2 路由，而是所有环节——从 Protobuf 定义、HTTP 路径、注册元数据、网关规则、client SDK、监控打标——都得对齐同一个版本语义。漏掉任意一环，所谓“平滑”就会在某个凌晨三点崩出一个诡异的 400。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
