go中接口废弃必须通过导出名变更、类型不兼容和go vet可捕获的导入路径变动来强制约束，而非仅注释；应立即将废弃接口移至internal/deprecated/，新接口使用全新类型名或不兼容签名，并配合replace+版本路径双控实现模块间平滑过渡。
接口废弃不能只靠注释，必须用编译器可感知的方式
Go 没有 @Deprecated 这类运行时注解，光在函数前写 // deprecated: use NewClient instead 对调用方毫无约束力。真正起作用的是：导出名变更 + 类型不兼容 + go vet 可捕获的导入路径变动。
常见错误是把旧接口改名后还保留在同一包里，结果新老代码混用导致 panic；或者只删了实现没动接口定义，下游编译仍通过但运行时报 nil pointer dereference。
- 废弃接口应立即从公开包中移除（不是注释掉），改到
internal/deprecated/下供迁移期临时引用 - 新接口必须使用全新类型名（如
UserV2Service而非UserService），避免interface{}强转绕过检查 - 若必须保留同名接口，需让其方法签名不兼容（例如新增必填参数、改返回值类型），迫使调用方显式修改代码
- 用
go vet -vettool=$(which shadow)配合自定义规则扫描旧导入路径，CI 中拦截未清理的import "myproject/user"
多模块间废弃过渡要靠 replace + 版本路径双控
当 modules/user 升级到 v2，而 modules/order 还依赖 v1 时，单纯改 go.mod 的 require 版本会引发构建失败——因为 Go 不允许同一模块两个主版本共存于一个构建图中。
正确做法是利用 replace 指向本地 v1 兼容层，并在 v2 模块中提供显式适配桥接。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
- 在
order/go.mod中写：replace modules/user => ./compat/user-v1-adapter，该目录仅含 v1 接口定义和对 v2 的封装调用 - v2 模块的
go.mod必须声明为module modules/user/v2，强制导入路径变为modules/user/v2 - 根目录
go.mod中禁止直接require modules/user v1.5.0，所有依赖都应经由子模块自己的go.mod声明 - 运行
go list -m all | grep user确认全项目只存在一个user主版本实例
平滑升级的关键是“先上线新模块，再下线旧模块”，而非代码内切换
很多人试图在同一个 HTTP handler 里写 if version == "v2" { ... } else { ... }，这会导致逻辑耦合、测试爆炸、灰度难控。真正的平滑升级发生在部署层：新模块独立进程监听新端口或新服务名，流量逐步切流。
底层接口废弃只是为这个过程扫清障碍，不是替代它。
- 废弃的
user.UserRepo不应在 v2 模块中复用，而应由user/v2.Repo完全重写，哪怕 SQL 语句一样 - API 网关或 service mesh（如 Istio）按模块名+版本标签路由，例如
destinationRule匹配host: user-service, version: v2 - 数据库迁移脚本必须与模块发布强绑定：v2 模块启动前，
user/v2/migration已执行完 schema 变更 - 监控指标按
module="user/v2", handler="GetUser"打点，确保能独立观察新旧模块健康度
最容易被忽略的坑：test 文件里的废弃接口残留
单元测试往往比业务代码更顽固——你删了 user.UserService，但 user/user_test.go 里还留着 mockUserService := &user.UserService{...}，测试照过，上线就崩。
这类问题不会出现在 go build 阶段，只有运行时才暴露，且难以复现。
- 所有 test 文件必须和生产代码走同一套 import 路径规则，禁用
_test后缀包绕过模块隔离 - CI 中加一步：
grep -r "UserService" ./modules/user --include="*.go" | grep -v "_test.go"，确认废弃名彻底消失 - 用
go tool trace抓线上 panic 栈，重点看是否来自user_test.go或mock_*.go这类非生产路径 - 如果模块提供 mock，必须按版本拆分：如
user/v1/mock和user/v2/mock，禁止跨版本复用
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
