本教程详细介绍了如何使用 `jlink` 工具为基于 Java 19 和 Spring Boot 3.0 的非模块化应用程序创建最小化的自定义 Java 运行时镜像。通过分析 `jdeps` 的输出，识别并解决 `NoClassDefFoundError` 导致的模块缺失问题，最终生成一个精简且功能完整的运行时环境，以优化应用部署和运行效率。
引言：定制化 Java 运行时镜像的优势
随着 Java 模块化系统（Jigsaw 项目）的引入，jlink 工具允许开发者创建只包含应用程序所需模块的自定义 Java 运行时镜像。这不仅能显著减小部署包的体积，还能提升启动速度，并提供一个更加隔离和安全的运行环境。对于 Spring Boot 这样的流行框架，虽然其应用通常以“胖 JAR”形式发布，但结合 jlink 仍能获得这些优势。本教程将以一个简单的 Spring Boot 3.0 应用为例，演示如何构建一个包含所有必要模块的自定义运行时。
准备 Spring Boot 应用程序
首先，我们创建一个基础的 Spring Boot 应用程序。这里使用 start.spring.io 生成一个 Maven 项目，配置为 Java 19 和 Spring Boot 3.0。为了演示目的，我们额外添加 commons-lang3 依赖并在主类中使用它。
pom.xml 配置：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.0.0</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>19</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>主应用程序类 DemoApplication.java：
package com.example.demo;
import org.apache.commons.lang3.StringUtils;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
String mix = "MIX";
if (StringUtils.isNoneBlank(mix)) {
System.out.println(mix);
}
SpringApplication.run(DemoApplication.class, args);
}
}使用 Maven 构建项目：mvn clean package。 构建成功后，将在 target 目录下生成 demo-0.0.1-SNAPSHOT.jar。 可以通过以下命令验证应用程序是否正常运行：
java -jar target/demo-0.0.1-SNAPSHOT.jar
此时，应用程序应正常启动并显示 Spring Boot 标志及日志信息。
使用 jdeps 分析应用程序依赖
jdeps 是 Java Development Kit (JDK) 提供的一个命令行工具，用于分析 Java 类文件的静态依赖关系。它可以帮助我们识别应用程序及其依赖库所使用的 JDK 模块。
执行 jdeps 命令分析生成的 JAR 文件：
jdeps target/demo-0.0.1-SNAPSHOT.jar
部分输出示例：
demo-0.0.1-SNAPSHOT.jar -> java.base demo-0.0.1-SNAPSHOT.jar -> java.logging demo-0.0.1-SNAPSHOT.jar -> not found com.example.demo -> java.io java.base com.example.demo -> java.lang java.base com.example.demo -> org.apache.commons.lang3 not found com.example.demo -> org.springframework.boot not found # ... 其他依赖 ...
从 jdeps 的输出中，我们可以看到 demo-0.0.1-SNAPSHOT.jar 直接依赖于 java.base 和 java.logging 模块。然而，对于 org.apache.commons.lang3、org.springframework.boot 等第三方库，jdeps 显示为 not found。这是因为 Spring Boot 应用程序通常被打包成一个“胖 JAR”（Fat Jar），其中包含了所有应用程序和其依赖的类。jdeps 在分析这种胖 JAR 时，无法直接识别内部第三方库所依赖的 JDK 模块，也无法识别胖 JAR 内部的类（如 org.springframework.boot.loader）所依赖的模块。因此，jdeps 的输出只能作为初步参考，对于复杂应用，特别是 Spring Boot 这种非模块化应用的自定义运行时构建，往往需要通过迭代试错来确定所有必需的模块。
首次尝试 jlink 及遇到的问题
基于 jdeps 的初步分析，我们可能认为只需要 java.base 和 java.logging 模块。尝试使用 jlink 创建自定义运行时镜像：
jlink --module-path $JAVA_HOME/jmods --add-modules java.base,java.logging --output mycustomrt
这条命令会在当前目录下创建一个名为 mycustomrt 的自定义运行时镜像。 接下来，尝试使用这个自定义运行时来运行 Spring Boot 应用程序：
./mycustomrt/bin/java -jar target/demo-0.0.1-SNAPSHOT.jar
此时，应用程序启动失败，并抛出 java.lang.NoClassDefFoundError 错误：
java.lang.NoClassDefFoundError: java/beans/PropertyEditorSupport
at org.springframework.boot.context.properties.bind.BindConverter$TypeConverterConverter.<clinit>(BindConverter.java:180)
# ... 更多堆栈信息 ...
Caused by: java.lang.ClassNotFoundException: java.beans.PropertyEditorSupport
# ... 更多堆栈信息 ...这个错误表明自定义运行时缺少 java.beans.PropertyEditorSupport 类，而这个类是 Spring Boot 在属性绑定和类型转换过程中所依赖的。java.beans 包通常位于 java.desktop 模块中。这说明我们最初添加的模块不足以满足 Spring Boot 应用程序的所有运行时需求。
识别并添加缺失的模块
当遇到 NoClassDefFoundError 时，我们需要根据错误信息来判断缺少哪个 JDK 模块。通常，可以通过搜索缺失的类名（例如 java.beans.PropertyEditorSupport）来确定它属于哪个 Java 模块。在这个案例中，java.beans 包是 java.desktop 模块的一部分。
此外，Spring Boot 应用程序在内部还会依赖一些其他的标准 Java 模块，即使我们的应用代码没有直接使用它们。根据经验和常见的 Spring Boot 依赖，以下模块通常是必需的：
- java.base: Java 核心 API，所有 Java 应用的基础。
- java.logging: Java 日志 API，Spring Boot 内部日志系统会使用。
- java.xml: XML 处理 API，Spring Boot 在某些配置或解析场景下可能使用。
- java.sql: JDBC API，如果应用程序涉及到数据库连接，这是必需的。即使不直接使用，Spring Boot 的数据源配置也可能间接依赖。
- java.prefs: Java Preferences API，Spring Boot 可能用于某些配置管理。
- java.desktop: 包含 java.beans 包，Spring Boot 在属性绑定、类型转换和一些内部机制中会使用到。
综合这些模块，我们构建一个新的 jlink 命令。
生成完整的自定义运行时镜像
现在，我们将所有识别到的必要模块添加到 jlink 命令中：
jlink --module-path $JAVA_HOME/jmods \
--add-modules java.base,java.logging,java.xml,java.sql,java.prefs,java.desktop \
--output mycustomrt_full执行此命令后，将生成一个包含所有必需模块的 mycustomrt_full 目录。 接下来，使用这个新的自定义运行时镜像来运行 Spring Boot 应用程序：
./mycustomrt_full/bin/java -jar target/demo-0.0.1-SNAPSHOT.jar
此时，Spring Boot 应用程序应该能够成功启动并正常运行。
注意事项与最佳实践
- jdeps 的局限性： 对于 Spring Boot 这样的“胖 JAR”应用，jdeps 无法完全准确地识别所有运行时所需的 JDK 模块。因此，jdeps 结果只能作为起点，实际构建自定义运行时往往需要通过迭代试错来完善。
- 迭代试错： 当遇到 NoClassDefFoundError 或其他运行时错误时，应根据错误信息逐步添加缺失的模块。这是一个常见的调试过程。
- Spring Boot Maven Plugin 集成： 从 Spring Boot 3.x 开始，spring-boot-maven-plugin 提供了更好的 jlink 集成支持。可以通过配置插件来自动化自定义运行时镜像的构建过程，例如使用 build-image 目标或 jlink 目标（如果可用且配置得当），这比手动执行 jlink 命令更加便捷和可靠。
- 减小运行时体积： jlink 提供了 --compress 选项（例如 --compress=2）来进一步减小运行时镜像的体积。在生产环境中，这通常是一个推荐的优化步骤。
- 模块化应用与非模块化应用： 本教程主要针对非模块化的 Spring Boot 应用程序。如果您的 Spring Boot 应用程序本身已经进行了模块化改造（即包含 module-info.java 文件），那么 jlink 的过程会更加直接，因为 jdeps 和 jlink 可以更准确地识别模块依赖。
- 特定环境依赖： 如果应用程序依赖于特定于操作系统的功能（如 AWT/Swing GUI），可能需要额外的模块。
总结
通过本教程，我们学习了如何使用 jlink 工具为 Spring Boot 3.0 应用程序构建一个定制化的 Java 运行时镜像。尽管 jdeps 在分析胖 JAR 时存在局限性，但通过结合 jdeps 的初步分析和运行时错误（如 NoClassDefFoundError）的迭代调试，我们可以成功识别并包含所有必要的 JDK 模块。构建自定义运行时镜像有助于减小部署体积，提高应用启动效率，并为现代 Java 应用程序提供更优化的部署方案。
