Go API版本切换本质是路由分发与代码组织，应采用路径前缀（如/v1、/v2）硬隔离，各版本独立注册路由、中间件及DTO结构体，禁用query或header主路由，确保调试直观、CDN友好、监控可分。
Go 本身不提供运行时 API 版本切换能力，所谓“版本切换”实际是路由分发 + 代码组织 + 工具链协同的结果。直接改 go.mod 里的 go 1.21 行不会让 handler 自动切到 v2 逻辑——那只是编译器语言特性约束；真正的 API 版本切换发生在 HTTP 请求到达时的路由选择环节。
用路由前缀（如 /v1、/v2）做硬分离
这是最可靠、调试最直观、CDN/代理最友好的方式。所有主流 Go Web 框架都原生支持按路径前缀分组：
-
gorilla/mux：用router.PathPrefix("/v2").Subrouter()创建独立子路由，互不影响中间件和 panic 恢复逻辑 -
gin：用r.Group("/v2")返回新*gin.RouterGroup，其GET/POST绑定的 handler 完全隔离 -
echo：用e.Group("/v2")，同样支持独立中间件栈（比如 v2 要求 JWT scope，v1 只需 basic auth） - 别把版本号塞进 query（
?v=v2）——缓存系统、日志聚合、CDN 都会丢失语义，且net/http的Handler接口无法按 query 自动 dispatch
避免在 handler 里写 if version == "v2" 分支
这种写法短期快，长期难维护。一旦 v3 加入字段校验或新 DB 查询，handler 会迅速变成嵌套 if-else 泥潭。正确做法是物理隔离：
- 目录结构按版本划分：
handlers/v1/user.go和handlers/v2/user.go各自实现完整业务流 - 共享模型用指针字段扩展，而非继承或 interface 强耦合（例如
v2.User内嵌v1.User，只新增Permissions *[]string） - 共用 service 层时，通过参数传入版本上下文（如
svc.GetUser(ctx, id, Version("v2"))），但仅限行为差异极小的场景 - 绝不让
v1handler 直接调用v2的函数——版本边界必须清晰可测
注意 go 工具链版本与 go.mod 声明的匹配
API 版本和 Go 语言版本是两回事，但混用时容易触发隐性错误：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 如果
go.mod写着go 1.21，却用go1.20.14执行go run，会报错compile: version "go1.20.14" does not match go tool version "go1.21.13" - 多 Go 版本共存时，别手动改
$GOROOT和$PATH—— 用gvm管理，执行gvm use go1.21.13后，go version和go env GOROOT自动对齐 - 项目根目录下放
.gvmrc（内容为export GVM_GO_VERSION="go1.21.13"），进目录即自动切换，避免不同项目间污染 -
GOMODCACHE必须随 Go 版本切换而隔离（go env -w GOMODCACHE="/path/to/v21/cache"），否则go mod tidy可能复用旧版下载的 module，引发missing GOSUMDB校验失败
不要依赖 Accept header 做主版本路由
用 Accept: application/vnd.myapp.v2+json 做内容协商适合格式微调（如加 metadata 字段），不适合行为级变更：
- v2 若新增权限校验、改用 POST 替代 GET、或返回结构完全不同的 payload，靠 header 解析后 if-else dispatch 会让 handler 失去单一职责
- curl 测试要加
-H "Accept: ..."，浏览器直接访问看不到效果，前端联调成本陡增 - 反向代理（如 Nginx）默认不转发自定义 header，需要显式配置
proxy_pass_request_headers on - 若真要用，务必设默认 fallback（如 header 缺失时走 v1），并在响应头中返回
X-API-Version: v1显式告知客户端当前生效版本
真正麻烦的从来不是怎么写两个 /v1 和 /v2 路由，而是当 v1 进入维护期后，如何确保没人往里面塞新逻辑、如何让 CI 拒绝 v1 目录的非 bugfix 提交、以及怎么让文档生成器自动标注已弃用接口——这些才是版本切换落地时最容易被跳过的点。
