旧函数调用时可通过包装函数+sync.Once实现首次调用自动打印弃用警告，需严格保持原函数签名、仅提示一次、避免panic，并配合godoc注释提升IDE识别度。
旧函数调用时如何自动打印弃用警告
Go 本身不支持像 Python 的 @deprecated 或 Java 的 @Deprecated 那样在运行时自动触发警告，必须手动在包装函数里显式输出。最直接的方式是用 log.Printf 或 fmt.Fprintf(os.Stderr, ...)，但要注意：只在首次调用时提示一次，避免刷屏。
- 用包级变量
var warnedOldFunc sync.Once控制仅提示一次 - 警告信息需包含旧函数名、推荐替代函数名、以及建议的迁移路径（如 “请改用
NewDoSomething()”） - 不要用
panic或log.Fatal—— 这会破坏兼容性，违背“平滑”目标 - 若函数被高频调用（如 in hot loop），警告逻辑要足够轻量，
sync.Once比atomic.Bool更稳妥
包装函数返回值与参数签名怎么保持一致
如果旧函数是 func OldGetUser(id int) (*User, error)，包装函数不能擅自改成返回 error 前置或加 context 参数——否则调用方编译不过。必须严格复刻签名，内部再做适配。
- 参数类型、顺序、数量必须完全一致；返回值类型和顺序也必须一致
- 若新版 API 多了
context.Context，可在包装函数内用context.Background()补上，但需注明“此调用不支持超时/取消” - 若新版返回结构体字段有变化（如
UserV2vsUser），包装函数里要做字段映射，而不是直接类型转换 - 别为了“看起来更现代”而把
error改成自定义错误类型——老代码依赖errors.Is(err, xxx)会失效
如何让 IDE 和静态检查工具识别弃用状态
Go 的 go vet 和主流 IDE（如 GoLand、VS Code + gopls）目前都不解析注释中的 “deprecated” 文字，但可以靠文档注释 + 工具链配合提升可见性。
- 在旧函数的 godoc 注释开头写
// Deprecated: use NewDoSomething instead.，gopls 会在补全时显示该行 - 配合
staticcheck自定义规则（需配置.staticcheck.conf），匹配函数名 + 注释关键词，报告调用位置 - 禁止在包装函数内部加
//go:noinline—— 这会让内联失效，影响性能，且无助于弃用提示 - CI 中可加脚本扫描所有调用旧函数的位置（如
grep -r "OldDoSomething(" ./... | grep -v "_test.go"），作为迁移进度参考
并发安全的包装函数要注意什么
如果旧函数本身不是并发安全的（比如操作全局 map 或未加锁的缓存），单纯套一层包装不会改变其行为。警告只是提醒，不能替代修复。
立即学习“go语言免费学习笔记（深入）”；
- 包装函数自身应是并发安全的（例如警告只打一次、日志写入线程安全），但不负责修复被包装函数的并发问题
- 若旧函数内部有竞态，且你已在新版中修复，包装函数里应明确加锁或用 sync.Pool 等隔离，而不是假设“用户会自己加锁”
- 避免在包装函数里启动 goroutine 去调用新版 —— 调用方没预期异步行为，容易导致 panic 或资源泄漏
- 测试时要用
-race跑旧函数的包装版，确认警告逻辑没引入新竞态（比如多个 goroutine 同时触发sync.Once是安全的，但手写 flag 判断不是）
