Rain 核心模块

Rain 核心不只包含 Application。应用最常直接使用的三大能力是：

• DI 与配置：创建和组装应用对象，读取配置。
• Event 事件总线：在同一进程中发布事实并解耦监听器。
• Job 任务调度：注册周期任务和动态任务。

它们都接入 Application 的扫描和生命周期，但职责不同：

Application
├─ DI：谁创建对象、怎样注入依赖与配置
├─ Event：一个事实发生后，谁需要同步响应
└─ Job：一个任务应在什么时间被调用

模块选择

需求	使用模块	核心入口
构造服务并注入依赖	DI	构造器、@Inject、DiContext
注入配置值	DI	@Config、ConfigManager
同一接口选择不同实现	DI	@AutoBind、@Named
发布领域或生命周期事件	Event	EventBus.post
自动发现事件监听器	Event	@EventListener、@SubscribeEvent
声明固定间隔任务	Job	@CronTab、@Cron
运行时创建和取消任务	Job	JobBuilder、JobManager

添加依赖

最常见的应用直接引入 Application 和需要的业务模块：

dependencies {
    implementation("com.IceCreamQAQ.Rain:application:1.0.0-DEV12")
    implementation("com.IceCreamQAQ.Rain:event:1.0.0-DEV12")
    implementation("com.IceCreamQAQ.Rain:job:1.0.0-DEV12")
}

dependencies {
    implementation 'com.IceCreamQAQ.Rain:application:1.0.0-DEV12'
    implementation 'com.IceCreamQAQ.Rain:event:1.0.0-DEV12'
    implementation 'com.IceCreamQAQ.Rain:job:1.0.0-DEV12'
}

Application 已组合 DI、配置、类加载和 Hook。Event 与 Job 按需添加，不需要事件或任务时可以不引入。

DI：组装对象

Rain 会扫描应用包中的具体类，并按构造器参数递归创建依赖：

class OrderRepository

class OrderService(
    private val repository: OrderRepository,
    @Config("order.maxItems") private val maxItems: Int,
)

public final class OrderRepository {
}

public final class OrderService {
    private final OrderRepository repository;
    private final int maxItems;

    public OrderService(
        OrderRepository repository,
        @Config("order.maxItems") int maxItems
    ) {
        this.repository = repository;
        this.maxItems = maxItems;
    }
}

order.maxItems=100

这里没有 @Component：具体类只要在 rain.scanPackages 中且构造条件满足，就可以由容器创建。命名实例、集合注入、BeanFactory 和底层创建规则见 DI 与配置。

Event：发布事实

定义事件、声明监听器，再从业务服务发布：

data class OrderCreated(val orderId: Long) : Event

@EventListener
class OrderListener {
    @SubscribeEvent
    fun onCreated(event: OrderCreated) {
        println("created: ${event.orderId}")
    }
}

class OrderService(
    private val eventBus: EventBus,
) {
    fun create(orderId: Long) {
        eventBus.post(OrderCreated(orderId))
    }
}

public final class OrderCreated implements Event {
    public final long orderId;

    public OrderCreated(long orderId) {
        this.orderId = orderId;
    }
}

@EventListener
public final class OrderListener {
    @SubscribeEvent
    public void onCreated(OrderCreated event) {
        System.out.println("created: " + event.orderId);
    }
}

public final class OrderService {
    private final EventBus eventBus;

    public OrderService(EventBus eventBus) {
        this.eventBus = eventBus;
    }

    public void create(long orderId) {
        eventBus.post(new OrderCreated(orderId));
    }
}

EventBus 是同步、进程内分发。发布线程会执行监听器；它不是消息队列。权重、取消、异常和编程式注册见 Event 事件总线。

Job：按时间调用

给可注入的类标记 @CronTab，给无参数方法标记 @Cron：

@CronTab
class CleanupJobs(
    private val cleanupService: CleanupService,
) {
    @Cron("10m")
    fun cleanup() {
        cleanupService.removeExpired()
    }
}

@CronTab
public final class CleanupJobs {
    private final CleanupService cleanupService;

    public CleanupJobs(CleanupService cleanupService) {
        this.cleanupService = cleanupService;
    }

    @Cron("10m")
    public void cleanup() {
        cleanupService.removeExpired();
    }
}

当前 @Cron 的字符串表示 Rain 时间间隔，不是标准 Cron 表达式。动态注册、取消、并发和异常事件见 Job 任务调度。

三个模块如何协作

一个常见业务链是：DI 创建服务，Job 定时调用服务，服务发布 Event：

JobLoader 扫描 @CronTab
  ↓
DI 创建 CleanupJobs 与 CleanupService
  ↓
JobCenter 到时调用 cleanup()
  ↓
CleanupService 完成清理并 EventBus.post
  ↓
EventBus 同步调用匹配监听器

三者都依赖正确的扫描包。最小应用配置：

rain.scanPackages=com.example.app

推荐阅读顺序

1. DI 与配置：先理解对象如何创建，后两个模块都依赖它。
2. Event 事件总线：理解 Loader 如何发现监听器并建立运行时注册。
3. Job 任务调度：理解注解任务、动态 DSL 和 ApplicationService 生命周期。
4. Application：从框架实现角度追踪三者如何接入统一启动链。

如果目标是开发新的 Rain 模块，而不是只使用现有能力，请继续阅读扩展点总览。