探讨Golang模块依赖管理中多版本API设计的演进与重构

到了 Go 模块的 v2 及以上版本，目录必须明确改成 /v2，同时把 go.mod 和所有 import 路径一并更新到位；API 版本管理更推荐走路径前缀，而不是依赖 Accept 头；DTO 也要拆分清楚，保持独立定义；replace 只适合开发阶段使用，正式发布时必须改为 require 并打上 tag；至于版本下线，不能只停留在口头层面，监控、告警和降级这些环节都得闭环，这才算真正落地。

Go模块路径中v2+后缀必须显式重命名目录

不改目录名，go build 就会报 cannot find module providing package。Go 的模块系统靠 import 路径后缀（如 /v2）识别版本，不是靠 go.mod 里写个新路径就能生效。

• 模块根目录必须从 myapi/ 改成 myapi/v2/
• go.mod 中的 module 行要同步改成 example.com/myapi/v2
• 所有内部 import 语句，包括同模块子包引用（如 example.com/myapi/v2/handler），都要带 /v2
• 如果用了 go.work，确保它包含的是 myapi/v2 目录，而不是顶层 myapi

URL路径版本比Accept头更可靠

如果用 Accept: application/vnd.myapi.v2+json 来做版本路由，正式上线后往往很容易出问题：前端的 fetch 默认并不会主动带上 Accept，curl 测试时也常常因为漏配 header 导致结果失真，OpenAPI 工具在生成文档时还可能把 v1 和 v2 接口混到一块儿，甚至连 Nginx 这层都得额外补一套基于 header 的匹配规则。

• 推荐统一走路径前缀，如 /api/v1/users 和 /api/v2/users
• Gin/Echo 等框架用 Group("/v2") 即可天然隔离中间件、认证逻辑和限流策略
• 网关、CDN、日志聚合都按 path 统计和分发，调试时 curl 一眼看清调的是哪个版本

v1/v2 DTO 必须分离，别靠 json tag 覆盖字段名

想在 v2 把 name 改成 full_name，只改 struct tag 是错的——老客户端仍发 {"name":"Alice"}，服务端必须能接收并兼容处理。

• 定义独立 DTO：UserV1 和 UserV2，不要共用同一 struct
• 嵌入复用用值类型：type UserV2 struct { UserV1; CreatedAt time.Time }，别用 *UserV1（零值问题）
• 字段重命名必须新增字段，比如 v2 加 FullName string，同时保留 Name string 并在 handler 中做映射
• 数据库模型（db.User）与 API 层完全隔离，用显式转换函数（如 toUserV1()）桥接，禁用 map[string]interface{} ——IDE 跳转和编译检查全失效

多模块项目中 replace 不是长期方案

本地开发时用 replace example.com/myapi/v2 => ./myapi/v2 没问题，但 CI 构建或发布镜像时，如果没清理缓存或没打 tag，很容易拉到旧版本。

• replace 只在当前模块生效，子模块若直接 require 远程 v2，可能实际加载的是 v1
• 上线前必须运行 go list -m all | grep myapi 确认解析出的确实是 v2.0.1，而非 v1.9.3
• 真正稳定发布时，应删掉 replace，改用 require example.com/myapi/v2 v2.0.1，并确保该 tag 已推送到远端
• 如果依赖方还没升级，别硬推 v2，先提供 v1 兼容层，或推动对方适配；用 exclude 会破坏构建，不是解法

实际演进中最容易被忽略的点：版本下线不是删代码，而是监控 + 告警 + 降级三步闭环。只要还有请求打到 /v1，对应 handler 就不能删——哪怕只是返回 410 Gone 并记录 trace ID，也比 panic 强。