Go接口版本演进需冻结旧接口、用组合替代继承、结构体字段用指针+omitempty、路由按/v1/v2物理隔离、新增能力通过新接口或适配器实现，确保向后兼容。
Go 没有接口版本语法，所谓“接口版本演进”本质是人为约束下的契约管理——不改旧接口、不删旧字段、用组合代替继承、靠路由和结构体设计兜底兼容性。
为什么不能直接修改已有接口定义
Go 的 interface 是隐式实现的，一旦你从 type UserService interface { Get(); Update() } 改成 type UserService interface { Get(); Update(); Notify() }，所有只实现了前两个方法的旧 service 实例就无法再赋值给该接口变量，编译直接报错：cannot use ... (type *OldService) as type UserService in assignment: *OldService does not implement UserService (missing Notify method)。
常见错误现象：把 v2 新增方法塞进老接口，导致大量 handler、mock、测试全部失效；或为“兼容”强行让旧实现返回 nil / 空操作，结果调用方 panic 或逻辑错乱。
- 接口应极小粒度，比如拆成
UserReader、UserWriter、UserExporter，v2 新增导出能力只需加新接口，不影响旧代码 - 废弃方法不能删，而要保留签名，内部返回
errors.New("deprecated: use UserNotifier instead")并加注释 - 避免定义包含 5+ 方法的“上帝接口”，那是版本演进的定时炸弹
结构体字段变更如何不破坏 JSON 兼容
Go 的 json.Marshal 对缺失字段默认忽略，对新增字段默认设零值——但前提是字段必须是**指针类型 + omitempty 标签**，否则非空字段会强制序列化，v1 客户端解析失败。
例如，v1 响应结构：
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"`
}
v2 扩展时，正确做法是：
type UserV2 struct {
ID int `json:"id"`
Name string `json:"name"`
Email *string `json:"email,omitempty"` // 指针 + omitempty
Avatar *string `json:"avatar_url,omitempty"`
}
- 不要用
string而要用*string，否则 v1 客户端收到空字符串会误判为有效值 - 不要省略
omitempty，否则Email: ""会被序列化，v1 解析器可能崩溃 - 禁止在 v1 结构体上直接加字段——哪怕加了
omitempty，也违背“旧结构体不变”原则，容易引发反射、gob、数据库 scan 等隐式依赖问题
HTTP 路由层必须用路径前缀隔离版本
别信中间件里 parse X-API-Version 或 query 参数 ?v=2，线上故障 70% 出在这儿：CDN 缓存失效、日志查不到版本、Nginx location 匹配错、OpenAPI 文档生成混乱。
正确姿势是用独立路由实例挂载：
v1Router := chi.NewRouter()
v1Router.Get("/users", v1GetUsersHandler)
v1Router.Post("/users", v1CreateUserHandler)
v2Router := chi.NewRouter()
v2Router.Get("/users", v2GetUsersHandler) // 可含分页、字段扩展等
v2Router.Post("/users", v2CreateUserHandler)
r.Mount("/v1", v1Router)
r.Mount("/v2", v2Router)
- 每个版本用独立
chi.NewRouter()，避免中间件污染（比如 v2 需要 rate limit，v1 不需要） - handler 函数名带版本标识，如
v1GetUsersHandler，防止误复用 - 响应结构体、DB 查询逻辑、校验规则全部按版本拆包，禁止共用一个
Userstruct
适配器模式用于跨版本逻辑桥接
当旧业务逻辑必须对接新接口时，别硬改老代码，用适配器封装转换。比如 v1 的 SendEmail(user *UserV1) 要调用 v2 的 Notifier.Send(ctx, &NotifyReq{UserID: user.ID, To: user.Email})：
type V1EmailAdapter struct {
notifier Notifier
}
func (a *V1EmailAdapter) SendEmail(user *UserV1) error {
req := &NotifyReq{
UserID: user.ID,
To: user.Email,
Type: "email",
}
return a.notifier.Send(context.Background(), req)
}
- 适配器只做最小转换，不掺杂业务逻辑
- 旧代码继续注入
*V1EmailAdapter，完全无感 - 后续下线 v1 时，直接删掉适配器，不波及原有调用链
最易被忽略的一点：兼容性不是“让新代码迁就旧客户端”，而是通过物理隔离（路由）、契约冻结（接口/结构体）、显式转换（适配器）三者配合，把变化关进笼子——只要路径前缀没变、JSON 字段没强求、接口方法没删，v1 客户端就能永远跑下去，哪怕背后服务已重构三次。
