Mastering Spring Native with GraalVM: A Hands‑On Guide to Configuring Mica Components

Introduction

Hello everyone, I am "L.cm" from Rumen Technology. In this tutorial we will dive into Spring Native with GraalVM, presenting a hands‑on, hard‑core example.

Spring Native

2.1 GraalVM native image configuration generation

After compiling the spring native project ( mica-native-test) the following GraalVM native‑image configuration files are produced.

These files allow configuration of dynamic proxies, reflection, resource files, and serialization.

2.2 Spring Native hints

Spring Native provides many hints to configure unsupported dynamic proxies, reflection, and resources for native images. The main hints are illustrated below.

These hints generate entries in proxy-config.json, reflect-config.json, resource-config.json, and serialization-config.json.

Mica adaptation

We use several Mica components as examples to demonstrate Spring Native hints.

3.1 mica‑ip2region

The mica-ip2region module requires the ip2region.db file, so we need to add a custom resource configuration.

Add the Spring Native dependency:

<dependency>
    <groupId>org.springframework.experimental</groupId>
    <artifactId>spring-native</artifactId>
    <version>${spring-native.version}</version>
    <scope>provided</scope>
</dependency>

Then annotate the configuration class with @NativeHint to include the ip2region.db resource.

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(Ip2regionProperties.class)
@NativeHint(resources = @ResourceHint(patterns = "^ip2region/ip2region.db"))
public class Ip2regionConfiguration {
    @Bean
    public Ip2regionSearcher ip2regionSearcher(ResourceLoader resourceLoader,
                                               Ip2regionProperties properties) {
        return new Ip2regionSearcherImpl(resourceLoader, properties);
    }
}

After recompiling the mica-native-test project, the ip2region.db file appears in resource-config.json.

Running the project shows the component works perfectly.

3.2 mica‑captcha

The mica-captcha module needs font files; we add a resource hint similar to the previous step.

@NativeHint(resources = @ResourceHint(patterns = "^fonts/.*.ttf"))

When building a native image in Docker, install the required fonts: yum install fontconfig -y && fc-cache --force For AWT‑related errors on macOS, see GraalVM issues 817 and 2842.

3.3 mica‑caffeine

The caffeine library uses many unsafe operations, requiring extensive @NativeHint configurations. After adding the following hints, the application starts successfully.

@NativeHint(types = {
    @TypeHint(types = CaffeineAutoCacheManager.class, access = AccessBits.ALL),
    @TypeHint(types = CaffeineCacheManager.class, access = AccessBits.ALL),
    @TypeHint(typeNames = "com.github.benmanes.caffeine.cache.UnsafeAccess",
        fields = @FieldHint(name = "UNSAFE", allowUnsafeAccess = true),
        access = AccessBits.PUBLIC_METHODS),
    @TypeHint(types = Thread.class, access = AccessBits.DECLARED_FIELDS),
    @TypeHint(typeNames = "com.github.benmanes.caffeine.cache.PS",
        fields = {
            @FieldHint(name = "key", allowUnsafeAccess = true),
            @FieldHint(name = "value", allowUnsafeAccess = true)
        },
        access = AccessBits.DECLARED_CONSTRUCTORS),
    // ... (additional type hints omitted for brevity)
})

After adding these hints, the application runs without errors.

Conclusion

Spring Native is still in an incubating stage; it works well for simple projects without many third‑party components, but larger applications may need to wait for further maturity. We will continue to monitor and publish related articles.

Thanks for reading – I’m "Chun Ge", see you next time!