真正有效的废弃声明需明确迁移路径：注释中写清替代api及示例，编译时升级警告为错误，提供自动迁移工具，并在文档页顶部并置新旧api对比与注意事项。

直接在接口上加 @Deprecated 不够，关键是要让用户“愿意改、知道怎么改、改了不翻车”。真正有效的废弃声明，是把迁移路径写进注释里，让 IDE 能提示、文档能对齐、编译时有明确指引。

注释里必须包含替代方案

仅写 @Deprecated 或 “已过时” 是无效的。要明确指出“该用谁”，并给出最简等效调用示例：

• ✅ 正确写法：@Deprecated("Use newMethod(String, int) instead. Example: newMethod(name, 10);")
• ❌ 无效写法：@Deprecated("This method is deprecated.")
• 若替代 API 尚未稳定，可注明适用版本，如：@Deprecated("Replaced by UserService.createAsync() since v2.4.0")

配合编译警告升级为错误（可选但推荐）

在插件或内部 SDK 构建流程中，启用 -Werror=deprecation（Java）或等效配置，让废弃调用直接编译失败。这不是制造障碍，而是把问题暴露在开发阶段——比上线后报错成本低得多。

• 团队可统一配置 Gradle：allprojects { tasks.withType(JavaCompile) { options.compilerArgs += ['-Werror=deprecation'] } }
• CI 流程中加入检查，阻止含废弃调用的 PR 合并

提供自动迁移脚本或 IDE 插件支持

用户反感迁移，往往因为“改一处，漏十处”。提供可运行的辅助工具，能极大提升采纳率：

• 发布配套的 codemod 脚本（如 jscodeshift / AST-based），一键替换项目中所有 oldMethod() 为 newMethod()
• 为 IntelliJ / VS Code 开发轻量插件，在光标悬停时显示“点击快速替换为 newMethod()”，并自动导入新类
• shadcn-vue 和 ofetch 的 CLI 迁移命令就是成熟范例：执行 npx shadcn-vue migrate 或 ofetch@2-upgrade 即可完成批量适配

文档与旧版 API 并置呈现

不要把“已弃用”页面藏在文档角落。在旧 API 的文档页顶部加醒目 banner，同时列出：

• 弃用原因（如“性能瓶颈”“安全限制”“架构解耦需要”）
• 新版 API 文档链接（跳转直达）
• 迁移前后对比代码块（含参数映射、返回值变化、异常处理差异）
• 常见误用场景提醒（例如：“注意：newMethod() 不再自动重试，请自行封装”）

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！