高级 Native Images 主题

嵌套配置属性

Spring ahead-of-time 引擎会自动为配置属性创建反射提示。但是，不是内部类的嵌套配置属性*必须*使用 @NestedConfigurationProperty 注解，否则它们将不会被检测到，也不会可绑定。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.NestedConfigurationProperty;

@ConfigurationProperties(prefix = "my.properties")
public class MyProperties {

	private String name;

	@NestedConfigurationProperty
	private final Nested nested = new Nested();

	// getters / setters...

	public String getName() {
		return this.name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public Nested getNested() {
		return this.nested;
	}

}

其中 Nested 是：

public class Nested {

	private int number;

	// getters / setters...

	public int getNumber() {
		return this.number;
	}

	public void setNumber(int number) {
		this.number = number;
	}

}

上面的示例为 my.properties.name 和 my.properties.nested.number 生成配置属性。如果没有在 nested 字段上使用 @NestedConfigurationProperty 注解，my.properties.nested.number 属性在 native image 中将不可绑定。您也可以注解 getter 方法。

使用构造函数绑定时，您必须使用 @NestedConfigurationProperty 注解字段：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.NestedConfigurationProperty;

@ConfigurationProperties(prefix = "my.properties")
public class MyPropertiesCtor {

	private final String name;

	@NestedConfigurationProperty
	private final Nested nested;

	public MyPropertiesCtor(String name, Nested nested) {
		this.name = name;
		this.nested = nested;
	}

	// getters / setters...

	public String getName() {
		return this.name;
	}

	public Nested getNested() {
		return this.nested;
	}

}

使用 records 时，您必须使用 @NestedConfigurationProperty 注解参数：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.NestedConfigurationProperty;

@ConfigurationProperties(prefix = "my.properties")
public record MyPropertiesRecord(String name, @NestedConfigurationProperty Nested nested) {

}

使用 Kotlin 时，您需要使用 @NestedConfigurationProperty 注解数据类的参数：

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.NestedConfigurationProperty

@ConfigurationProperties(prefix = "my.properties")
data class MyPropertiesKotlin(
	val name: String,
	@NestedConfigurationProperty val nested: Nested
)

在所有情况下都请使用公共的 getter 和 setter，否则属性将不可绑定。

转换 Spring Boot 可执行 Jar

只要 jar 包含 AOT 生成的资源，就可以将 Spring Boot 可执行 jar 转换为 native image。这在许多情况下都很有用，包括：

您可以保持常规的 JVM 管道，并在 CI/CD 平台上将 JVM 应用程序转换为 native image。
由于 native-image 不支持交叉编译，您可以保持一个操作系统无关的部署工件，稍后再转换为不同的操作系统架构。

您可以使用 Cloud Native Buildpacks 或使用 GraalVM 附带的 native-image 工具将 Spring Boot 可执行 jar 转换为 native image。

您的可执行 jar 必须包含 AOT 生成的资源，如生成的类和 JSON 提示文件。

使用 Buildpacks

Spring Boot 应用程序通常通过 Maven（mvn spring-boot:build-image）或 Gradle（gradle bootBuildImage）集成使用 Cloud Native Buildpacks。但是，您也可以使用 pack 将 AOT 处理的 Spring Boot 可执行 jar 转换为 native 容器镜像。

首先，确保 Docker 守护进程可用（有关更多详细信息，请参阅 Get Docker）。如果您在 Linux 上，请配置它以允许非 root 用户。

您还需要按照 buildpacks.io 上的安装指南安装 pack。

假设 AOT 处理的 Spring Boot 可执行 jar 构建为 myproject-0.0.1-SNAPSHOT.jar 在 target 目录中，运行：

$ pack build --builder paketobuildpacks/builder-jammy-java-tiny \
    --path target/myproject-0.0.1-SNAPSHOT.jar \
    --env 'BP_NATIVE_IMAGE=true' \
    my-application:0.0.1-SNAPSHOT

以这种方式生成镜像不需要本地 GraalVM 安装。

一旦 pack 完成，您可以使用 docker run 启动应用程序：

$ docker run --rm -p 8080:8080 docker.io/library/myproject:0.0.1-SNAPSHOT

使用 GraalVM native-image

将 AOT 处理的 Spring Boot 可执行 jar 转换为 native 可执行文件的另一种选择是使用 GraalVM native-image 工具。为此，您需要在机器上安装 GraalVM 发行版。您可以在 Liberica Native Image Kit 页面上手动下载，或者使用 SDKMAN! 等下载管理器。

假设 AOT 处理的 Spring Boot 可执行 jar 构建为 myproject-0.0.1-SNAPSHOT.jar 在 target 目录中，运行：

$ rm -rf target/native
$ mkdir -p target/native
$ cd target/native
$ jar -xvf ../myproject-0.0.1-SNAPSHOT.jar
$ native-image -H:Name=myproject @META-INF/native-image/argfile -cp .:BOOT-INF/classes:`find BOOT-INF/lib | tr '\n' ':'`
$ mv myproject ../

这些命令在 Linux 或 macOS 机器上工作，但您需要为 Windows 调整它们。

@META-INF/native-image/argfile 可能不会打包在您的 jar 中。只有在需要可达性元数据覆盖时才会包含它。

native-image -cp 标志不接受通配符。您需要确保列出所有 jar（上面的命令使用 find 和 tr 来执行此操作）。

使用跟踪代理

GraalVM native image 跟踪代理允许您拦截 JVM 上的反射、资源或代理使用，以生成相关的提示。 Spring 应该自动生成大多数这些提示，但跟踪代理可用于快速识别缺失的条目。

使用代理为 native image 生成提示时，有几种方法：

直接启动应用程序并测试它。
运行应用程序测试来测试应用程序。

第一个选项对于识别当库或模式不被 Spring 识别时缺失的提示很有用。

第二个选项对于可重复的设置听起来更有吸引力，但默认情况下生成的提示将包括测试基础设施所需的任何内容。其中一些在实际运行应用程序时是不必要的。为了解决这个问题，代理支持一个访问过滤器文件，这将导致某些数据从生成的输出中排除。

直接启动应用程序

使用以下命令启动附加了 native image 跟踪代理的应用程序：

$ java -Dspring.aot.enabled=true \
    -agentlib:native-image-agent=config-output-dir=/path/to/config-dir/ \
    -jar target/myproject-0.0.1-SNAPSHOT.jar

现在您可以测试想要为其生成提示的代码路径，然后使用 ctrl-c 停止应用程序。

在应用程序关闭时，native image 跟踪代理将把提示文件写入给定的配置输出目录。您可以手动检查这些文件，或将它们用作 native image 构建过程的输入。要将它们用作输入，请将它们复制到 src/main/resources/META-INF/native-image/ 目录。下次构建 native image 时，GraalVM 将考虑这些文件。

native image 跟踪代理上可以设置更多高级选项，例如按调用者类过滤记录的提示等。有关更多信息，请参阅官方文档。

自定义提示

如果您需要为反射、资源、序列化、代理使用等提供自己的提示，可以使用 RuntimeHintsRegistrar API。创建一个实现 RuntimeHintsRegistrar 接口的类，然后对提供的 RuntimeHints 实例进行适当的调用：

import java.lang.reflect.Method;

import org.springframework.aot.hint.ExecutableMode;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;
import org.springframework.util.ReflectionUtils;

public class MyRuntimeHints implements RuntimeHintsRegistrar {

	@Override
	public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
		// Register method for reflection
		Method method = ReflectionUtils.findMethod(MyClass.class, "sayHello", String.class);
		hints.reflection().registerMethod(method, ExecutableMode.INVOKE);

		// Register resources
		hints.resources().registerPattern("my-resource.txt");

		// Register serialization
		hints.serialization().registerType(MySerializableClass.class);

		// Register proxy
		hints.proxies().registerJdkProxy(MyInterface.class);
	}

}

然后，您可以在任何 @Configuration 类（例如您的 @SpringBootApplication 注解的应用程序类）上使用 @ImportRuntimeHints 来激活这些提示。

如果您有需要绑定的类（主要在序列化或反序列化 JSON 时需要），您可以在任何 bean 上使用 @RegisterReflectionForBinding。大多数提示都是自动推断的，例如当从 @RestController 方法接受或返回数据时。但是当您直接使用 WebClient、RestClient 或 RestTemplate 时，您可能需要使用 @RegisterReflectionForBinding。

测试自定义提示

RuntimeHintsPredicates API 可用于测试您的提示。该 API 提供了构建 Predicate 的方法，可用于测试 RuntimeHints 实例。

如果您使用 AssertJ，您的测试将如下所示：

import org.junit.jupiter.api.Test;

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.predicate.RuntimeHintsPredicates;
import org.springframework.boot.docs.packaging.nativeimage.advanced.customhints.MyRuntimeHints;

import static org.assertj.core.api.Assertions.assertThat;

class MyRuntimeHintsTests {

	@Test
	void shouldRegisterHints() {
		RuntimeHints hints = new RuntimeHints();
		new MyRuntimeHints().registerHints(hints, getClass().getClassLoader());
		assertThat(RuntimeHintsPredicates.resource().forResource("my-resource.txt")).accepts(hints);
	}

}

静态提供提示

如果您愿意，可以在一个或多个 GraalVM JSON 提示文件中静态提供自定义提示。这些文件应放在 src/main/resources/ 中的 META-INF/native-image/*/*/ 目录内。在 AOT 处理期间生成的提示被写入名为 META-INF/native-image/{groupId}/{artifactId}/ 的目录。将您的静态提示文件放在与此位置不冲突的目录中，例如 META-INF/native-image/{groupId}/{artifactId}-additional-hints/。

已知限制

GraalVM native images 是一项不断发展的技术，并非所有库都提供支持。 GraalVM 社区通过为尚未提供自己的项目提供可达性元数据来提供帮助。 Spring 本身不包含第三方库的提示，而是依赖可达性元数据项目。

如果您在为 Spring Boot 应用程序生成 native images 时遇到问题，请查看 Spring Boot wiki 的 Spring Boot with GraalVM 页面。您还可以在 GitHub 上向 spring-aot-smoke-tests 项目提交问题，该项目用于确认常见应用程序类型按预期工作。

如果您发现某个库与 GraalVM 不兼容，请在可达性元数据项目上提出问题。