Function 与 API 基础模块

Rain 最底层发布两个工具模块：function 提供框架内部共用的 JVM/Kotlin/ASM 工具，api 提供不依赖具体实现的 DI、Event 和 Loader 接口。

依赖选择

implementation("com.IceCreamQAQ.Rain:api:1.0.0-DEV12")

implementation 'com.IceCreamQAQ.Rain:api:1.0.0-DEV12'

api 已依赖 function。只编写框架扩展协议、不希望引入完整 Application 时可以依赖 api。普通 Rain 应用通常直接依赖 application，不必重复声明。

API 模块

DiContext

稳定的最小容器操作：

context.getBean(Service::class.java)
context.getBean(Service::class.java, "named")
context.putBean(Service::class.java, instance)
context.newBean(Service::class.java)
context.injectBean(existing)
context.registerClass(Service::class.java)

context.getBean(Service.class);
context.getBean(Service.class, "named");
context.putBean(Service.class, instance);
context.newBean(Service.class);
context.injectBean(existing);
context.registerClass(Service.class);

api 只定义协议；实际实现位于 di 模块。扩展模块构造器优先依赖 DiContext，不要依赖 ContextImpl，除非确实需要注册 ClassContext 等内部能力。

Loader API

• Loader：启动扫描扩展。
• LoadItem：被扫描类、触发 target 和注解实例。
• ApplicationService：启动/停止资源。
• @LoadBy：把类型或注解关联到 Loader。
• @AutoBind：声明自动实现绑定接口。

完整用法见 Application。

Event API

Event 是标记接口，EventBus 只有同步 post(event): Boolean。具体监听器和取消事件位于 event 模块。

把 Event/EventBus 放在 api，使业务模块可以发布事件而不直接依赖 EventBusImpl。

IUser

interface IUser {
    fun checkPermission(permission: String): Boolean
}

它是最小权限用户协议。SmartWeb 可通过 WebUserProvider 写入 ActionContext。复杂 RBAC/ABAC 应在应用层定义更丰富用户类型和 ProcessProvider。

InstanceProvider

InstanceProvider 当前是空类，没有可使用协议。不要把类名视为已完成的 Provider API。

Function 模块

Function 主要服务框架实现，公开可见不等于长期稳定。常见类别如下。

反射工具

clazz.allField
clazz.allMethod
method.nameAtParams
method.nameWithParamsFullClass
element.annotation<MyAnnotation>()

ReflectKt.getAllField(clazz);
ReflectKt.getAllMethod(clazz);
ReflectKt.getNameAtParams(method);
ReflectKt.getNameWithParamsFullClass(method);
element.getAnnotation(MyAnnotation.class);

Controller、Event、DI 用它统一遍历继承成员和生成方法签名。业务代码可使用，但应注意它们的继承/去重规则可能随框架演进。

RelType

RelType<T> 把 Java Type 转成“真实 Class + 泛型参数”结构，供配置、集合注入和 Access 泛型解析：

val type = RelType.create(method.genericReturnType)
val raw = type.realClass
val firstGeneric = type.generics?.firstOrNull()

RelType<?> type = RelType.Companion.create(method.getGenericReturnType());
Class<?> raw = type.getRealClass();
RelType<?> firstGeneric = type.getGenerics() == null
    ? null
    : type.getGenerics()[0];

它不是完整 Kotlin type system，复杂通配符、类型变量和嵌套泛型应写专项测试。

DataNode

• ObjectNode：字符串 key 到 DataNode。
• ArrayNode：节点列表。
• StringNode：标量文本。
• asObject/asArray/asMap：转换目标 RelType。

ConfigImpl 把 Properties/YAML/JSON 统一合并到 DataNode 树。部分节点写入/转换方法仍有 TODO，因此它更适合作为配置内部表示，不建议当通用 JSON DOM 使用。

时间工具

currentTimeMillis
currentTimeSecondsL
"5s".toTime()
DateUtil.formatDateTime()

TimeKt.getCurrentTimeMillis();
TimeKt.getCurrentTimeSecondsL();
StringKt.toTime("5s");
DateUtil.INSTANCE.formatDateTime();

JobBuilder 使用 toTime() 解析间隔。时间常量基于系统时钟，不提供 Clock 注入；对可测试业务时间应自行抽象 Clock。

线程与协程

coreNumThreadPool("worker")
coreNum2ThreadPool("worker")
coreNumCoroutineScope("worker")

ThreadKt.coreNumThreadPool("worker");
ThreadKt.coreNum2ThreadPool("worker");
ThreadKt.coreNumCoroutineScope("worker");

这些是便捷工厂，调用方必须管理 close/cancel。JobCenter 展示了作为 ApplicationService 统一释放的方式。

ASM 工具

Function 提供 descriptor、primitive cast、栈宽、参数读取等 ASM helper，供 Hook、EventInvoker、AccessMaker 使用。

只有编写字节码扩展时才应直接依赖。ASM 的 descriptor 和栈错误会在类加载时报 VerifyError，必须用真实加载测试验证。

IO、文件、JSON 与字符串

模块还包含 classpath 文件读取、目录创建、FastJSON2 辅助、首字母大小写、cast 和 SLF4J logger 获取等函数。它们是 Rain 内部便利层，不应替代成熟的应用级 IO/序列化抽象。

稳定性边界

推荐下游直接使用：

• DiContext
• Loader / LoadItem
• ApplicationService
• Event / EventBus
• @AutoBind / @LoadBy
• IUser

谨慎直接使用：

• rain.function 反射和 DataNode 实现。
• ASM helper。
• 具体错误类型和内部命名函数。

Rain 的简单实现让这些工具源码很容易阅读，但没有严格模块封装也意味着内部 helper 可能被误当稳定 API。扩展模块应尽量围绕 api 接口编程。