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，很容易拉到旧版本。
立即学习“go语言免费学习笔记（深入）”；
-
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 强。 
