必须三者并存：//go:deprecated 指令（go 1.17+，仅导出项有效，紧贴声明）、deprecated: 注释（供 godoc/gopls 解析）、运行时 sync.once 单次警告（避免热路径开销），缺一不可。
必须用 //go:deprecated 指令 + Deprecated: 文档注释 + 运行时首次警告三者并存，缺一不可。只写注释或只加指令，都会让部分工具链失效。
为什么 // Deprecated: 注释本身不触发警告
Go 编译器完全忽略任何形如 // Deprecated: 的注释——它不是语言特性，只是 godoc 和 gopls 约定的文本前缀。如果你只写这个，go build 静默通过，CI 不报警，IDE 里也不会标灰。
-
//go:deprecated是唯一能触发编译期警告的机制，从 Go 1.17 起生效，且仅对导出函数/类型有效 - 必须紧贴声明，中间不能有空行；拼写错误（比如
//go:deprected）或位置错（写在函数体里）都无效 - 字符串参数必须非空，例如：
//go:deprecated "use NewDoSomething(ctx) instead" - 警告只在调用处出现，不是定义处；老代码继续编译，但会看到
OldDoSomething is deprecated: use NewDoSomething(ctx) instead
运行时警告怎么做到“只提示一次”又不拖慢高频调用
包装函数里不能每次调用都打印日志，尤其当 OldGetUser 出现在热路径（如 HTTP handler 内循环）时。正确做法是用 sync.Once 控制输出时机，比 atomic.Bool 更轻量、更可靠。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 声明包级变量：
var warnedOldGetUser sync.Once - 在包装函数内调用：
warnedOldGetUser.Do(func() { fmt.Fprintf(os.Stderr, "WARNING: OldGetUser is deprecated, use NewGetUser(ctx) instead\n") }) - 不要用
log.Printf—— 它带锁且格式化开销大；fmt.Fprintf(os.Stderr, ...)更直接 - 绝对不要
panic或log.Fatal，这会破坏“平滑过渡”前提
包装函数签名怎么保持兼容又不埋坑
旧函数签名是契约，改一个参数顺序、多一个 context.Context、少一个返回值，调用方就编译失败。包装函数必须原样复刻，内部再适配。
- 如果新版是
func NewGetUser(ctx context.Context, id int) (*User, error)，旧版是func OldGetUser(id int) (*User, error)，包装函数就得写成：func OldGetUser(id int) (*User, error) { return NewGetUser(context.Background(), id) } - 禁止把
error替换成自定义错误类型（如*MyError），否则errors.Is(err, ErrNotFound)会失效 - 如果新版响应结构体字段不同（如
UserV2多了AvatarURL），包装函数里要显式映射字段，不能强制类型转换 - DTO 结构体必须按版本拆分，例如
UserResponseV1和UserResponseV2，禁止共用同一type User struct{}
最容易被忽略的是：弃用不等于冻结——你得监控 OldGetUser 的调用量衰减曲线，等它归零或趋近于零，才能真正删掉函数和包装逻辑。中间任何一步跳过，都可能让某个遗留客户端突然崩掉。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
