---
title: "native RuntimeNativeRegistrar API 参考"
---

`RuntimeNativeRegistrar` 是 Solon AOT 提供的手动登记接口，用于补充框架自动处理不到的原生元信息（第三方框架的反射、资源、序列化等）。本页是完整 API 参考，用法示例见 《native 项目开发定制》。


### 1、接口定义

```java
public interface RuntimeNativeRegistrar {
    void register(AppContext context, RuntimeNativeMetadata metadata);
}
```

实现类注册为 Solon 组件（`@Component`）即可，AOT 阶段会自动收集并调用：

```java
@Component
public class RuntimeNativeRegistrarImpl implements RuntimeNativeRegistrar {
    @Override
    public void register(AppContext context, RuntimeNativeMetadata metadata) {
        // ...登记
    }
}
```

### 2、RuntimeNativeMetadata 方法一览

所有方法返回 `this`，可链式调用。

#### 2.1 反射登记

| 方法 | 说明 |
| --- | --- |
| `registerReflection(Class<?> type, MemberCategory... categories)` | 按成员类别登记反射 |
| `registerReflection(String className, MemberCategory... categories)` | 同上（按类名字符串） |
| `registerReflection(Class<?> type, Consumer<ReflectionHints> typeHint)` | 细粒度登记（可追加字段/方法/构造器明细） |
| `registerReflection(String className, Consumer<ReflectionHints> typeHint)` | 同上（按类名字符串） |
| `registerField(Field field)` | 登记单个字段 |
| `registerConstructor(Constructor<?> c, ExecutableMode mode)` | 登记单个构造器 |
| `registerMethod(Method m, ExecutableMode mode)` | 登记单个方法 |
| `registerAllDeclaredMethod(Class<?> clazz, ExecutableMode mode)` | 登记类上所有声明方法 |
| `registerDefaultConstructor(Class<?> clazz)` | 登记默认构造（不存在则不登记） |
| `registerDefaultConstructor(String className)` | 同上（按类名字符串） |

#### 2.2 资源登记

| 方法 | 说明 |
| --- | --- |
| `registerResourceInclude(String pattern)` | 登记包含的资源（正则表达式） |
| `registerResourceInclude(String pattern, String reachableType)` | 同上（带条件类） |
| `registerResourceExclude(String pattern)` | 登记排除的资源 |
| `registerResourceExclude(String pattern, String reachableType)` | 同上（带条件类） |

#### 2.3 序列化与代理登记

| 方法 | 说明 |
| --- | --- |
| `registerSerialization(Class<?> type)` | 登记 Java 序列化类 |
| `registerSerialization(String name)` | 同上（按全类名） |
| `registerSerialization(Package basePackage)` | 登记整个包下所有类（会扫描类文件） |
| `registerSerialization(Class<?> type, String reachableType)` | 带条件类 |
| `registerLambdaSerialization(Class<?> type)` | 登记 lambda 序列化（对应 lambdaCapturingTypes） |
| `registerJdkProxy(Class<?> type)` | 登记 JDK 代理接口（写入 proxy-config.json） |
| `registerJdkProxy(Class<?> type, String reachableType)` | 同上（带条件类） |

#### 2.4 其它

| 方法 | 说明 |
| --- | --- |
| `registerArg(String... args)` | 追加 native-image 构建参数（写入 native-image.properties） |
| `setApplicationClassName(String)` | 设置应用主类（一般不用手动设置） |

### 3、MemberCategory（成员类别，共 12 个）

| 类别 | 生成的配置 | 含义 |
| --- | --- | --- |
| `PUBLIC_FIELDS` | `allPublicFields` | 公有字段（含继承的） |
| `DECLARED_FIELDS` | `allDeclaredFields` | 声明的字段（不含继承的） |
| `INTROSPECT_PUBLIC_CONSTRUCTORS` | `queryAllPublicConstructors` | 公有构造器可查询（不可调用） |
| `INTROSPECT_DECLARED_CONSTRUCTORS` | `queryAllDeclaredConstructors` | 声明构造器可查询 |
| `INVOKE_PUBLIC_CONSTRUCTORS` | `allPublicConstructors` | 公有构造器可调用 |
| `INVOKE_DECLARED_CONSTRUCTORS` | `allDeclaredConstructors` | 声明构造器可调用 |
| `INTROSPECT_PUBLIC_METHODS` | `queryAllPublicMethods` | 公有方法可查询（含继承的） |
| `INTROSPECT_DECLARED_METHODS` | `queryAllDeclaredMethods` | 声明方法可查询 |
| `INVOKE_PUBLIC_METHODS` | `allPublicMethods` | 公有方法可调用（含继承的） |
| `INVOKE_DECLARED_METHODS` | `allDeclaredMethods` | 声明方法可调用 |
| `PUBLIC_CLASSES` | `allPublicClasses` | 公有内部类可用（`getClasses()`） |
| `DECLARED_CLASSES` | `allDeclaredClasses` | 声明内部类可用（`getDeclaredClasses()`） |

> 区别：**INTROSPECT（查询）** 只是能拿到元信息；**INVOKE（调用）** 是能真正执行反射调用。只读反射用 INTROSPECT 即可，别滥用 INVOKE（会增大镜像体积）。

### 4、ExecutableMode（执行模式）

| 枚举 | 生成的配置 | 含义 |
| --- | --- | --- |
| `INTROSPECT` | `queriedMethods` / 查询类 | 只查询元信息，不调用 |
| `INVOKE` | `methods` / 调用类 | 可反射调用 |

### 5、reachableType（条件登记）

`registerReflection` / `registerResourceInclude` / `registerSerialization` / `registerJdkProxy` 均支持 `reachableType`（条件类）。只有该类可达时，登记才生效，对应生成 `condition.typeReachable`：

```java
metadata.registerReflection("com.example.OnlyOnFoo",
        MemberCategory.INVOKE_DECLARED_CONSTRUCTORS);
// 带条件：
metadata.registerResourceInclude("special/.*", "com.example.MyStarter");
```

> 作用：按需裁剪元数据，缩小 native 镜像体积；一般用户用不上，第三方面向多场景的 starter 会用到。

### 6、完整示例（nginxWebUI 改造片段）

```java
@Component
public class RuntimeNativeRegistrarImpl implements RuntimeNativeRegistrar {
    @Override
    public void register(AppContext context, RuntimeNativeMetadata metadata) {
        // 资源
        metadata.registerResourceInclude("acme.zip");
        metadata.registerResourceInclude("nginx.conf");
        metadata.registerResourceInclude("messages_en_US.properties");

        // 序列化
        metadata.registerSerialization(JsonResult.class);
        metadata.registerSerialization(Server.class.getPackage());

        // 反射
        metadata.registerReflection(ProviderFactory.class, MemberCategory.INVOKE_DECLARED_METHODS);
        metadata.registerReflection(BufferedImage.class,
                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
                MemberCategory.INVOKE_DECLARED_METHODS);
    }
}
```