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:

<code>&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.experimental&lt;/groupId&gt;
    &lt;artifactId&gt;spring-native&lt;/artifactId&gt;
    &lt;version&gt;${spring-native.version}&lt;/version&gt;
    &lt;scope&gt;provided&lt;/scope&gt;
&lt;/dependency&gt;</code>

Then annotate the configuration class with

@NativeHint

to include the

ip2region.db

resource.

<code>@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);
    }
}</code>

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.

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

When building a native image in Docker, install the required fonts:

<code>yum install fontconfig -y && fc-cache --force</code>

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.

<code>@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)
})</code>

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!