native RuntimeNativeRegistrar API 参考

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

1、接口定义

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

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

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

2、RuntimeNativeMetadata 方法一览

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

2.1 反射登记

2.2 资源登记

2.3 序列化与代理登记

2.4 其它

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

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

4、ExecutableMode（执行模式）

5、reachableType（条件登记）

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

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

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

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

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