简介《Java Language Specification, Java SE 17 Edition》是Oracle官方发布的JDK 17语言规范原文文档面向需要准确理解JDK 17新特性与Java语言底层规则的开发者、架构师和教学人员可直接用作权威参考资料。压缩包内共有1个PDF文件约4.87MB文档按13章完整编排涵盖词法结构、类型/值/变量、转换与上下文、运算符、控制流程、方法、类与接口、异常、执行系统、数据类型、线程与锁同时包含JSR-392规范、预览特性说明及附录许可信息。目录设计清晰可快速定位文本块、记录类型、模式匹配、类型擦除等JDK 17重点内容正文则适合系统学习Unicode转义、泛型擦除、原始类型、交集类型、类加载器、垃圾回收、同步锁等语言细节既能通读建立完整认知又能在接口设计、类型转换、并发编程等场景中随时查证。具体来说文档对变量赋值、引用类型、参数化类型、类型擦除、可具体化类型、原始类型与交集类型均有精确定义对运算符优先级、控制流跳转、方法重载与重写、类的继承和接口实现等基础规则也有细致描述。当前已有440人学习/下载适合作为Java开发者案头常备的规范文档无论是初学者梳理语法脉络还是资深开发者查漏补缺都有实际价值。1. JDK 17新特性的原文文档先搞清楚官方到底改了什么再动手我见过太多人升级 JDK 17是先从某篇二手博客抄几个新特性关键词然后直接改 pom 文件里的版本号编译一过就觉得完事了。等代码上线要么是 switch 表达式行为跟旧习惯对不上要么是 GC 参数被静默忽略最后查了半天才发现问题出在对官方原文文档的误读上。JDK 17 是 2021 年 9 月发布的长期支持版本距离现在已足够久生态已经非常成熟但它也是最后一次携带一批“预览特性”的 LTS 版本。这篇笔记就把 JDK 17 新特性的原文文档当成第一手材料拆开讲从 Release Notes 到 JEP 文档再到怎么把每条新特性落成本地可跑的验证代码。适合正在做版本升级评估、或者想搞清 record 类和密封类到底怎么用的后端开发者如果你已经在生产环境跑 JDK 17 但总觉得哪里别扭这篇也能帮你回头对齐官方语义。2. JDK 17 新特性原文文档的全貌从 Release Notes 到 JEP2.1 官方文档体系里新特性信息分散在三个地方JDK 17 的新特性原文文档并不是一份文件而是分散在三个官方渠道里JDK 17 Release Notes、JDK 17 的 API 文档Javadoc以及 JEPJDK Enhancement Proposal索引。三者职责不同Release Notes 是变更清单告诉你“改了什么”Javadoc 是语义定义告诉你“每个方法现在怎么行为”JEP 是设计文档告诉你“为什么这么改、权衡了哪些方案”。如果只读 JEP 而忽略 Release Notes你会漏掉大量非功能性变更。比如 JDK 17 里 macOS 上默认启用了统一日志下的 GC 日志输出位置调整这类变化不会出现在 JEP 列表里却可能影响你的监控脚本。如果只读 Release Notes 而不读 JEP你又很难理解 record 类型内部为什么隐式生成了那些方法——因为 JEP 395 里详细写了类声明的语义约束。三个文档的阅读顺序我建议是先扫 Release Notes 的“New Features”清单找出跟你业务相关的条目再逐个打开对应 JEP 文档看设计动机和示例最后针对你要用的类和方法查 Javadoc确认精确的行为语义。这个顺序能让你在“知道有什么”和“理解为什么”之间建立连接而不是读完就忘。2.2 JDK 17 里那些被广泛引用的正式特性清单JDK 17 一共包含 14 个 JEP其中几个是开发者日常最常用的JEP 395 是 recordJEP 397 是密封类JEP 406 是 switch 模式匹配的预览JEP 409 是密封类在 java.lang 里的整合。另外还有 JEP 411 废弃了 SecurityManagerJEP 356 改进了随机数生成器接口。如果你在评估“要不要升级”先把这份清单拉出来对照自己的代码库做扫描比盲搜关键词高效得多。这里有一份 JDK 17 正式特性清单我按自己的理解做了归类不是官方原文的照搬重点是帮你看清哪些跟日常编码强相关JEP 编号特性名称开发影响306恢复 Always-Strict 浮点语义数学计算行为对齐影响极小356增强伪随机数生成器接口新增 RandomGenerator 接口382新的 macOS 渲染管线和 AArch64 支持桌面应用构建相关391macOS/AArch64 移植跨平台构建相关398弃用 Applet API基本无影响403移除 AOT/JIT 编译器实验特性极少数使用 GraalVM 早期实验的用户有影响406switch 模式匹配预览新语法可体验但要注意预览状态407移除 RMI 激活机制遗留系统要排查409密封类正式发布架构设计新选择410移除实验性的 AOT 编译器同 403411弃用 SecurityManager安全检查代码要注意412外部函数与内存 API 孵化实验性 API注意 JEP 406 是预览特性这个事实你写的 switch 模式匹配代码在 JDK 17 里编译必须要--enable-preview开关而且运行也一样要加。这个“预览”状态意味着后续版本的行为可能变化例如 JDK 21 里 switch 模式匹配已经正式转正写法上有细微调整你不能指望 JDK 17 的预览代码原封不动升上去。2.3 预览特性与正式特性的边界原文文档里如何区分原文文档里有个很容易被忽视的细节预览特性的 JEP 文档正文顶部会有明显的“Preview”标识Release Notes 里也会在特性名后标注(Preview)字样。Javadoc 中对应的新 API 会被标记为preview注解如果你用标准 JDK 编译预览代码javac 会打印一行警告告诉你这是预览特性。区分这两者不是形式主义。我给 A 同学排查过一个问题他把 JDK 17 的 record 类用得很顺手以为 switch 模式匹配也是正式特性结果代码里写了一大片模式匹配标签编译时全绿但运行时某些分支行为跟预期不符。实际上 record 在 JDK 16 转正、JDK 17 已经是正式特性而 switch 模式匹配在 JDK 17 还是预览两者对编译的要求、对后续升级的兼容性承诺完全不同。所以读原文文档时的判断标准是先看 JEP 状态字段Targeted或Integrated且没有Preview字样的才是当版本正式特性Preview或Incubator的状态意味着实现会被后续版本调整。你在团队里推广某个新特性时也要先对着这个状态说话免得把预览特性的行为当成稳定的 API 写进规范。3. 把 JDK 17 新特性原文文档转成可验证的本地示例代码3.1 最小环境准备下载、解压、确认版本号动手验证之前先把环境装干净。常见做法是下载一个 OpenJDK 17 的压缩包解压到本地目录而不是只用系统自带的包管理器安装这样你能精确控制版本。解压后先确认版本号这一步能避免后面所有“为什么我的环境不支持”的疑问。# 解压 JDK 17 到 /opt/jdk-17 mkdir -p /opt/jdk tar -xzf jdk-17.0.9_linux-x64_bin.tar.gz -C /opt/jdk/ # 设置环境变量并验证版本 export JAVA_HOME/opt/jdk/jdk-17.0.9 export PATH$JAVA_HOME/bin:$PATH java -versionjava -version会输出类似openjdk version 17.0.9 ...的字样。这里注意一个细节不同发行方比如某些 Linux 发行版自带的 OpenJDK或商业发行版输出的字符串格式有差异但版本号第一段必须是 17。如果输出的是 1.8 或者 11说明 PATH 里还有别的 JDK 在拦截这时候用which java查一下实际路径再检查/etc/profile.d/里有没有残留的 JAVA_HOME 配置。3.2 第一个验证实验record 类的编译与反编译验证record 是 JDK 17 里最值得先验证的特性因为它最容易感受到“写起来少、生成得多”的差异。先建一个最简 record 类编译之后用javap反编译看结构这是理解 record 本质的直观方式比读十遍文档都管用。// RecordDemo.java public class RecordDemo { // 声明一个 record表示一个坐标点 public record Point(int x, int y) {} public static void main(String[] args) { Point p new Point(3, 4); // 自动生成了 x()、y() 方法不是 getX()别记错 System.out.println(x p.x() , y p.y()); // 自动生成 toString System.out.println(p); // 自动生成 equals 和 hashCode System.out.println(p.equals(new Point(3, 4))); } }编译运行之后再执行javap -p RecordDemo\$Point.class你会看到编译器自动生成了x()、y()、equals、hashCode、toString还有那个带参数的构造方法。注意 record 的访问器方法名是x()而不是getX()这是团队代码规范里最容易起争执的地方很多从 C# 或 Kotlin 转过来的开发者会顺手写getX()然后发现编译报错。3.3 第二个验证实验密封类的层级限制如何体现在编译期密封类sealed class解决的是“继承关系可控”的问题。JDK 17 里用sealed关键字修饰父类用permits列出允许的子类。这个验证实验的重点是看编译器如何阻止不在列表里的类继承——这才是密封类真正的价值。// SealedDemo.java public class SealedDemo { // 声明密封接口只允许两个实现 public sealed interface Shape permits Circle, Square {} public record Circle(double radius) implements Shape {} public record Square(double side) implements Shape {} public static void main(String[] args) { Shape s new Circle(1.5); // 用模式匹配处理不同子类型 if (s instanceof Circle c) { System.out.println(circle area Math.PI * c.radius() * c.radius()); } } }试着在这个文件里增加一个class Triangle implements Shape {}编译立刻报错。这个报错信息会明确告诉你Triangle不在Shape的 permits 列表里。这种错误发生在编译期而不是运行期是设计上最大的进步——你的架构约束在代码提交阶段就被强制校验而不是等到上线后靠 code review 或者运行时报错来发现问题。3.4 第三个验证实验switch 模式匹配的预览开关与运行时限制JDK 17 的 switch 模式匹配是预览特性所以验证实验跟前两个不同——你必须在编译和运行两个阶段都显式声明预览开关否则即使代码写对了也会被拒绝。这个实验能同时验证两件事功能本身和“预览”状态带来的附加约束。// SwitchPatternDemo.java public class SwitchPatternDemo { // 定义简单的层级结构 sealed interface Expr permits Num, Add {} record Num(int value) implements Expr {} record Add(Expr left, Expr right) implements Expr {} static int eval(Expr e) { // 模式匹配 switch注意不需要 break return switch (e) { case Num(int n) - n; case Add(Expr l, Expr r) - eval(l) eval(r); }; } public static void main(String[] args) { // 构造 1 (2 3) Expr e new Add(new Num(1), new Add(new Num(2), new Num(3))); System.out.println(eval(e)); } }编译命令必须带两个参数--enable-preview告诉 javac 允许使用预览语法--release 17明确目标版本。运行时的java命令也要加--enable-preview。如果你只在编译时加而运行时不加会收到UnsupportedClassVersionError报错信息里的preview features are not enabled就是指向这个开关。# 编译和运行都必须带 --enable-preview javac --release 17 --enable-preview SwitchPatternDemo.java java --enable-preview SwitchPatternDemo这里有一个实际工作中常见的误解有人以为--release 17已经隐含了预览支持其实没有。--release 17只管你声明“目标平台是 17”--enable-preview才是打开语言特性预览的钥匙两者缺一不可且必须同时出现。3.5 验证结果如何与原文文档对照反编译、API 签名与行为实验跑完三个实验只是第一步真正的“验证”是把结果跟原文文档对齐。这里我有一套自己的对照流程先javap -p看编译器生成的成员清单跟 JEP 文档的描述比对再用javadoc生成你本地那个类的 API 文档看方法签名与官方 Javadoc 的差异最后修改入参观察行为变化比如 record 的 equals 在字段相同时返回 true、字段不同时返回 false这看起来理所当然但你要亲自确认它不比对象引用的地址才敢在业务代码里放心用它做值比较。// 验证 equals 是值比较而非引用比较 Point p1 new Point(1, 2); Point p2 new Point(1, 2); System.out.println(p1 p2); // false引用比较 System.out.println(p1.equals(p2)); // true值比较注意区分和equals在这个场景下的不同结果。如果你的代码里到处用比较 record 对象就会出现“看起来相同的两个坐标被判为不同”的诡异 bug。这类问题在团队里很常见因为习惯了基本类型的比较换到引用类型上还忘记改用equals。4. 读 JDK 17 新特性文档的 5 个避坑方法从翻车现场到排查清单4.1 坑一只见 JEP 列表没看 Release Notes遗漏行为调整现象某公司把自己的项目从 JDK 11 升到 17任务管理功能一切正常但监控脚本突然拿不到 GC 日志。排查半天发现日志输出路径变了。原因JDK 17 的 Release Notes 里记录了 GC 日志输出的默认路径调整但这条信息不在任何 JEP 里。只读 JEP 索引的团队完全看不到这条变更导致运维层面被动。解决每次升级先完整读一遍对应版本的 Release Notes只看标注了Changed、Deprecated、Removed的条目逐条核对有没有影响自己的部署脚本、监控项、启动参数。这一步花 30 分钟能省下后面几天的故障排查时间。4.2 坑二把预览特性当正式特性写进生产代码现象A 同学在 JDK 17 里用预览版 switch 模式匹配重写了旧的 if-else 判断链编译运行都正常。半年后项目升级到 JDK 21发现这段代码编译报错。原因JDK 17 的预览特性没有向后兼容承诺。JDK 21 里 switch 模式匹配虽然转正了但语法细节有调整比如 null 分支的处理方式、守卫条件when关键字的引入旧写法不能直接编译。解决明确区分预览状态和正式状态。你对团队宣讲时把 JEP 406 这类预览特性定位为“技术预研”可以验证学习但不要进主干生产逻辑。生产代码只用 record、密封类这类已转正的特性。如果实在要用就把版本升级的时间成本提前算进去并且准备好重写这些代码的心理预期。排查时怎么快速确认用javac --release 17编译时观察警告信息里有没有preview字样或者直接打开 JEP 文档看状态字段一目了然。4.3 坑三record 类的访问器命名与 equals 语义混淆现象新写的 record 类在业务代码里调getX()报错同事坚持说“IDEA 里明明提示有这个方法”但 javac 编译不通过。原因IDEA 等 IDE 对 record 的代码提示有时会显示成 Lombok 风格的getX()形式这其实是 IDE 的显示转换真正的方法是x()。另一位同事则是在比较两个 record 对象时用了导致“内容明明相同却判断不等”的深坑。解决统一在项目规范里写明两条规则record 的访问器是无get前缀的字段名方法record 对象的相等性判断一律用equals禁止用。可以在 CI 里加一个简单的源文件扫描脚本搜出代码里的record关键字后检查是否存在get前缀调用把这个底线守住。4.4 坑四密封类的 permits 子类没有放在同一文件或同一包编译失败现象某开发者设计了精密的密封类继承层级把子类分散在多个文件里编译时 javac 直接报错错误信息是“类不在同一包中”或者“permits 子类必须是直接子类”。原因密封类对 permits 列出的子类有两个约束必须在同一模块或同一包中而且必须是直接继承。把子类放到其他包里虽然逻辑上合理但违反了语言规范。解决设计密封类层级时先把包结构画出来确保所有 permitted 子类都跟密封类在同一包内。如果你需要更大的自由度考虑改用模块化设计——模块内的包之间可以跨包继承但模块声明里要加上exports和opens的配合这个复杂度通常不值得为归档层级牺牲掉。4.5 坑五构建工具版本太旧不识别--release 17现象Maven 项目在 pom 里配置了maven.compiler.release17但构建时提示invalid target release: 17。开发机本地 javac 直接编译没问题一上 CI 就挂。原因Maven 编译器插件版本太旧或者 JDK 17 的 toolchain 配置没有指向新的 JDK。旧版 maven-compiler-plugin 不认release参数有的旧 script 里还写死了source和target而不是release导致新 JDK 的交叉编译行为失效。解决maven-compiler-plugin 升级到支持 Java 17 的版本pom 里同时设置source、target、release三个属性并显式指定 toolchain。然后验证编译日志里是否出现--release 17参数。更简单的检查方法是直接在项目根目录执行mvn compile然后用javap -v看生成的 class 文件主版本号是否 61这个方法用一次就能确认编译目标真是指向了 17。5. 用原文特性做升级回归一套能被团队复制的最小检查流程5.1 在现有项目里小范围启用 record从 “写着玩” 到 “能上线”你先挑一个无状态的数据载体试水比如把原来用类加构造器加 getter 写的 DTO 改成 record。注意你的项目如果依赖了 Jackson 做 JSON 序列化需要确认 Jackson 版本对 record 的支持如果依赖 MyBatis 这类反射框架则需要确认框架版本对 record 的支持。这里有个来自一线实践的血泪经验不是 record 本身不能用而是它周围的序列化、持久化框架可能还没跟上。// 原写法大量样板代码 public class UserDTO { private String name; private int age; public UserDTO(String name, int age) { this.name name; this.age age; } public String getName() { return name; } public int getAge() { return age; } } // record 写法一行声明自动生成构造器、访问器、equals、hashCode、toString public record UserDTO(String name, int age) {}换完之后跑整个测试套件重点看 JSON 序列化输出的字段名是否变化、反序列化是否正常、有没有反射框架触碰到get前缀方法的地方。这套验证做完你基本就能判断项目里的基础设施对 record 的兼容程度。5.2 用密封类重构策略模式原来要写 20 行接口约束现在交给编译器如果你的代码里有一个接口实现类只在固定的几个类型之间切换这非常适合改造成密封类。比如支付渠道接口微信、支付宝、银行卡三种实现是业务固定的。用sealed修饰这个接口明确列出允许的实现类之后任何人想新增一种实现会相对谨慎因为要在编译期过 permits 列表这一关。// 支付渠道的密封接口 public sealed interface PaymentChannel permits WeChatPay, AliPay, CardPay {} public final class WeChatPay implements PaymentChannel { public void pay(String orderId, double amount) { /* 微信支付逻辑 */ } } public final class AliPay implements PaymentChannel { public void pay(String orderId, double amount) { /* 支付宝支付逻辑 */ } } public final class CardPay implements PaymentChannel { public void pay(String orderId, double amount) { /* 银行卡支付逻辑 */ } }留意这里子类必须声明为final或者继续sealed/non-sealed否则编译报错。这种约束本质上是在编译期就把“架构边界”固化下来后续审查代码时能少很多口舌也给新人熟悉业务约束提供了一个清晰的起点。5.3 升级到新版本的回归检查点列一份可执行的对照表最后给你一份我每次升级 JDK 版本都会对照检查的清单这里的“检查”不是读文档而是真的跑一遍代码路径检查项操作方式通过标准编译 启动用新 JDK 干净编译确认无警告无编译错误无预览特性警告运行时行为跑原有测试套件全量测试通过无新增瓶颈序列化/反序列化验证 JSON/XML 组件对 record 类的兼容字段名不变数据不丢失反射调用扫描代码中getMethod、getDeclaredField调用访问器方法名相关的反射逻辑有适配安全策略检查 SecurityManager 相关代码找到弃用警告对应位置并替换javap -verbose查看 class 主版本号是一个快速抓手JDK 17 编译出来的 class 文件主版本号是 61JDK 11 是 55JDK 8 是 52。在 CI 脚本的构建末尾加一段打印主版本号的命令你就能确认输出物到底是用哪个 JDK 构建的这个习惯能拦下不少环境漂移的问题。老实说JDK 17 的原文文档里最容易被忽略的不是那几十个新 API而是那些“看起来不重要”的行为调整——GC 日志路径、默认随机数生成器、弃用窗口期。它们不会出现在新闻里但会导致你把半天时间花在查一个根本不是自己代码引入的问题上。这也是我为什么强调要读原文而不是二手的特性列表原文里藏着你以为自己知道、但其实不知道的边界。先从最小验证开始做起把上面这份检查表在你当前项目里跑一遍你对 JDK 17 的信心会扎实很多。希望帮到你。本文还有配套的精品资源点击获取