如何用native-maven-plugin结合元数据与配置构建Spring MVC原生镜像

核心需求与已完成的实现 #

你最初的核心目标包括：

• 让native-maven-plugin指向已构建好的Spring MVC 5 fat jar
• 同时使用自定义反射配置文件和公开的可达性元数据
• 加载已有的predefined-classes-config.json文件
• 可选将native-agent整合进构建流程
• 确认GraalVM CE 21.0.2对应的插件版本，以及该GraalVM版本是否过时

已实现的配置（需求1、2） #

你已经通过以下native-maven-plugin配置搞定了需求1和2：

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.10.1</version>
    <configuration>
        <fallback>false</fallback>
        <mainClass>launch.Main</mainClass>
        <classpath>${project.build.directory}/ROOT.jar</classpath>
        <metadataRepository>
            <enabled>true</enabled>
        </metadataRepository>
        <verbose>true</verbose>
    </configuration>
    <executions>
        <execution>
            <id>build-native</id>
            <goals>
                <goal>compile-no-fork</goal>
            </goals>
            <phase>package</phase>
            <configuration>
                <buildArgs>
                    <buildArg>--report-unsupported-elements-at-runtime</buildArg>
                    <buildArg>-H:ReflectionConfigurationFiles=native-image/conf/reflect-config-custom.json</buildArg>
                    <buildArg>-H:ResourceConfigurationFiles=native-image/conf/resource-config-custom.json</buildArg>
                    <buildArg>--enable-all-security-services</buildArg>
                    <buildArg>--enable-http</buildArg>
                    <buildArg>--enable-https</buildArg>
                </buildArgs>
                <jvmArgs>
                    <arg>--add-opens=java.base/java.lang=ALL-UNNAMED</arg>
                    <arg>--add-opens=java.base/java.io=ALL-UNNAMED</arg>
                    <arg>--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED</arg>
                    <arg>-Dspring.profiles.active=ad</arg>
                </jvmArgs>
                <pluginArtifacts>
                    <pluginArtifact>
                        <file>${project.build.directory}/ROOT.jar</file>
                        <type>jar</type>
                    </pluginArtifact>
                </pluginArtifacts>
            </configuration>
        </execution>
    </executions>
</plugin>

需求2、3的最终解决办法 #

你后续发现用-H:ConfigurationFileDirectories参数就能同时搞定自定义配置加载和公开元数据的使用，而且不需要把predefined-classes-config.json放进jar包，只要指定配置文件所在的目录就行，这个方案很高效。

关于预定义类的建议 #

先明确概念：预定义类是GraalVM Native Image用来标记那些静态分析检测不到、但构建时必须显式保留的类——比如框架内部的基础类、SPI实现类，或者运行时动态加载的类。给你几个实操建议：

• 不用打包进jar：完全没必要把predefined-classes-config.json塞进fat jar，用-H:ConfigurationFileDirectories指定目录，Native Image会自动读取这个文件。
• 验证配置有效性：开启--verbose参数查看构建日志，检查预定义类有没有被正确加载；如果运行时出现类找不到的错误，先核对配置文件里的类路径是不是写对了。
• 结合native-agent减少手动维护：如果后续需要更新预定义类列表，把native-agent加进构建流程就行——运行测试的时候，agent会自动收集所有需要的类，生成完整的配置文件，你直接合并到自定义配置里即可，避免手动编写遗漏。

版本兼容性说明 #

• GraalVM版本：GraalVM CE 21.0.2确实偏旧，建议升级到和Spring MVC 5兼容的LTS版本，比如22.3.x系列，新版本修复了很多Native Image的兼容性问题，对Spring生态的支持也更完善。
• 插件版本：你当前使用的native-maven-plugin 0.10.1和GraalVM 21.0.2是兼容的，但如果升级GraalVM到22.3.x，记得同步把插件升到0.13.x版本，确保版本匹配。

可选：把native-agent整合进构建流程 #

如果想自动收集配置、减少手动编写工作量，可以在maven里新增agent的执行步骤：
在native-maven-plugin的executions中添加以下配置，绑定到test阶段：

<execution>
    <id>native-agent</id>
    <goals>
        <goal>agent</goal>
    </goals>
    <phase>test</phase>
    <configuration>
        <outputDirectory>${project.build.directory}/native-image-agent-output</outputDirectory>
    </configuration>
</execution>

运行mvn test后，agent会在指定目录生成完整的配置文件，后续你可以将这些文件合并到自定义配置中，降低维护成本。

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