Go中唯一触发编译警告的是//go:deprecated指令，需紧贴导出标识符声明且无空行；Deprecated:注释仅被godoc、gopls等工具识别，需三者并存以保障兼容性。
Go 中没有官方 // Deprecated 注释语法
Go 语言本身不解析任何形如 // Deprecated 的注释，这类注释不会触发编译警告、IDE 提示或文档生成工具的特殊处理。你写 // Deprecated: use NewClient instead，go build 完全无视它，gopls 也大概率不标灰——除非你额外配置了静态检查工具。
真正起作用的是 Go 文档注释（即 godoc 风格）中约定俗成的 Deprecated: 前缀，配合外部工具链识别：
-
go doc和pkg.go.dev会把以Deprecated:开头的首行注释渲染为「已弃用」区块（但不加视觉降级） -
gopls（VS Code Go 插件底层语言服务器）从 v0.13+ 起支持识别该前缀，并在编辑器中显示删除线 + 悬停提示 - 静态检查工具如
staticcheck可通过-checks U1000等规则捕获被标记但未加go:deprecated指令的函数（见下节）
//go:deprecated 是唯一能触发编译期警告的机制
从 Go 1.17 开始，//go:deprecated 是唯一能让 go build 或 go test 主动报警告的方案。它不是注释，而是编译指令（pragmatic directive），必须紧贴函数/类型声明上方，且不能有空行隔开。
常见错误写法：
立即学习“go语言免费学习笔记（深入）”；
// 这样写无效：有空行、位置错、拼写错
func OldHelper() {}
// Deprecated: use NewHelper instead
//go:deprected // ← 拼错了，且空行隔开
func OldHelper() {}
正确写法（无空行、精确拼写、紧跟声明）：
//go:deprecated "use NewHelper instead"
func OldHelper() {}
- 字符串参数必填，建议明确替代方案，比如
"use NewHelper(ctx) instead" - 仅对导出标识符（首字母大写）生效；私有函数加了也不会报警告
- 警告只在调用处触发，不是定义处；调用
OldHelper()时才会看到OldHelper is deprecated: use NewHelper instead - 不支持条件废弃（比如“仅在 Go < 1.20 时废弃”），它是硬开关
IDE 和文档里想让废弃态「看得见」，得靠组合动作
仅靠 //go:deprecated 不足以覆盖所有场景：老项目没升级 Go 1.17+、CI 不跑 go build、或者用户只看 pkg.go.dev 页面——这时候就得靠文档注释 + 工具协同。
推荐写法（三者并存，兼容性最强）：
// Deprecated: use NewHelper instead.
// This function will be removed in v2.0.
//
//go:deprecated "use NewHelper instead"
func OldHelper() {}
- 首行
Deprecated:触发pkg.go.dev的「Deprecated」标签栏和gopls悬停摘要 - 补充说明行（如版本计划）帮助使用者判断迁移 urgency
-
//go:deprecated确保新 Go 版本能产生构建警告 - 注意：两段之间不能有空行，否则
gopls可能只读取第一行，忽略指令
别漏掉测试和重构后的清理点
标记废弃只是第一步，容易被忽略的是后续动作：
- 所有调用
OldHelper()的地方，应尽快替换成新接口；否则警告会持续刷屏，团队可能习惯性忽略 - 单元测试里如果还用旧函数，
go test同样会报警告——建议在测试中加//lint:ignore U1000（若用 staticcheck）或直接重写测试 - 发布新 major 版本前，应彻底删除已标记废弃的符号；Go 没有「运行时废弃」概念，删了就是真没了
- 如果函数逻辑无法直接替换（比如签名差异大），考虑保留旧函数做兼容桥接，内部转发并加日志告警，比纯标记更主动
废弃不是加个注释就完事，它是个需要定义生命周期、同步上下游、最后干净收口的动作。最常卡住的地方，其实是没人去 grep 全局调用点，或者忘了更新文档示例代码。
