编辑
2026-11-21
学习记录
0

目录

从零搭一个 Spring Boot 项目,一次构建出 Native Image(便签实战)
1. 环境
2. 用 Spring Initializr 搭骨架
3. 写业务代码——故意把 native 会踩的都摆出来
StickyNote.java
AddNoteRequest.java
NotesStore.java
NotesController.java
4. 先把 JVM 版跑通(这是前提,不是终点)
5. Native 三件套
5.1 手写反射清单 NativeHints
5.2 契约测试:把「忘注册」钉成 mvn test 红灯
5.3 Dockerfile.native
6. 构建镜像
7. 冒烟清单(顺序不可反)
8. 报错手册:症状 → 病因 → 修法
编译期
运行期(缺反射的标准死法,全部实测过原文)
自查两条命令(不用重打镜像)
增量兜底:tracing agent 录制
「换 Jackson 3 是不是就省了」
9. 运行参数与观测(native 没有 JVM)
10. demo → 真实项目:动手前的盘查清单
References(官方来源,2026-11-21 核对)

从零搭一个 Spring Boot 项目,一次构建出 Native Image(便签实战)

面向的场景:项目还没写(或者你手里有个新项目),想从第一行代码起就把 GraalVM native image 的路走通。本文用一个便签笔记 API demo 全程实做:每一节都有要跑的命令和预期输出,全部命令在 2026-11-21 实测过(Spring Boot 4.2.0 / Java 25 / GraalVM native-image 25 / Docker 引擎不限,本文不依赖任何特殊工具)。

已有项目要转 native?这篇照样适用——§3–§5 的「动态特性面」就是改造时要盘的东西。

关于「一定成功」:native-image 是 closed-world 编译,决定成败的是你的代码用了多少编译期看不见的动态特性,不是命令本身。本 demo 特意把三类最常踩的动态特性都摆出来(自管 Jackson mapper、controller 返回 record、文件落盘),按流程走一遍你就把套路学会了;到 §8 你能拿到「不管什么报错都有对应查法」的排查表。照做保证的是每一步可验证,不是零报错——报错不可怕,§8 就是为它写的。

1. 环境

只需要三样,全部用官方发行:

工具版本要求验证命令本机示例输出
JDK21+(本文 25)java -versionopenjdk 25.0.x(哪个厂商都行)
Maven3.9+mvn -versionApache Maven 3.9.x
Docker 引擎任意能跑的docker versionKiri/Desktop/Engine 均可

GraalVM 不需要装到本机——构建全在容器里做(§6),这是本流程对外网依赖最小、对开发机侵入最小的路线。

内存前提:native-image 编译阶段要 6–10GB 可用(小 demo 也躲不掉:本文 demo 编译器峰值 RSS 实测 4.59GB,依赖多的项目更高)。Docker Desktop 用户记得把 VM 内存调到 8GB+。

架构前提:在什么架构上编,就产出什么架构的二进制。linux/amd64 的部署目标就在 amd64 机器上构建;Apple Silicon 上不要用 buildx + QEMU 跨编(大概率死在编译中途)。

2. 用 Spring Initializr 搭骨架

命令行一步到位(等价的网页版是 https://start.spring.io ,依赖选 Spring Web,其余同参数):

bash
mkdir notes && cd notes curl -s https://start.spring.io/starter.tgz \ -d dependencies=web -d javaVersion=25 -d type=maven-project \ -d groupId=com.example -d artifactId=notes -d name=notes | tar -xzf -

基线确认(此刻还没有业务代码,应一次通过):

bash
mvn test

实测输出:BUILD SUCCESS,跑掉脚手架自带的 1 个上下文测试,Boot 版本 4.2.0、java.version 25(以 Initializr 当日默认为准;3.x 的老项目同样适用本文,AOT/hints 机制一致)。

3. 写业务代码——故意把 native 会踩的都摆出来

便签 API 三个接口,五个文件。每个文件的作用和它埋的 native 考点都标在注释外的表里:

文件干什么native 考点
StickyNote便签 recordcontroller 返回 record——AOT 不管返回类型
AddNoteRequest请求体 recordAOT 会自动兜 @RequestBody(留作对照组)
NotesStore.Snapshot落盘载体 record(嵌套)嵌套 record + 自管 mapper,AOT 两头都不管
NotesStorenew JsonMapper() 读写 ./data/notes.json自管 mapper = Spring 看不见 = hints 推导不到
NotesControllerGET/POST/DELETE + 400 校验触发以上全部序列化路径

StickyNote.java

java
package com.example.notes; /** 一条便签。id 是存储层生成的自增串,createdAt 用 ISO-8601 字符串。 */ public record StickyNote(String id, String text, String createdAt) { }

AddNoteRequest.java

java
package com.example.notes; /** POST /api/notes 的请求体。text 必填由 controller 校验。 */ public record AddNoteRequest(String text) { }

NotesStore.java

java
package com.example.notes; import java.io.IOException; import java.io.UncheckedIOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.StandardCopyOption; import java.time.Instant; import java.util.ArrayList; import java.util.List; import java.util.Optional; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import tools.jackson.databind.json.JsonMapper; /** * 自管 Jackson 的 JSON 文件存储——native 迁移的主成本就在这类地方: * mapper 不是 Spring bean,AOT 推导不出它读写的类,必须手写反射 hints。 * 落盘走 temp-then-move,进程崩了也不留半个 JSON。 */ @Component public class NotesStore { /** 落盘载体:包一层 record 而不是直接序列化 List,省掉泛型 TypeReference。 */ public record Snapshot(List<StickyNote> notes) { } private final Path file; private final JsonMapper mapper = JsonMapper.builder().build(); private final List<StickyNote> notes = new ArrayList<>(); private long seq = 0; public NotesStore(@Value("${notes.file:./data/notes.json}") String path) throws IOException { this.file = Path.of(path); if (Files.exists(file)) { Snapshot loaded = mapper.readValue(file.toFile(), Snapshot.class); if (loaded != null && loaded.notes() != null) { notes.addAll(loaded.notes()); notes.stream().map(StickyNote::id).mapToInt(Integer::parseInt).max() .ifPresent(max -> seq = max); } } } public synchronized StickyNote add(String text) { StickyNote note = new StickyNote(String.valueOf(++seq), text, Instant.now().toString()); notes.add(note); persist(); return note; } public synchronized Optional<StickyNote> remove(String id) { Optional<StickyNote> hit = notes.stream().filter(n -> n.id().equals(id)).findFirst(); hit.ifPresent(n -> { notes.remove(n); persist(); }); return hit; } public synchronized List<StickyNote> list() { return List.copyOf(notes); } private void persist() { try { Files.createDirectories(file.getParent()); Path tmp = file.resolveSibling(file.getFileName() + ".tmp"); mapper.writeValue(tmp.toFile(), new Snapshot(List.copyOf(notes))); Files.move(tmp, file, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE); } catch (IOException e) { throw new UncheckedIOException("Failed to write notes file: " + file, e); } } }

两个说明:

  • tools.jackson.databind.json.JsonMapper 是 Jackson 3(Boot 4 的默认 JSON 库)。demo 从零起就用它是正路;老项目里 Jackson 2/3 并存也完全不影响本流程——native 的成本在「自管实例」,不在版本(换库省不了事,§8 末尾有论证)。
  • Snapshot 包一层而不是直接序列化 List<StickyNote>:省掉 TypeReference 泛型黑魔法,且嵌套 record(编译产物 NotesStore$Snapshot.class)正是最容易漏注册的那种。

NotesController.java

java
package com.example.notes; import java.util.List; import java.util.Map; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.DeleteMapping; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api/notes") public class NotesController { private final NotesStore store; public NotesController(NotesStore store) { this.store = store; } @GetMapping public List<StickyNote> list() { return store.list(); } @PostMapping public StickyNote add(@RequestBody AddNoteRequest request) { if (request == null || request.text() == null || request.text().isBlank()) { throw new IllegalArgumentException("text must not be blank"); } return store.add(request.text().trim()); } @DeleteMapping("/{id}") public ResponseEntity<?> remove(@PathVariable String id) { return store.remove(id) .<ResponseEntity<?>>map(ResponseEntity::ok) .orElseGet(() -> ResponseEntity.status(HttpStatus.NOT_FOUND) .body(Map.of("message", "note not found: " + id))); } /** 参数校验统一 400 + 可读 message;不留给 Spring 默认 500。 */ @ExceptionHandler(IllegalArgumentException.class) public ResponseEntity<?> badRequest(IllegalArgumentException e) { return ResponseEntity.badRequest().body(Map.of("message", e.getMessage())); } }

4. 先把 JVM 版跑通(这是前提,不是终点)

bash
mvn -DskipTests package java -jar target/notes-0.0.1-SNAPSHOT.jar

另开终端把每条路径都打一遍:

bash
curl -s http://localhost:8080/api/notes # [] curl -s -X POST http://localhost:8080/api/notes -H 'Content-Type: application/json' -d '{"text":"first note"}' # {"id":"1","text":"first note","createdAt":"2026-11-21T05:53:36.197658600Z"} curl -s -X POST http://localhost:8080/api/notes -H 'Content-Type: application/json' -d '{"text":""}' -w ' http=%{http_code}' # {"message":"text must not be blank"} http=400 curl -s http://localhost:8080/api/notes # [{"id":"1","text":"first note","createdAt":"..."}] cat data/notes.json # {"notes":[{"id":"1","text":"first note","createdAt":"..."}]} curl -s -X DELETE http://localhost:8080/api/notes/1 -w ' del http=%{http_code}'

全部符合预期 → JVM 基线成立。JVM 全绿不代表 native 能跑(native 的失败模式是 JVM 根本不会遇到的反射缺失),但 JVM 不绿就没必要往下走了——先修逻辑再谈编译。

5. Native 三件套

5.1 手写反射清单 NativeHints

为什么必须手写——AOT 有两个盲区,本 demo 五条序列化路径里两条各踩一个:

序列化发生在AOT 管吗例子
@RequestBody 反序列化✅ 自动注册AddNoteRequest
controller 返回类型序列化❌ 不管StickyNote(实测参考:rag-agent 的 MealDecision 就因为这条在线上裸 500)
自管 mapper(new ObjectMapper() / JsonMapper.builder().build())读写❌ 完全看不见NotesStore.Snapshot 的落盘/加载
java
package com.example.notes; import org.springframework.aot.hint.MemberCategory; import org.springframework.aot.hint.RuntimeHints; import org.springframework.aot.hint.RuntimeHintsRegistrar; /** * native 反射清单:所有会被 Jackson 序列化的 record。 * * controller 返回类型 AOT 不管(它只兜 @RequestBody),自管 mapper 读写 AOT 更不知道—— * 少一个类就是 native 上一个 500。加 record 时同步这里,NativeHintsContractTest 会替你把关。 */ public class NativeHints implements RuntimeHintsRegistrar { @Override public void registerHints(RuntimeHints hints, ClassLoader classLoader) { MemberCategory[] categories = { MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS, MemberCategory.INVOKE_PUBLIC_METHODS, MemberCategory.INVOKE_DECLARED_CONSTRUCTORS, MemberCategory.DECLARED_FIELDS }; hints.reflection().registerType(StickyNote.class, categories); hints.reflection().registerType(AddNoteRequest.class, categories); hints.reflection().registerType(NotesStore.Snapshot.class, categories); } }

挂上入口(Spring Boot 的 @SpringBootApplication 加一个注解):

java
@SpringBootApplication @ImportRuntimeHints(NativeHints.class) public class NotesApplication { ... }

四类 MemberCategory 的来历(都是实测换来的):INVOKE_PUBLIC_METHODS 给 record 访问器(Jackson 3 拿不到 record components 会报 UnsupportedFeatureError);DECLARED_FIELDS 给 Jackson 2 风格读字段;两个构造器类别兜反序列化。别嫌多,少一类就是一场只在线上见的事故。

5.2 契约测试:把「忘注册」钉成 mvn test 红灯

native 反射事故的头号来源是以后加功能的人(包括下个月的你)新加了 record 忘了同步 5.1。一份按名字断言的测试根治:

java
package com.example.notes; import static org.assertj.core.api.Assertions.assertThat; import java.io.File; import java.util.LinkedHashMap; import java.util.LinkedHashSet; import java.util.Map; import java.util.Set; import java.util.TreeSet; import org.junit.jupiter.api.Test; import org.springframework.aot.hint.MemberCategory; import org.springframework.aot.hint.RuntimeHints; /** 契约测试:包里每个 record(含嵌套)都必须注册进 NativeHints,忘注册时 mvn test 变红。 */ class NativeHintsContractTest { private static final Set<MemberCategory> REQUIRED = Set.of( MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS, MemberCategory.INVOKE_PUBLIC_METHODS, MemberCategory.INVOKE_DECLARED_CONSTRUCTORS, MemberCategory.DECLARED_FIELDS); @Test void everyRecordIsRegistered() throws Exception { File dir = new File(StickyNote.class.getProtectionDomain().getCodeSource() .getLocation().getPath().replace("%20", " "), "com/example/notes"); Set<Class<?>> records = new LinkedHashSet<>(); File[] files = dir.listFiles((d, n) -> n.endsWith(".class")); assertThat(files).isNotNull(); for (File file : files) { String name = "com.example.notes." + file.getName().replace(".class", ""); Class<?> type = Class.forName(name, false, getClass().getClassLoader()); if (type.isRecord()) { records.add(type); } } assertThat(records).isNotEmpty(); RuntimeHints hints = new RuntimeHints(); new NativeHints().registerHints(hints, getClass().getClassLoader()); Map<String, Set<MemberCategory>> registered = new LinkedHashMap<>(); hints.reflection().typeHints().forEach(h -> registered.put(h.getType().getName(), h.getMemberCategories())); Set<String> gaps = new TreeSet<>(); for (Class<?> record : records) { Set<MemberCategory> owned = registered.get(record.getName()); if (owned == null) { gaps.add(record.getName() + "(未注册)"); } else { REQUIRED.stream().filter(c -> !owned.contains(c)) .forEach(c -> gaps.add(record.getName() + " 缺 " + c)); } } assertThat(gaps).isEmpty(); } }
bash
mvn test

实测:2 个测试通过(上下文 + 契约)。这个套路在 rag-agent 里第一次跑就抓出两条漏网(一条靠 AOT 侥幸、一条是真·潜伏线上 500),值得你抄。

API 注记:Spring Framework 7(Boot 4)里读 hints 用 reflection().typeHints() 流 + TypeHint.getMemberCategories();Boot 3.x 的老代码是 entries(),抄的时候对一下版本。

5.3 Dockerfile.native

两阶段:借 Maven 发行版下载依赖,借 GraalVM 发行版做 AOT + 原生编译,运行层只要 glibc + 证书 + 时区。

dockerfile
# syntax=docker/dockerfile:1 ARG NATIVE_IMAGE=ghcr.io/graalvm/native-image-community:25 ARG MAVEN_IMAGE=maven:3.9-eclipse-temurin-25 ARG RUNTIME_IMAGE=debian:12-slim FROM ${MAVEN_IMAGE} AS maven FROM ${NATIVE_IMAGE} AS build COPY --from=maven /usr/share/maven /opt/maven ENV PATH=/opt/maven/bin:$PATH \ MAVEN_OPTS="-Xmx1g" WORKDIR /build COPY docker/maven-settings.xml /build/maven-settings.xml COPY pom.xml ./ RUN --mount=type=cache,target=/root/.m2 \ mvn -B -q -s /build/maven-settings.xml \ org.apache.maven.plugins:maven-dependency-plugin:3.8.1:go-offline || true COPY src ./src RUN --mount=type=cache,target=/root/.m2 \ mvn -B -s /build/maven-settings.xml -Pnative -Dmaven.test.skip=true native:compile FROM ${RUNTIME_IMAGE} WORKDIR /app RUN apt-get update && apt-get install -y --no-install-recommends \ ca-certificates tzdata bash zlib1g \ && rm -rf /var/lib/apt/lists/* \ && groupadd --system app && useradd --system --gid app app \ && mkdir -p /app/data && chown -R app:app /app COPY --from=build --chown=app:app /build/target/notes /app/notes ENV SERVER_PORT=8080 TZ=Asia/Shanghai LANG=C.UTF-8 EXPOSE 8080 USER app:app HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ CMD bash -c 'exec 3<>/dev/tcp/127.0.0.1/8080; printf "GET /api/notes HTTP/1.0\r\nHost: localhost\r\n\r\n" >&3; head -n 1 <&3 | grep -q "200"' ENTRYPOINT ["/app/notes"] CMD ["-Xmx256m"]

要点逐条:

  • -Pnative 是 spring-boot-starter-parent 自带的 profile,pom 不用改——它自动接上 process-aot(AOT 代码+hints 生成)和 add-reachability-metadata(拉社区元数据仓库,覆盖主流三方库)。
  • native:compile 产出的二进制名 = <imageName>,默认取 artifactId(这里是 notes);想让 Dockerfile 里 COPY 路径稳定,就在 pom 的 native-maven-plugin 显式写 <imageName>。
  • 依赖层和源码层分开 + .m2 cache mount:改代码重编不重下依赖。
  • CMD ["-Xmx256m"] 就是堆的默认值(native 没有 JVM,堆只能当启动参数传,运行时可盖,见 §7)。
  • 配套 docker/maven-settings.xml(国内走阿里云,可选):
xml
<settings> <mirrors> <mirror> <id>aliyun-public</id> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings>
  • .dockerignore 别忘:
target/ data/

6. 构建镜像

bash
docker build -f Dockerfile.native -t notes:native . # 国内网络(docker.io 不可达时连 `# syntax` 行都要走 mirror,实测漏了它第一步就失败): docker build -f Dockerfile.native -t notes:native \ --build-arg BUILDKIT_SYNTAX=docker.m.daocloud.io/docker/dockerfile:1 \ --build-arg NATIVE_IMAGE=ghcr.m.daocloud.io/graalvm/native-image-community:25 \ --build-arg MAVEN_IMAGE=docker.m.daocloud.io/library/maven:3.9-eclipse-temurin-25 \ --build-arg RUNTIME_IMAGE=docker.m.daocloud.io/library/debian:12-slim .

实测(本机冷缓存):native-image 编译 94.6 秒,含依赖下载全程约 3 分钟;产出镜像 63.6MB(demo 依赖面小——rag-agent 那种带 Tika 的重项目是 131MB)。

编译期报错看 §8 的表;编过了不等于能跑,继续 §7。

7. 冒烟清单(顺序不可反)

bash
mkdir -p data && docker run -d --name notes -p 127.0.0.1:8087:8080 \ -v "$PWD/data:/app/data" notes:native
  1. 启动:docker logs notes 应看到 Started 行。实测:native 0.06 秒(空库),同一个 demo 的 JVM 版 1.35 秒——启动收益的量级感就在这。
  2. 只读:curl -s http://localhost:8087/api/notes → [] 或已有数据。
  3. 写 + 落盘:POST 一条 → 返回带 id 的 JSON → cat data/notes.json 确认宿主侧文件真的写了(容器里跑 spring/app 用户,卷权限不对会死在这步)。
  4. 校验路径:POST 空 text → 400 + message。
  5. 删除 + 持久化再确认:DELETE → 文件同步更新。
  6. 重启回读:docker restart notes 再 GET——上一步写的数据要能加载回来(这是自管 mapper 读路径的反射验证,1–5 只验了写)。

实测:七步全过(含第 6 步重启回读——native 下自管 mapper 的读路径同样被验证)。私有 RSS 29MB(demo 空载;挂 48MB 语料的 rag-agent 是 151.5MiB,参照 §9 的口径别用 top 比)。

上线判据:每个接口的成功分支真回过 200。只把 404/400 失败分支走顺不算数——序列化死在错误处理之后,失败路径永远碰不到它(rag-agent 的饭点决策就是这么在线上炸的,502 友好了一年,配好域名走成功分支当天变裸 500)。

8. 报错手册:症状 → 病因 → 修法

编译期

报错病因修法
NoClassDefFoundError in some Feature传递依赖自带的 GraalVM Feature 假设了不存在于你 classpath 的东西找该库的官方禁用开关塞进 <buildArg>-J-Dxxx=false</buildArg>(rag-agent 实测:angus-activation 的 mailcap Feature 用 -J-Dangus.activation.native-image.enable=false 关掉)
编译中途被 kill内存不够没有绕法,加内存
class 文件版本不匹配NATIVE_IMAGE 和 MAVEN_IMAGE 的 JDK 版本不同源对齐版本

运行期(缺反射的标准死法,全部实测过原文)

症状/报错病因修法
No serializer found for class X and no properties discoveredX 是 mapper 要序列化的 record/POJO,hints 漏了NativeHints 加 X.class(嵌套类单独加:Outer.Inner.class);§5.2 的测试早就该红
接口裸 500 {timestamp,status,error,path} 无 message死在消息转换器阶段,你的异常处理器接不到九成是上一行;先查 hints
MissingReflectionRegistrationError 指向 SDK 内部类(如 putAdditionalProperty)三方 SDK 自带 META-INF 配置权限不全升级 SDK 通常没用(rag-agent 实测 OpenAI SDK 4.80.0→4.111.0 缺口依旧);按 SDK 报错提示在 src/main/resources/META-INF/native-image/<group>/<artifact>/ 批量补 JSON,官方自动合并机制,不是 hack
UnsupportedFeatureError: Record components not availablerecord 访问器没注册补 INVOKE_PUBLIC_METHODS
ArrayIndexOutOfBoundsException at ...BitFieldSet...(flexmark 类位掩码库静态初始化崩)库用 getEnumConstants() 反射枚举,native 下 values() 没注册返回空数组全部相关枚举注册 INVOKE_PUBLIC_METHODS;清单扫法:解包 class → grep java/lang/Enum 候选 → javap 核实 final class ... extends java.lang.Enum(泛型约束是假候选)。注意 tracing agent 对这类反射录不全,必须手工
一切正常,除了某条功能线上 500,而它失败分支友好成功分支才走到序列化让成功分支可达(配好外部依赖)再验——这也是为什么冒烟清单第 7 节不许跳步

自查两条命令(不用重打镜像)

bash
# AOT 给某类生成了什么: mvn -Pnative -Dmaven.test.skip=true spring-boot:process-aot grep -c 'StickyNote' target/spring-aot*/main/resources/META-INF/native-image/*/*/reachability-metadata.json # native 二进制认哪些运行参数(官方标志表): docker run --rm notes:native -XX:PrintFlags=

增量兜底:tracing agent 录制

功能多了、依赖换了、报错查不过来时,用 JVM 挂 agent 录一遍真实流量再合并进 META-INF(GraalVM 24+ 是统一格式单文件;native-image-configure 没有 merge 子命令,并集要自己做或手工粘):

bash
docker run -d -v $PWD/trace-out:/trace-out <镜像JVM版> \ java '-agentlib:native-image-agent=config-output-dir=/trace-out' -jar app.jar # 把每条路径打一遍,然后优雅停止——agent 在 JVM 退出时才落盘: docker stop -t 30 <容器>

两条边界:只录走过的路径;不能替代手工清单(位掩码枚举类反射实测录不全)。rag-agent 仓库里 trace-native.ps1 + scripts/merge-trace-config.js + trace-collect.ps1 是现成实现。

「换 Jackson 3 是不是就省了」

不省,有实测背书:Boot 4 的 MVC 转换器本来就是 Jackson 3(tools.jackson 3.1.5 在 classpath),上面那条 record 500 恰恰是 Jackson 3 序列化的——换库救不了 hints 缺口;而 Jackson 2 又常因 SDK 内部依赖删不掉。native 成本的分界线是「自管实例 vs Spring 托管」,不是「2 vs 3」。

9. 运行参数与观测(native 没有 JVM)

  • 堆参数只能当启动参数:docker run ... notes:native -Xmx256m;compose 用 command:(整体替换镜像 CMD)。
  • JAVA_TOOL_OPTIONS 被静默忽略——那行环境变量在 native 容器里等于没写,不报错,这是最阴的坑。
  • 参数三类(实测 GraalVM 25):-Xms/-Xmx/-Xmn/-Xss 与 -XX:MaxDirectMemorySize/-XX:ActiveProcessorCount/-XX:+ExitOnOutOfMemoryError 生效;未识别的 -X 开头静默忽略;未识别的 -XX: 键拒启(error: Could not find option,restart 循环)。JVM 时代的 -XX:TieredStopAtLevel/-XX:MaxMetaspaceSize/-XX:+UseSerialGC 一概别搬。
  • 内存观测用 docker stats 或私有 RSS(/proc/1/statm resident−shared),别用 top 的 VmRSS:native 的 RSS 一半是二进制的只读共享映射。同条件实测对照(48MB 语料的 rag-agent):cgroup 151MiB vs JVM 332MiB、私有 RSS 145MB vs 306MB,而 top 给出误导性的 294 vs 366。
  • 验证镜像真的更新:比对 image ID(docker images / tar 的 manifest.json Config sha256),别看构建日志的 DONE 行。

10. demo → 真实项目:动手前的盘查清单

本文 demo 只有 Jackson 序列化一种动态特性。真项目照单全查,每一格都可能在 §8 里等你:

  • 还有哪些自管 mapper(new ObjectMapper() / JsonMapper.builder())在读写的类?→ 全进 NativeHints + 契约测试管住
  • 有没有三方 SDK 自带 META-INF 配置不全?→ 真 key 打到成功分支才算数(§7 第 7 条)
  • 用了哪些做动态代理/反射枚举/位掩码的库(flexmark、各类配置映射器)?→ 手工清单,agent 兜不住
  • 资源加载(模板、字体、getClassLoader().getResource)?→ hints.resources()
  • @ConfigurationProperties、SpEL、序列化白名单等 Spring 动态件?→ AOT 多半管,但每个都要冒烟走到
  • 定时任务/异步线程池在 native 的行为?→ 编译期会有 warning,别忽略
  • 值不值?收益是启动秒→毫秒、常驻内存 -40~55%(见 §9 实测);成本是每次加功能多维护一处 hints。长驻服务、小内存机器、冷启动敏感(serverless/挂件)值;天天改的重反射项目先掂量。

References(官方来源,2026-11-21 核对)

本文作者:Weee

本文链接:

版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!