从 21 迁移到 25

版本坐标：class 65 → 6901

JDK 21 的 class 文件版本是 65，JDK 25 是 69。先用目标 JDK 确认运行时与编译工具一致，再用 --release 25 编译；--release 同时约束语法、字节码版本和标准库 API 快照。

java -version
javac -version

openjdk version "25" 2025-09-16 LTS
OpenJDK Runtime Environment Corretto-25.0.0.36.2 (build 25+36-LTS)
OpenJDK 64-Bit Server VM Corretto-25.0.0.36.2 (build 25+36-LTS, mixed mode, sharing)

javac --release 21 -d out21 ModuleImportDemo.java
# error: module imports are not supported in -source 21

ModuleImportDemo.java:1: error: module imports are not supported in -source 21
import module java.base;
       ^
  (use -source 25 or higher to enable module imports)
1 error

--release 25 编译出的 class 在 21 上会抛 UnsupportedClassVersionError。反过来，21 编译的 class 通常能在 25 上运行，但预览 class 除外。

API：转正、改名与移除02

先按「21 的状态 → 25 的状态」列一张表，再处理不兼容改签名。最容易踩的是 ScopedValue 的便捷方法与结构化并发的整套 API。

import java.util.concurrent.*;

public class OldApi {
    void fetch() throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            scope.fork(() -> "a");
            scope.join().throwIfFailed();
        }
    }
}

OldApi.java:5: error: cannot find symbol
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
                                                ^
  symbol:   class ShutdownOnFailure
  location: interface StructuredTaskScope
Note: OldApi.java uses preview features of Java SE 25.
Note: Recompile with -Xlint:preview for details.
1 error

• new ShutdownOnFailure() → open() 或 open(Joiner.allSuccessfulOrThrow())。
• join().throwIfFailed() → join()；失败直接抛 FailedException。
• ShutdownOnSuccess.result() → open(Joiner.anySuccessfulResultOrThrow()).join()。
• joinUntil(Instant) → open(joiner, cfg -> cfg.withTimeout(Duration))。

运行时：转正不等于默认开启03

紧凑对象头（JEP 519）在 25 从实验特性转为产品特性，但 JEP 519 明确把「改变默认对象头布局」列为非目标。本机默认值仍是 false，必须显式开启。

java -XX:+PrintFlagsFinal -version | grep UseCompactObjectHeaders

bool UseCompactObjectHeaders = false {product lp64_product} {default}

加 -XX:+UseCompactObjectHeaders 后，同一命令会显示 true {command line}；不需要 -XX:+UnlockExperimentalVMOptions，因为 25 已将其转为产品特性。分代 Shenandoah（JEP 521）同样只是从实验转为产品，默认仍是单代 satb。

java -XX:+UseShenandoahGC -XX:ShenandoahGCMode=generational \
     -XX:+PrintFlagsFinal -version | grep ShenandoahGCMode

ccstr ShenandoahGCMode = generational {product} {command line}

AOT 方面，JEP 514 简化了创建 AOT 缓存的命令，JEP 515 把训练运行的方法 profile 放进缓存，改善启动与预热。三步仍是 record → create → run，收益主要在启动阶段，不是峰值吞吐。

java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -cp app.jar AotApp
java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -cp app.jar
java -XX:AOTCache=app.aot -cp app.jar AotApp

aot app running

• 32 位 x86 端口在 25 移除（JEP 503）：不再提供 32 位 x86 运行时；检查 native agent、JNI 库和容器镜像。
• System.setSecurityManager 与 Thread.stop 在 25 仍抛 UnsupportedOperationException。
• -XX:-UseCompressedClassPointers 在 25 已弃用并会警告；紧凑对象头依赖它，关闭后紧凑对象头也会被禁用。

预览：25 还有什么，为什么不能跨版本04

JDK 25 仍有多项预览/孵化特性。它们不是「beta 正式版」：API 可能改名、改签名甚至撤回，class 文件也会被标记为预览。

javac --release 25 --enable-preview -d out ScopedStructuredDemo.java
java --enable-preview -cp out ScopedStructuredDemo

预览 class 的 minor version 是 65535。只在编译时加 --enable-preview、却忘记运行时加，会得到下面的错误；把 21 的预览 class 放到 25 上同样不行。

Error: LinkageError occurred while loading main class ScopedStructuredDemo
	java.lang.UnsupportedClassVersionError: Preview features are not enabled for ScopedStructuredDemo (class file version 69.65535). Try running with '--enable-preview'

• 编译和运行两端都要 --enable-preview，且运行时 JDK 版本必须与编译时一致。
• 21 的预览 class 是 65.65535，25 只识别 69.65535；升级后必须重新编译。
• --enable-preview 本身不会把普通 class 标成 65535；只有实际使用预览特性才会。
• 预览代码应隔离在适配层后面，不要把预览类型暴露到公共 API。

升级检查清单05

1. 盘点所有运行时：本地、CI、容器、Kubernetes、构建插件，统一到 25。
2. 用 --release 25 编译，开启 -Xlint:removal；先让编译警告可见。
3. 重写结构化并发：open() + Joiner；确认仍用 --enable-preview。
4. 替换 ScopedValue 的 runWhere/callWhere/getWhere；检查 orElse(null)。
5. 模块导入去掉预览参数；处理 List / Date 等同名类歧义。
6. 紧凑源文件检查 package 与 IO 静态导入；需要 --release 时改用 javac。
7. A/B 评估紧凑对象头与分代 Shenandoah；确认不是 32 位 x86 并回归 native 依赖。
8. 隔离预览特性，跑完整测试、压测与回滚演练。

迁移完成的标准不是「能启动」，而是「启动参数干净、没有依赖预览 class、默认值与预期一致、测试与压测通过、回滚路径明确」。

版本边界BOUNDARY

这张表比 API 本身更值得记。写代码时先确认你的运行时版本。

费曼自检SELF CHECK

先合上页面，用自己的话回答，再展开对照。能讲出因果和反例，才算真正掌握。