API版本升级需全链路隔离：路由、参数、逻辑、响应及依赖必须严格分离，避免破坏性变更影响旧客户端；禁止在handler内用if-else判断版本，应通过独立中间件分流并提前校验；参数绑定须用版本专属结构体，数据库查询与响应结构亦须彻底拆分；基础依赖升级后需全量E2E验证v1/v2兼容性。
API 版本升级中出现破坏性变更，不是靠“兼容层”硬扛就能解决的——它必须从路由、参数、逻辑、响应到依赖全部隔离。否则一个 v2 的字段重命名或分页方式切换，就会让 v1 客户端返回 500 或静默丢数据。
路由与中间件必须按版本分流
别用 if-else 在 handler 里判断 X-API-Version 后走不同分支。这种写法会让日志、监控、中间件行为混杂，且容易漏掉 header 解析失败时的 fallback 路径。
- 用独立中间件提取版本，并提前 abort 不支持的值，例如只放行
v1和v2，其他直接 400 - 路由注册时显式区分：
router.GET("/api/v1/users", handlerV1)和router.GET("/api/v2/users", handlerV2)，避免路径复用导致的缓存污染 - 若必须共用路径（如通过 header 控制），中间件中需调用
c.Set("api_version", version)，后续所有 handler、validator、logger 都要基于这个 key 做分支，而不是反复解析 header
参数结构体和绑定必须彻底拆开
ShouldBindQuery 不会自动跳过字段缺失，也不会忽略多余字段——但它能“静默忽略”结构体里没有定义的 query 参数。这是实现版本隔离的关键机制。
-
v1用type V1Pagination struct { Page int `form:"page" binding:"required,min=1"` PageSize int `form:"page_size" binding:"required,max=50"` } -
v2用type V2Pagination struct { Cursor string `form:"cursor"` Limit int `form:"limit" binding:"max=100"` }，不带requiredtag - 绝对不要在
v2handler 里复用v1的结构体变量并调用c.ShouldBindQuery(&v1Params)，Gin 会因缺少page字段而报 validation error - 旧客户端传了
page但 handler 是v2？没问题，ShouldBindQuery(&v2Params)直接忽略它——这才是设计预期
数据库查询与响应结构不能共享逻辑
offset 分页和游标分页不只是“换种算 offset 的方式”，它们对应完全不同的 SQL 模式、索引策略和可观测指标。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
-
v1查询用db.Offset((page-1)*size).Limit(size)，总数统计用db.Count(&count) -
v2查询用db.Where("id > ?", cursor).Order("id ASC").Limit(limit)，不查总数，只判断是否有下一页：db.Limit(limit + 1).Find(&results); hasNext = len(results) > limit - 响应结构体必须分开定义：
PaginatedResponseV1{Total: count, Data: items}vsPaginatedResponseV2{Data: items, NextCursor: lastID, HasNext: hasNext} - 别试图用一个通用
Paginator接口包装两者——它们的语义边界清晰，强行抽象只会把条件判断下沉到更难测的底层
第三方依赖升级可能意外触发版本断裂
你没动 API 代码，但 go get github.com/golang-jwt/jwt/v4@latest 后 v1 的 token 解析突然失败，大概率是 JWT 库的 Parse 行为变更（比如 v4.5.0 开始默认禁用 unsafe 算法）影响了旧版签名验证逻辑。
- 检查
go.mod中该模块是否带/v4路径，确认你导入的是github.com/golang-jwt/jwt/v4而非旧的github.com/dgrijalva/jwt-go - 运行
go list -m -u all | grep jwt，看是不是间接依赖拉高了版本；若是，用replace锁死已验证可用的子版本，例如replace github.com/golang-jwt/jwt/v4 => github.com/golang-jwt/jwt/v4 v4.4.1 - 对 JWT、validator、database driver 这类基础依赖，每次升级后必须跑通全量
v1和v2的 E2E 测试用例，不能只测新增功能
最常被跳过的环节是：你以为改了 handler 就完事，其实中间件里的日志字段、监控指标标签、OpenAPI 文档生成器的 schema 扫描、甚至 Swagger UI 的默认请求示例，都可能还绑在旧版结构体上。版本变更不是单点替换，是一次横跨 HTTP 层到数据层的契约刷新。
