使用GraalVM构建Spring Boot3原生镜像遇-parameters编译错误

问题场景 #

执行mvn clean native:compile构建Spring Boot 3的GraalVM原生镜像时，触发如下错误：

Constructor binding in a native image requires compilation with -parameters but the following classes were compiled without it:
    okhttp3.Protocol
    at org.springframework.boot.context.properties.bind.BindableRuntimeHintsRegistrar.registerHints(BindableRuntimeHintsRegistrar.java:91)
    at org.springframework.boot.context.properties.ConfigurationPropertiesBeanFactoryInitializationAotProcessor$ConfigurationPropertiesReflectionHintsContribution.applyTo(ConfigurationPropertiesBeanFactoryInitializationAotProcessor.java:70)
    at org.springframework.context.aot.BeanFactoryInitializationAotContributions.applyTo(BeanFactoryInitializationAotContributions.java:78)
    at org.springframework.context.aot.ApplicationContextAotGenerator.lambda$processAheadOfTime$0(ApplicationContextAotGenerator.java:58)
    at org.springframework.context.aot.ApplicationContextAotGenerator.withCglibClassHandler(ApplicationContextAotGenerator.java:67)
    at org.springframework.context.aot.ApplicationContextAotGenerator.processAheadOfTime(ApplicationContextAotGenerator.java:53)
    at org.springframework.context.aot.ContextAotProcessor.performAotProcessing(ContextAotProcessor.java:106)
    at org.springframework.context.aot.ContextAotProcessor.doProcess(ContextAotProcessor.java:84)
    at org.springframework.context.aot.ContextAotProcessor.doProcess(ContextAotProcessor.java:49)
    at org.springframework.context.aot.AbstractAotProcessor.process(AbstractAotProcessor.java:82)
    at org.springframework.boot.SpringApplicationAotProcessor.main(SpringApplicationAotProcessor.java:80)

环境信息 #

• OS: Windows 10 x64 22H2
• JDK: GraalVM CE 22.3.2 with Open JDK 17.0.7
• Maven: 3.9.1
• Spring-Boot: 3.1.0-RC1
• okhttp: 5.0.0-alpha.11

已尝试升级okhttp至最新版本，问题未解决；因其他依赖依赖okhttp，无法移除该包。

错误核心解析 #

1. okhttp3.Protocol是未合规编译的类：错误提示明确指出该类编译时未添加-parameters参数。
2. 为什么需要-parameters：Spring Boot 3的AOT（提前编译）和GraalVM原生镜像构建中，配置属性的构造函数绑定依赖反射获取参数名。Java默认编译不会将参数名存入class文件，-parameters参数会强制保留参数名，确保反射机制能正确识别，进而生成原生镜像所需的运行时提示。

解决方法 #

方法1：全局配置Maven编译时添加-parameters #

在pom.xml中配置maven-compiler-plugin，强制所有代码（包括依赖包的编译过程）添加该参数：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

方法2：手动添加Runtime Hints绕过检查 #

如果无法重新编译okhttp，可通过Spring的RuntimeHintsRegistrar手动注册反射提示，跳过AOT检查：

1. 创建自定义配置类：

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.ImportRuntimeHints;

@Configuration
@ImportRuntimeHints(OkHttpRuntimeHints.class)
public class OkHttpNativeConfig {
    static class OkHttpRuntimeHints implements RuntimeHintsRegistrar {
        @Override
        public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
            // 为okhttp3.Protocol的构造函数注册反射提示
            hints.reflection().registerConstructor(okhttp3.Protocol.class.getDeclaredConstructors()[0], true);
        }
    }
}

2. 确保该配置类被Spring Boot组件扫描机制覆盖。

方法3：等待okhttp官方适配 #

当前使用的是okhttp的alpha测试版本，官方后续正式版本可能会默认添加-parameters编译参数以适配Spring Boot 3的AOT要求，可关注官方版本更新。

内容的提问来源于stack exchange，提问作者Patryk Be