Java 26 迁移时怎样整理弃用 API 清单

Java 26 迁移时，最容易漏掉的不是某个新语法，而是“代码还能编译”与“代码已经没有迁移风险”之间的差距。建议把清单分成三类：已经移除的 API、标记为 forRemoval=true 的 API，以及 sun.* 等 JDK 内部 API；再用 jdeprscan、jdeps 和 javac --release 26 把每一项绑定到构建产物和回归记录。

官方资料：https://docs.oracle.com/en/java/javase/26/migrate/removed-apis.html

不要把“弃用”统一当成低优先级警告。Java 26 已移除 Applet API，标记为待移除的调用则应在本次迁移中单独排期。

先把迁移对象分成三类

第一类是已经不能继续依赖的 API。例如 Java 26 移除了整个 java.applet 包、javax.swing.JApplet，还移除了 Thread.stop() 等条目。它们要直接进入“阻断构建或阻断发布”的清单，不能只靠压制编译警告。

第二类是仍可调用、但带有 forRemoval=true 的 API。它们说明平台已经给出后续移除信号，应该记录替代 API、影响模块和计划版本。第三类是内部 API，例如 sun.*，即使当前运行时还能访问，也不应作为长期兼容方案。

用 jdeprscan 找到真正用到的弃用 API

只看 Javadoc 的弃用列表，无法知道项目是否真的调用了某个类或方法。先把应用或库构建成 JAR，再扫描字节码；下面的命令同时保留普通弃用项和明确标记为待移除的项目。

# 扫描 JAR 中引用的弃用 API，先看完整清单
jdeprscan --release 26 build/libs/app.jar

# 只筛出后续可能被移除的 API，便于建立高优先级任务
jdeprscan --release 26 -l --for-removal build/libs/app.jar

# 把输出保存到迁移记录，避免每次只凭终端滚动内容判断
jdeprscan --release 26 build/libs/app.jar > build/jdk26-deprecation.txt

清单至少记录“类或方法、所在模块、调用方、是否 for removal、替代方案、负责人、关闭构建”。这样既能处理直接调用，也能把第三方库暴露出来的问题分配给依赖升级任务。

用 jdeps 补查内部 API 依赖

jdeprscan 关注弃用状态，不能替代模块依赖分析。JDK 迁移指南建议使用 jdeps 查找内部 API；对编译产物执行 -jdkinternals，可以把 sun.* 等实现细节暴露出来。

# 查找对 JDK 内部 API 的静态依赖
jdeps -jdkinternals build/libs/app.jar

# 同时查看模块和包级依赖，帮助定位升级边界
jdeps --multi-release 26 --print-module-deps build/libs/app.jar

扫描结果不等于完整运行时依赖：反射调用可能不会出现在静态结果里。因此对每个内部 API 条目，清单还要有一条测试或启动验证记录；临时的 --add-exports、--add-opens 只能作为过渡标记，不能作为永久关闭理由。

把清单接到构建门禁

迁移构建建议显式使用 --release 26，让编译器按目标 Java SE 版本检查 API 边界；不要把 --release 与 -source、-target 混用。构建系统可以把扫描结果作为制品附件，测试再负责确认行为没有改变。

# 用 JDK 26 编译，并固定目标 Java SE API 边界
javac --release 26 -d build/classes $(find src -name '*.java')

# 迁移门禁：扫描构建产物并让待移除项进入人工处理
jdeprscan --release 26 -l --for-removal build/libs/app.jar

# 迁移门禁：检查是否仍依赖 JDK 内部 API
jdeps -jdkinternals build/libs/app.jar

建议用以下字段管理每一行：risk、symbol、module、replacement、owner、target-release、verification。已移除项的 risk 设为阻断，forRemoval 设为高优先级，普通弃用项按调用频率和替代难度排期。

迁移前后的速查表

最后不要只把报告上传到构建系统就结束。真正可维护的清单要能回答三个问题：是谁调用了它、为什么还没替换、下一次构建怎样自动发现回归。

常见问题

只有编译失败才需要处理吗？不是。已移除 API 会直接暴露问题，但 forRemoval=true 和内部 API 可能暂时还能通过编译，仍应在迁移窗口中处理。

jdeprscan 能替代测试吗？不能。它扫描字节码引用，不能证明反射路径、配置路径和运行行为没有变化；它适合做清单输入，测试负责验证行为。