高级原生镜像主题

嵌套配置属性

Spring 提前编译引擎会自动为配置属性创建反射提示。但是，不是内部类的嵌套配置属性**必须**使用 @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 属性在原生镜像中将不可绑定。

使用构造函数绑定时，必须使用 @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;
	}

}

使用记录时，必须使用 @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 转换为原生镜像。这出于多种原因可能很有用，包括

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

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

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

使用 Buildpacks

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

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

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

假设一个作为myproject-0.0.1-SNAPSHOT.jar构建的经过 AOT 处理的 Spring Boot 可执行 jar 位于target目录中，请运行

$ pack build --builder paketobuildpacks/builder-jammy-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 转换为原生可执行文件的另一个选项是使用 GraalVM 的native-image工具。要使其工作，您需要在机器上安装 GraalVM 发行版。您可以在Liberica Native Image Kit 页面手动下载它，也可以使用 SDKMAN! 等下载管理器。

假设一个作为myproject-0.0.1-SNAPSHOT.jar构建的经过 AOT 处理的 Spring Boot 可执行 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 原生镜像跟踪代理允许您拦截 JVM 中的反射、资源或代理使用情况，以生成相关的提示。Spring 应该自动生成大多数这些提示，但跟踪代理可用于快速识别缺少的条目。

当使用代理为原生镜像生成提示时，有两种方法

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

当库或模式未被 Spring 识别时，第一个选项对于识别缺少的提示很有趣。

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

直接启动应用程序

使用以下命令启动附加了原生镜像跟踪代理的应用程序

$ 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停止应用程序。

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

还有更多高级选项可以在原生镜像跟踪代理上设置，例如按调用方类等过滤记录的提示。有关进一步阅读，请参阅官方文档。

自定义提示

如果您需要为反射、资源、序列化、代理使用等提供自己的提示，则可以使用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 原生镜像是一项不断发展的技术，并非所有库都提供支持。GraalVM 社区通过为尚未发布自己的项目的项目提供可达性元数据来提供帮助。Spring 本身不包含第三方库的提示，而是依赖于可达性元数据项目。

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

如果您发现某个库无法与 GraalVM 一起使用，请在可达性元数据项目上提出问题。