Lazberry Registry Framework (LRF)
一款轻量级、高性能的依赖注入(DI)和反转控制(IoC)框架,专为 Spigot / Paper MC 服务器插件设计。
? 概述
Lazberry Registry Framework (LRF) 通过提供一套现代化的、类似 Spring 的声明式生态系统,简化了 Minecraft 插件的开发,该生态系统专为高并发的 Bukkit 环境量身定制。
通过使用简洁的 Java 注解自动管理依赖图、命令映射、事件监听器绑定以及异步任务,LRF 彻底消除了你在 onEnable() 生命周期中所需的样板初始化代码。
安装指南 
Gradle
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
dependencies {
implementation 'com.github.lazberry89:LazberryRegistryFramework:v1.0.1'
annotationProcessor 'com.github.lazberry89:LazberryRegistryFramework:v1.0.1'
}
gradle.kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
dependencies {
implementation("com.github.lazberry89:LazberryRegistryFramework:v1.0.1")
annotationProcessor("com.github.lazberry89:LazberryRegistryFramework:v1.0.1")
}
maven
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.lazberry89</groupId>
<artifactId>LazberryRegistryFramework</artifactId>
<version>v1.0.1</version>
</dependency>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
<configuration>
<source>21</source>
<target>21</target>
<annotationProcessorPaths>
<path>
<groupId>com.github.lazberry89</groupId>
<artifactId>LazberryRegistryFramework</artifactId>
<version>v1.0.1</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
Lazberry Registry Framework 快速入门指南
1. 框架规则
本框架遵循 CORS 原则。
| 键 |
原则 |
描述 |
C |
具体类优先 (Concrete) |
LRF 仅管理具体类和实例。除非标记为声明性模型,否则在 IoC 处理过程中严格忽略 interface 或 abstract class 等抽象实体。 |
O |
OOP 不变量 (OOP Invariant) |
严格执行面向对象编程原则。关键的生命周期句柄通过最终封装锁定,以保留领域完整性和对象边界。 |
R |
运行时安全 (Runtime-Safety) |
在启动阶段强制执行快速失败机制。尽早捕获依赖循环、配置不匹配和平台不兼容问题,以防止运行时服务器崩溃。 |
S |
结构隔离 (Structural Isolation) |
使用 @Virtual 和 @ConsumableClass 将运行时单例与模板类和代理隔离开来,防止内存污染和垃圾回收瓶颈。 |
2. 根域注解
| 注解 |
目标 |
描述 |
@Component |
Class |
将目标类注册为 IoC Bean。支持内部注解 (@Include, @Exclude),以根据 ServerType 控制特定平台的扫描规则。 |
@Inject |
Constructor |
IoC 依赖解析的主要构造函数句柄。在初始化时自动将所需的依赖项注入到目标组件中。 |
@ConsumableClass |
Class |
标记可重用的模板结构或 DTO(数据传输对象),明确将其从默认的单例 IoC Bean 实例化中排除。 |
@Virtual |
Class |
应用于接口、抽象蓝图或基础模板,以跳过自动 IoC 扫描并强制执行仅针对具体类的绑定机制。 |
@Conditional |
Class |
通过 ConditionalRegistry 评估运行时条件,动态地将目标组件包含或排除在 IoC 容器之外。 |
@Async |
Method |
标记将在后台线程上异步执行的方法,将计算密集型任务与主执行循环隔离。 |
@Sync |
Method |
强制在主服务器刻线程边界内进行同步执行。 |
@Transactional |
Method |
将执行块包装在事务边界内,以保证原子状态更改和安全回滚能力。 |
@Document |
Class / Field |
将结构元数据和文档标签附加到运行时组件上,供内部框架自省使用。 |
@SelfDestruct |
Class / Method |
指定动态资源或临时处理器,以便在清理周期期间注销并清除内存。 |
3. 引擎与平台注解
| 注解 |
目标 |
描述 |
@Commands |
Class |
将命令映射处理器直接注册到底层 Paper/Spigot 命令执行框架中。 |
@Listeners |
Class |
在容器初始化期间,自动将 Bukkit 事件监听器方法注册到活跃的 PluginManager 中。 |
@ConfigObject |
Class / Record |
将 YAML 配置节直接绑定到不可变的 Java Record 或 POJO,并将映射后的对象自动注册到 IoC 容器中。 |
@ConfigValue |
Parameter |
从目标 YAML 文件中提取原始值或结构化值,直接注入到构造函数参数或字段中。 |
@GracefulShutdown |
Method / Class |
注册高优先级的清理任务,在服务器卸载前转储内存缓存、刷新网络缓冲区并保存状态。 |
@Schedule |
Method |
将方法执行循环绑定到具有可配置延迟/周期限制的同步或异步 Bukkit 调度器通道上。 |
@Task |
Class |
声明由框架执行池管理的后台工作线程任务或计划作业。 |
@InboundChannel |
Class |
绑定传入的代理/服务器插件消息通道,用于跨服务器网络通信。 |
@OutboundChannel |
Class |
绑定传出的代理/服务器插件消息通道以分发网络数据包。 |
@Monitor |
Method / Class |
附加遥测仪器以测量执行延迟、微秒级尖峰和性能指标。 |
@Reflection |
Method |
通过优化的反射句柄绕过标准访问控制,用于高性能的底层字段/方法操作。 |
4. 框架中的 DI 自动化
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.repository.UserRepository;
import com.lazberry.myplugin.config.PluginConfig;
@Component
public class UserService {
private final UserRepository userRepository;
private final PluginConfig pluginConfig;
@Inject
public UserService(UserRepository userRepository, PluginConfig pluginConfig) {
this.userRepository = userRepository;
this.pluginConfig = pluginConfig;
}
public void processUserData(String uuid) {
if (pluginConfig.isLoggingEnabled()) {
userRepository.findUser(uuid);
}
}
}
-
作用:
- 告知 LRF IoC 容器将
UserService 管理为单例 Bean。
@Inject 指示框架在启动时自动解析并提供所需的依赖项(UserRepository、PluginConfig)到构造函数中。
-
约束条件:
- 单构造函数约束: 如果存在多个构造函数,必须显式地在预期的构造函数上放置
@Inject。
- 依赖要求:
@Inject 构造函数内的所有参数类型也必须注册为有效的 IoC 组件、@ConfigObject Bean 或框架实例。
- 类规则: 目标类不能是
interface(接口)或 abstract class(抽象类)。跳过虚拟类 IoC 扫描的注解是 @Virtual 和 @ConsumableClass。
5. 配置对象映射示例
package com.lazberry.myplugin.config;
import Framework.LazberryRegistryFramework.Annotation.ConfigObject;
import Framework.LazberryRegistryFramework.Annotation.ConfigValue;
// 自动将 config.yml 中的 'database' 部分绑定到此不可变 Record
@ConfigObject(path = "database")
public record DatabaseConfig(
@ConfigValue(path = "host") String host,
@ConfigValue(path = "port") int port,
@ConfigValue(path = "username") String username,
@ConfigValue(path = "password") String password,
@ConfigValue(path = "max-pool-size") int maxPoolSize
) {}
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.config.DatabaseConfig;
@Component
public class DatabaseService {
private final DatabaseConfig dbConfig;
@Inject
public DatabaseService(DatabaseConfig dbConfig) {
this.dbConfig = dbConfig; // 作为类型安全的 IoC Bean 自动注入
}
public void connect() {
String url = "jdbc:mysql://" + dbConfig.host() + ":" + dbConfig.port();
System.out.println("Connecting to database: " + url);
}
}
-
作用:
- 直接将 YAML 配置路径绑定到类型安全的 Java
record 或 POJO,无需手动文件解析逻辑。
- 自动将映射后的对象注册到 IoC 容器中,以便通过
@Inject 在任何地方进行注入。
-
约束条件:
- 路径准确性:
@ConfigObject 中的 path 属性必须与 config.yml 中的确切节键匹配。
- 不可变性: 建议与 Java
record 一起使用,以确保类型安全和不可变性。
- 回退/默认值: YAML 文件中缺失的键必须定义默认回退值或使用可空类型。
6. 命令与监听器自动注册示例
package com.lazberry.myplugin.listener;
import Framework.LazberryRegistryFramework.Annotation.Listeners;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.service.UserService;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
// 启动时自动注册到 Bukkit 的 PluginManager
@Listeners
public class PlayerJoinListener implements Listener {
private final UserService userService;
@Inject
public PlayerJoinListener(UserService userService) {
this.userService = userService; // 无缝地将依赖项注入到监听器中
}
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
userService.processUserData(event.getPlayer().getUniqueId().toString());
}
}
package com.lazberry.myplugin.command;
```java
import Framework.LazberryRegistryFramework.Annotation.Commands;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.service.UserService;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
// 自动注入到 Paper/Spigot 命令映射中
@Commands(command = "userinfo")
public class UserInfoCommand implements CommandExecutor {
private final UserService userService;
@Inject
public UserInfoCommand(UserService userService) {
this.userService = userService;
}
@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
if (sender instanceof Player player && args.length > 0) {
userService.processUserData(args[0]);
player.sendMessage("§a用户数据处理成功!");
return true;
}
return false;
}
}
工作原理与约束条件
-
角色:
@Listeners:无需在 onEnable() 内部调用 getServer().getPluginManager().registerEvents(...)。框架会自动扫描并注册监听器 Bean。
@Commands:使用指定的命令名称,将目标 CommandExecutor 直接自动注册到服务器命令映射中。
-
约束条件:
- 接口要求:
@Listeners 的目标类必须实现 Bukkit 的 Listener 接口。
plugin.yml 注册: 使用 @Commands 声明的命令仍必须在 plugin.yml 的 commands: 部分进行定义(除非使用动态命令映射桥接)。
- 单例生命周期: 监听器和命令均被视为单例组件,并通过
@Inject 支持完整的依赖注入。
7. 调度与异步执行示例
package com.lazberry.myplugin.task;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import Framework.Annotation.Async;
import Framework.LazberryRegistryFramework.Annotation.Schedule;
import com.lazberry.myplugin.service.UserService;
@Component
public class CacheCleanupTask {
private final UserService userService;
@Inject
public CacheCleanupTask(UserService userService) {
this.userService = userService;
}
// 在初始延迟 10 秒(200 tick)后,每 5 分钟(6000 tick)异步运行一次
@Schedule(delay = 200, period = 6000, async = true)
public void runPeriodicCachePurge() {
System.out.println("[LRF] 开始自动后台缓存清理...");
// 这里的重型操作不会阻塞主服务器线程
}
// 按需调用的简单异步方法执行
@Async
public void processHeavyDataLog(String logData) {
// 立即在后台线程池上运行
System.out.println("[LRF Async Worker] 记录用户活动: " + logData);
}
}
工作原理与约束条件
-
角色:
@Schedule:利用 Bukkit 调度器自动注册并触发方法执行循环,无需手动调用 runTaskTimer()。
@Async:将方法执行直接卸载到后台线程池,以防止在计算密集型或 I/O 操作期间出现主线程卡顿。
-
约束条件:
- 线程安全: 标注了
@Async 或 @Schedule(async = true) 的方法不得直接调用需要主线程执行的 Bukkit API 方法(例如直接修改实体或方块)。
- 组件绑定: 目标方法必须属于有效的 IoC 管理 Bean(例如,标注为
@Component)。
- 无参调度: 调度方法(
@Schedule)通常不应有参数要求,以便框架工作器能够自动调用它们。
8. 条件组件注册 (@Conditional)
您可以根据运行时环境、功能开关或服务器配置,动态地将组件包含或排除在 IoC 容器之外。
步骤 1:实现条件评估器
package com.lazberry.myplugin.condition;
import Framework.LazberryRegistryFramework.ConditionalRegistry;
// 1. 定义您的自定义运行时条件评估器
public final class DevEnvironmentCondition implements ConditionalRegistry {
@Override
public boolean matches() {
// 仅当在开发服务器环境中运行时返回 true
return System.getProperty("server.env", "prod").equalsIgnoreCase("dev");
}
}
步骤 2:将 @Conditional 应用于组件
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Conditional;
import com.lazberry.myplugin.condition.DevEnvironmentCondition;
// 2. 仅当 DevEnvironmentCondition#matches() 返回 true 时,才实例化该组件
@Component
@Conditional(DevEnvironmentCondition.class)
public class DebugLoggerService {
public DebugLoggerService() {
System.out.println("[LRF Debugger] 检测到开发环境。正在初始化 DebugLoggerService...");
}
public void logDebugInfo(String message) {
System.out.println("[DEBUG] " + message);
}
}
工作原理与约束条件
-
角色:
- 零开销过滤: LRF 扫描器在实例化目标组件之前会评估
matches()。如果返回 false,则该组件将从编译队列中完全丢弃——不产生任何内存开销。
- 解耦架构: 消除了初始化方法内部的硬编码
if/else 检查,使组件在不同服务器环境(例如大厅服 vs 小游戏服)之间保持干净和模块化。
-
约束条件:
- 必须包含默认构造函数: 实现
ConditionalRegistry 的评估器类必须拥有一个可访问的无参默认构造函数,以便框架在扫描阶段通过反射实例化它。
- 仅适用于类级别:
@Conditional 只能应用于类级别的声明(ElementType.TYPE)。
9. 外部与第三方实例注册
步骤 1:预注册外部句柄(引导初始化)
package com.lazberry.myplugin;
import Framework.LazberryRegistryFramework.DependencyContainer;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.File;
public class MyPluginBootstrap {
public static void initializeContainer(JavaPlugin plugin) {
// 将原生 Bukkit 上下文句柄预注册到主 IoC 容器中
DependencyContainer.registerInstance(JavaPlugin.class, plugin);
DependencyContainer.registerInstance(File.class, plugin.getDataFolder());
// 示例:手动注册第三方库实例
// DependencyContainer.registerInstance(JedisPool.class, new JedisPool("localhost", 6379));
}
}
步骤 2:在任何位置注入已注册的句柄
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.File;
@Component
public class StorageService {
private final JavaPlugin plugin;
private final File dataFolder;
@Inject
public StorageService(JavaPlugin plugin, File dataFolder) {
// 从预注册的外部句柄中自动注入
this.plugin = plugin;
this.dataFolder = dataFolder;
}
public void printPluginInfo() {
plugin.getLogger().info("Data folder path: " + dataFolder.getAbsolutePath());
}
}
工作原理与约束条件
-
作用:
- 早期上下文插入: 允许非托管的外部实例(如 Paper/Spigot 句柄、数据库连接池或外部 API 客户端)通过
@Inject 在整个 IoC 依赖图中可用。
- 多态查找:
getBean(Class) 通过类型可分配性检查安全地检索已注册的实例,无需手动显式强制转换。
-
约束条件:
- 引导时机: 必须在调用
PackageScanner.buildAndInjectBeans() 之前使用 registerInstance() 注册外部实例,以确保在构造函数解析期间依赖项可用。
- 键覆盖: 使用相同的类键注册另一个实例将覆盖底层容器映射中的前一项。
技术架构与实现规范 (Rev. 2026.1)
1. 架构理念与动机
Lazberry Registry Framework (LRF) 是一个企业级、高性能的反转控制 (IoC) 和依赖注入 (DI) 引擎,专为高度分布式、多代理 Minecraft 服务器拓扑结构而设计。传统的应用程序框架(如 Spring 或 Guice)引入了大量的运行时反射开销、巨大的内存占用,并且缺乏对游戏循环动态、刻率约束以及服务器-代理网络布局的原生理解。
LRF 通过确定性架构不变量解决了这些领域特定的挑战:
- 具体执行(反虚拟不变量):框架完全禁止模糊的 IoC 状态映射。接口和抽象蓝图被严格隔离为声明式模型 (
@Virtual),强制明确的具象实现绑定,以保障可预测的内存布局和零运行时查找歧义。
- 通过封装锁保留 OOP 不变量:原生 Bukkit 生命周期钩子 (
onEnable, onDisable) 在主类级别被声明为 final。这强制执行安全、对称的拆卸/启动机制,防止用户代码绕过 IoC 容器组装或优雅关闭队列。
- 激进的中止失败运行时安全性:与其允许隐藏错误或延迟初始化的故障在游戏中途显现(可能导致刻循环崩溃或损坏玩家数据),LRF 在启动时执行自顶向下的拓扑图验证和配置映射。任何结构故障都会立即中止引导序列。
2. 主引导程序与子类规范 (JavaPlugin 封装)
为了消除样板设置代码并强制执行严格的生命周期封装,主插件入口点必须直接扩展 LazberryRegistryFramework,而不是原始的 Bukkit JavaPlugin。
[Server Boot]
│
▼
┌────────────────────────────────────────────────────────┐
│ LazberryRegistryFramework.onEnable() [LOCKED final] │
├────────────────────────────────────────────────────────┤
│ 1. 上下文分配与包边界发现 │
│ 2. ClassPath 扫描与配置映射 (@ConfigObject) │
│ 3. IoC 图解析与 ByteBuddy 代理组装 │
│ 4. 调度器与事件绑定 │
│ 5. 开发者钩子分发 ─────────────────────────────────────┼──► onLrfEnable()
└────────────────────────────────────────────────────────┘
2.1. 不可侵犯的生命周期锁 (final 执行)
LazberryRegistryFramework 锁定原生 Bukkit 入口点以防止生命周期碎片化:
@Override
public final void onEnable() {
boot(this, getClass());
onLrfEnable();
}
@Override
public final void onDisable() {
try {
onLrfDisable();
} finally {
ScheduleProcessor.cancelAllSchedules();
ShutdownRegistry.executeShutdownSequence();
cleanUp(this, getClass());
}
}
2.2. 用户实现指南(具象主类)
开发人员通过受保护的生命周期钩子实现用户级的设置和拆卸逻辑:
package com.lazberry.myplugin;
```java
import Framework.LazberryRegistryFramework.LazberryRegistryFramework;
import lombok.extern.slf4j.Slf4j;
@Slf4j
public final class MyPluginMain extends LazberryRegistryFramework {
@Override
protected void onLrfEnable() {
// 在 LRF IoC 容器和代理初始化之后立即调用
log.info("MyPlugin successfully booted on LRF Core!");
}
@Override
protected void onLrfDisable() {
// 在任务取消和 IoC 容器销毁之前立即调用
log.info("MyPlugin initiating safe shutdown sequence...");
}
}
- 隐式包拓扑发现:调用
boot(this, getClass()) 会自动拦截 mainClass.getPackageName()。这建立了隐式的反射扫描边界,无需硬编码的包名字符串参数。
3. 全局组件矩阵与包结构
3.1. 根域配置 (Framework)
Framework.Annotation:控制组件边界的结构性标记(@Component.Include、@Conditional)、实例化选择(@Inject)、模板分类(@ConsumableClass、@Virtual)以及运行时语义声明(@Document、@Transactional)。
Framework.FrameworkExceptions:终止性边界违规异常,当结构不变量被违反时中止引导过程。
Framework.Utils:低级、高吞吐量的基础工具类(ParseEnum、ColorUtils、IDGenerator)。
- 生命周期与拓扑抽象:上下文环境标记(
Local、Global),在扫描之前注册到 ServerType 中。
3.2. 引擎核心 (Framework.LazberryRegistryFramework)
Framework.LazberryRegistryFramework.Annotation:Spigot/Paper 特定的钩子(@Commands、@Listeners、@Schedule、@ConfigObject、@GracefulShutdown、@InboundChannel、@OutboundChannel)。
Framework.LazberryRegistryFramework.Monitoring:微秒级精度的遥测子系统(PerformanceRegistry、MetricData)。
- 核心编排引擎:类路径遍历(
PackageScanner)、反射缓存(Reflections)、依赖图组装(DependencyContainer)、类型安全的配置映射(ConfigObjectMapper)、AOP 代理生成(LrfProxyFactory)以及网络消息路由(PluginMessageRouter)。
4. 组件扫描、O/R 映射与管道过滤器
PackageScanner 管道执行多阶段过滤以隔离运行时组件。
[类路径遍历] ──► [接口/抽象检查]
│
▼
[可消费/虚拟过滤器]
│
▼
[服务器兼容性检查]
│
├─────────────────────────┐
▼ ▼
[@ConfigObject 映射] [组件收集]
│ │
▼ ▼
[直接 IoC 注册] [条件验证]
│
▼
[目标组装列表]
4.1. 配置 O/R 映射 (@ConfigObject)
为了消除原始的 FileConfiguration.get() 调用并保证类型安全,LRF 提供了一个零样板代码的 YAML 到 POJO/Record 的映射引擎(ConfigObjectMapper)。
- Record 支持:支持不可变的 Java Record(Java 16+)和标准 POJO。
- 实例化阶段:在构造函数注入之前的扫描期间执行,将映射的配置实例注册到
DependencyContainer 中。
@ConfigObject(path = "database", file = "config.yml")
public record DatabaseConfig(
String host,
int port,
String username,
String password,
int maxPoolSize
) {}
4.2. 虚拟蓝图守卫 (@Virtual)
用于继承的抽象模板、模拟结构或基类使用 @Virtual 进行注解。PackageScanner 会立即丢弃这些目标,防止不完整的蓝图污染 IoC 容器。
5. IoC 装配线与拓扑图解析
DependencyContainer 管理事务性的、自上而下的装配线,以编译具体的应用程序组件。
5.1. 解析策略
- 缓存拦截:使用
Class.isAssignableFrom 扫描 BEAN_CONTAINER,以实现单地址内存契约表示。
- 严格抽象屏障:直接传入装配线的非具体类型会触发
VirtualClassInjectException。
- 循环锁解除:
CONSTRUCTION_STACK(LinkedHashSet)跟踪当前的构建链。如果在嵌套参数中检测到活跃的类型令牌,则立即抛出 CircularDependencyException。
5.2. 构造函数选择与参数注入
- 优先选择带有
@Inject 装饰的构造函数,回退到公共无参构造函数。
- 使用
@ConfigValue 注解的参数路由至 ConfigInjection.resolve()。
- 使用
@ConfigObject 或标准 @Component 模型注解的参数类通过 DependencyContainer.getOrCreateBean() 递归解析。
6. 防御性异常框架架构
| 异常类 |
根本原因触发条件 |
架构目的 |
VirtualClassInjectException |
尝试直接注入接口、抽象类或 @Virtual 标记。 |
确保只有具体的、可实例化的单例才能填充 IoC 上下文。 |
CircularDependencyException |
在活动的构造函数堆栈跟踪中检测到自引用循环。 |
防止线程冻结和无限递归导致的栈溢出崩溃。 |
NotCompatibleWithServerException |
组件的环境要求未通过当前平台检查。 |
防止因缺少 NMS 版本或无效服务器绑定而导致的类加载崩溃。 |
NotValidInitializeTimingException |
初始化钩子在当前容器阶段之外执行。 |
在多模块管理器之间强制执行严格的时序顺序。 |
InvalidConfigInjectException |
在值解析期间缺少配置节点或结构类型不匹配。 |
确保损坏或不完整的文件在运行时错误发生之前尽早失败。 |
7. 拆卸与资源清理管道
为了防止在热重载(/reload)期间 JVM 类加载器出现内存泄漏,LRF 强制实施反向的拆卸序列:
- 用户拆卸分发:执行开发者在
onLrfDisable() 中的逻辑。
- 任务冻结:
ScheduleProcessor.cancelAllSchedules() 系统地取消活动异步/同步任务循环。
- 优先关闭:标记为
@GracefulShutdown 的处理程序按优先级顺序执行,以转储内存缓存并持久化数据库状态。
- 静态容器清理:
cleanUp() 注销 ServerType 引用并清除静态容器映射,释放类加载器句柄以完成垃圾回收。
Lazberry Registry Framework (LRF)
A lightweight, high-performance Inversion of Control (IoC) and Dependency Injection (DI) framework designed specifically for Spigot / Paper MC server plugins.
? Overview
Lazberry Registry Framework (LRF) simplifies Minecraft plugin development by providing a modern Spring-like declarative ecosystem tailored for high-concurrency Bukkit environments.
By automating dependency graphs, command maps, event listener bindings, and asynchronous tasks using clean Java Annotations, LRF completely eliminates boilerplate initialization code in your onEnable() lifecycle.
Installation Guide 
Gradle
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
dependencies {
implementation 'com.github.lazberry89:LazberryRegistryFramework:v1.0.1'
annotationProcessor 'com.github.lazberry89:LazberryRegistryFramework:v1.0.1'
}
gradle.kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
dependencies {
implementation("com.github.lazberry89:LazberryRegistryFramework:v1.0.1")
annotationProcessor("com.github.lazberry89:LazberryRegistryFramework:v1.0.1")
}
maven
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.lazberry89</groupId>
<artifactId>LazberryRegistryFramework</artifactId>
<version>v1.0.1</version>
</dependency>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
<configuration>
<source>21</source>
<target>21</target>
<annotationProcessorPaths>
<path>
<groupId>com.github.lazberry89</groupId>
<artifactId>LazberryRegistryFramework</artifactId>
<version>v1.0.1</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
Quick Start Guide for Lazberry Registry Framework
1. Framework rules
This framework is governed by CORS rule.
| Key |
Principle |
Description |
C |
Concrete |
LRF only manages concrete classes and instances. Abstract entities like interface or abstract class are strictly dismissed during IoC processing unless marked as declarative models. |
O |
OOP Invariant |
Object-Oriented Programming principles are strictly enforced. Vital lifecycle handles are locked via final encapsulation to preserve domain integrity and object boundaries. |
R |
Runtime-Safety |
Enforces fail-fast mechanics during the boot phase. Dependency cycles, configuration mismatches, and platform incompatibilities are caught early to prevent runtime server crashes. |
S |
Structural Isolation |
Isolates runtime singletons from template classes and proxies using @Virtual and @ConsumableClass, preventing memory pollution and garbage collection bottlenecks. |
2. Root Domain Annotations
| Annotation |
Target |
Description |
@Component |
Class |
Registers target class as an IoC bean. Supports inner annotations (@Include, @Exclude) to control platform-specific scanning rules based on ServerType. |
@Inject |
Constructor |
Primary constructor handle for IoC dependency resolution. Automatically injects required dependencies into the target component upon initialization. |
@ConsumableClass |
Class |
Marks reusable template structures or DTOs (Data Transfer Objects) to explicitly exclude them from default singleton IoC bean instantiation. |
@Virtual |
Class |
Applied to interfaces, abstract blueprints, or base templates to skip automatic IoC scanning and enforce concrete-only binding mechanics. |
@Conditional |
Class |
Evaluates runtime conditions via ConditionalRegistry to dynamically include or exclude the target component from the IoC container. |
@Async |
Method |
Marks methods to be executed asynchronously on background threads, isolating compute-heavy tasks from primary execution loops. |
@Sync |
Method |
Enforces synchronous execution within the main server tick thread boundary. |
@Transactional |
Method |
Wraps execution blocks in transactional boundaries to guarantee atomic state changes and safe rollback capabilities. |
@Document |
Class / Field |
Attaches structural metadata and documentation tags to runtime components for internal framework introspection. |
@SelfDestruct |
Class / Method |
Designates dynamic resources or temporary handlers to be unregistered and memory-purged during cleanup cycles. |
3. Engine & Platform Annotations
| Annotation |
Target |
Description |
@Commands |
Class |
Registers command map handlers directly into the underlying Paper/Spigot command execution framework. |
@Listeners |
Class |
Automatically registers Bukkit event listener methods to the active PluginManager during container initialization. |
@ConfigObject |
Class / Record |
Binds a YAML configuration section directly to an immutable Java Record or POJO, auto-registering the mapped object into the IoC container. |
@ConfigValue |
Parameter |
Injects primitive or structured values extracted from target YAML files directly into constructor parameters or fields. |
@GracefulShutdown |
Method / Class |
Registers high-priority teardown tasks to dump memory caches, flush network buffers, and save state prior to server unload. |
@Schedule |
Method |
Binds method execution loops to synchronous or asynchronous Bukkit scheduler channels with configurable delay/period constraints. |
@Task |
Class |
Declares background worker tasks or scheduled jobs managed under the framework execution pool. |
@InboundChannel |
Class |
Binds incoming proxy/server plugin messaging channels for inter-server network communication. |
@OutboundChannel |
Class |
Binds outgoing proxy/server plugin messaging channels to dispatch network packets. |
@Monitor |
Method / Class |
Attaches telemetric instrumentation to measure execution latency, microsecond spikes, and performance metrics. |
@Reflection |
Method |
Bypasses standard access controls via optimized reflection handles for high-performance low-level field/method manipulation. |
4. Automation of DI in framework
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.repository.UserRepository;
import com.lazberry.myplugin.config.PluginConfig;
@Component
public class UserService {
private final UserRepository userRepository;
private final PluginConfig pluginConfig;
@Inject
public UserService(UserRepository userRepository, PluginConfig pluginConfig) {
this.userRepository = userRepository;
this.pluginConfig = pluginConfig;
}
public void processUserData(String uuid) {
if (pluginConfig.isLoggingEnabled()) {
userRepository.findUser(uuid);
}
}
}
-
Role:
- Tells the LRF IoC container to manage
UserService as a singleton bean.
@Inject instructs the framework to automatically resolve and supply required dependencies (UserRepository, PluginConfig) into the constructor at boot time.
-
Constraints:
- Single Constructor Constraint: If multiple constructors exist,
@Inject must be explicitly placed on the intended constructor.
- Dependency Requirement: All parameter types inside the
@Inject constructor must also be registered as valid IoC components, @ConfigObject beans, or framework instances.
- Class Rule: The target class must not be an
interface or abstract class. The annotation that skips IoC scanning on virtual classes is @Virtual and @ConsumableClass.
5. Configuration Object Mapping Example
package com.lazberry.myplugin.config;
import Framework.LazberryRegistryFramework.Annotation.ConfigObject;
import Framework.LazberryRegistryFramework.Annotation.ConfigValue;
// Automatically binds the 'database' section in config.yml to this immutable Record
@ConfigObject(path = "database")
public record DatabaseConfig(
@ConfigValue(path = "host") String host,
@ConfigValue(path = "port") int port,
@ConfigValue(path = "username") String username,
@ConfigValue(path = "password") String password,
@ConfigValue(path = "max-pool-size") int maxPoolSize
) {}
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.config.DatabaseConfig;
@Component
public class DatabaseService {
private final DatabaseConfig dbConfig;
@Inject
public DatabaseService(DatabaseConfig dbConfig) {
this.dbConfig = dbConfig; // Injected as a type-safe IoC bean automatically
}
public void connect() {
String url = "jdbc:mysql://" + dbConfig.host() + ":" + dbConfig.port();
System.out.println("Connecting to database: " + url);
}
}
-
Role:
- Binds a YAML configuration path directly to a type-safe Java
record or POJO without manual file-parsing logic.
- Auto-registers the mapped object into the IoC container so it can be injected anywhere via
@Inject.
-
Constraints:
- Path Accuracy: The
path attribute in @ConfigObject must match the exact section key in your config.yml.
- Immutability: Recommended to use with Java
record for type-safety and immutability.
- Fallback / Defaults: Keys missing in the YAML file must have default fallback values defined or nullable types.
6. Commands & Listeners Auto-Registration Example
package com.lazberry.myplugin.listener;
import Framework.LazberryRegistryFramework.Annotation.Listeners;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.service.UserService;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
// Automatically registered to Bukkit's PluginManager upon startup
@Listeners
public class PlayerJoinListener implements Listener {
private final UserService userService;
@Inject
public PlayerJoinListener(UserService userService) {
this.userService = userService; // Inject dependencies seamlessly into listeners
}
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
userService.processUserData(event.getPlayer().getUniqueId().toString());
}
}
package com.lazberry.myplugin.command;
import Framework.LazberryRegistryFramework.Annotation.Commands;
import Framework.Annotation.Inject;
import com.lazberry.myplugin.service.UserService;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
// Automatically injected into Paper/Spigot command map
@Commands(command = "userinfo")
public class UserInfoCommand implements CommandExecutor {
private final UserService userService;
@Inject
public UserInfoCommand(UserService userService) {
this.userService = userService;
}
@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
if (sender instanceof Player player && args.length > 0) {
userService.processUserData(args[0]);
player.sendMessage("§aUser data processed successfully!");
return true;
}
return false;
}
}
How it works & Constraints
-
Role:
@Listeners: Eliminates the need to call getServer().getPluginManager().registerEvents(...) inside onEnable(). The framework scans and registers listener beans automatically.
@Commands: Auto-registers the target CommandExecutor directly to the server command map using the specified command name.
-
Constraints:
- Interface Requirement:
@Listeners target classes must implement Bukkit's Listener interface.
plugin.yml Registration: Commands declared with @Commands must still be defined under the commands: section in plugin.yml (unless using a dynamic command map bridge).
- Singleton Life Cycle: Both listeners and commands are treated as singleton components and support full dependency injection via
@Inject.
7. Schedule & Async Execution Example
package com.lazberry.myplugin.task;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import Framework.Annotation.Async;
import Framework.LazberryRegistryFramework.Annotation.Schedule;
import com.lazberry.myplugin.service.UserService;
@Component
public class CacheCleanupTask {
private final UserService userService;
@Inject
public CacheCleanupTask(UserService userService) {
this.userService = userService;
}
// Runs asynchronously every 5 minutes (6000 ticks) after an initial 10-second delay (200 ticks)
@Schedule(delay = 200, period = 6000, async = true)
public void runPeriodicCachePurge() {
System.out.println("[LRF] Starting automated background cache cleanup...");
// Heavy operations here will not freeze the main server thread
}
// Simple asynchronous method execution invoked on demand
@Async
public void processHeavyDataLog(String logData) {
// Runs immediately on a background thread pool
System.out.println("[LRF Async Worker] Logging user activity: " + logData);
}
}
How it works & Constraints
-
Role:
@Schedule: Automatically registers and triggers method execution loops using Bukkit's scheduler without manual runTaskTimer() calls.
@Async: Offloads method execution directly to a background thread pool to prevent main-thread lag spikes during compute-heavy or I/O operations.
-
Constraints:
- Thread Safety: Methods annotated with
@Async or @Schedule(async = true) must not directly invoke Bukkit API methods that require main-thread execution (e.g., modifying entities or blocks directly).
- Component Bound: Target methods must belong to a valid IoC-managed bean (e.g., annotated with
@Component).
- Parameterless Schedules: Scheduled methods (
@Schedule) should generally have no parameter requirements so the framework worker can invoke them automatically.
8. Conditional Component Registration (@Conditional)
You can dynamically include or exclude components from the IoC container based on runtime environments, feature toggles, or server configurations.
Step 1: Implement the Condition Evaluator
package com.lazberry.myplugin.condition;
import Framework.LazberryRegistryFramework.ConditionalRegistry;
// 1. Define your custom runtime condition evaluator
public final class DevEnvironmentCondition implements ConditionalRegistry {
@Override
public boolean matches() {
// Returns true only when running on a development server environment
return System.getProperty("server.env", "prod").equalsIgnoreCase("dev");
}
}
Step 2: Apply @Conditional to the Component
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Conditional;
import com.lazberry.myplugin.condition.DevEnvironmentCondition;
// 2. The component is instantiated ONLY IF DevEnvironmentCondition#matches() returns true
@Component
@Conditional(DevEnvironmentCondition.class)
public class DebugLoggerService {
public DebugLoggerService() {
System.out.println("[LRF Debugger] Dev Environment detected. Initializing DebugLoggerService...");
}
public void logDebugInfo(String message) {
System.out.println("[DEBUG] " + message);
}
}
How it works & Constraints
-
Role:
- Zero-Footprint Filtering: The LRF scanner evaluates
matches() before instantiating the target component. If false, the component is completely dropped from the compilation queue—leaving zero memory overhead.
- Decoupled Architecture: Eliminates hardcoded
if/else checks inside initialization methods, keeping components clean and modular across different server environments (e.g., Lobby vs. Minigame servers).
-
Constraints:
- Default Constructor Required: The evaluator class implementing
ConditionalRegistry must possess an accessible no-argument default constructor so the framework can instantiate it via reflection during the scan phase.
- Class Target Only:
@Conditional can only be applied to class-level declarations (ElementType.TYPE).
9. External & Third-Party Instance Registration
Step 1: Pre-Register External Handles (Bootstrapping)
package com.lazberry.myplugin;
import Framework.LazberryRegistryFramework.DependencyContainer;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.File;
public class MyPluginBootstrap {
public static void initializeContainer(JavaPlugin plugin) {
// Pre-registers native Bukkit context handles into the primary IoC registry
DependencyContainer.registerInstance(JavaPlugin.class, plugin);
DependencyContainer.registerInstance(File.class, plugin.getDataFolder());
// Example: Registering a third-party library instance manually
// DependencyContainer.registerInstance(JedisPool.class, new JedisPool("localhost", 6379));
}
}
Step 2: Inject Registered Handles Anywhere
package com.lazberry.myplugin.service;
import Framework.Annotation.Component;
import Framework.Annotation.Inject;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.File;
@Component
public class StorageService {
private final JavaPlugin plugin;
private final File dataFolder;
@Inject
public StorageService(JavaPlugin plugin, File dataFolder) {
// Automatically injected from the pre-registered external handles
this.plugin = plugin;
this.dataFolder = dataFolder;
}
public void printPluginInfo() {
plugin.getLogger().info("Data folder path: " + dataFolder.getAbsolutePath());
}
}
How it works & Constraints
-
Role:
- Early Context Insertion: Allows non-managed external instances (such as Paper/Spigot handles, database pools, or external API clients) to be available across the entire IoC dependency graph via
@Inject.
- Polymorphic Lookup:
getBean(Class) safely retrieves registered instances through type assignability checks without requiring manual explicit casting.
-
Constraints:
- Bootstrapping Timing: External instances must be registered using
registerInstance() before invoking PackageScanner.buildAndInjectBeans() to guarantee dependency availability during constructor resolution.
- Key Overwrite: Registering another instance with an identical class key will overwrite the previous entry inside the underlying container map.
Technical Architecture and Implementation Specification (Rev. 2026.1)
1. Architectural Philosophy and Motivation
The Lazberry Registry Framework (LRF) is an enterprise-grade, high-performance Inversion of Control (IoC) and Dependency Injection (DI) engine specifically engineered for highly distributed, multi-proxy Minecraft server topologies. Traditional application frameworks like Spring or Guice introduce substantial runtime reflection overhead, large memory footprints, and lack native understanding of game-loop dynamics, tick-rate constraints, and server-proxy network layouts.
LRF solves these domain-specific challenges through Deterministic Architectural Invariants:
- Concrete Enforcement (Anti-Virtual Invariant): The framework completely bans ambiguous IoC state mapping. Interfaces and abstract blueprints are strictly isolated as declarative models (
@Virtual), forcing explicit concrete implementation binding to guarantee predictable memory layouts and zero runtime lookup ambiguity.
- OOP Invariant Preservation via Encapsulation Locks: Native Bukkit lifecycle hooks (
onEnable, onDisable) are declared final at the master class level. This enforces safe, symmetrical teardown/startup mechanics, preventing user code from bypassing IoC container assembly or graceful shutdown queues.
- Aggressive Fail-Fast Runtime-Safety: Rather than allowing hidden errors or lazy initialization failures to surface mid-game (potentially crashing tick loops or corrupting player data), LRF executes top-down topological graph verification and configuration mapping at boot time. Any structural failure instantly aborts the bootstrapping sequence.
2. Main Bootstrapper & Subclass Specification (JavaPlugin Encapsulation)
To eliminate boilerplate setup and enforce strict lifecycle encapsulation, main plugin entry points must extend LazberryRegistryFramework directly instead of raw Bukkit JavaPlugin.
[Server Boot]
│
▼
┌────────────────────────────────────────────────────────┐
│ LazberryRegistryFramework.onEnable() [LOCKED final] │
├────────────────────────────────────────────────────────┤
│ 1. Context Allocation & Package Boundary Discovery │
│ 2. ClassPath Scanning & Config Mapping (@ConfigObject) │
│ 3. IoC Graph Resolution & ByteBuddy Proxy Assembly │
│ 4. Scheduler & Event Binding │
│ 5. Developer Hook Dispatch ────────────────────────────┼──► onLrfEnable()
└────────────────────────────────────────────────────────┘
2.1. Inviolable Lifecycle Locks (final Enforcement)
LazberryRegistryFramework locks native Bukkit entry points to prevent lifecycle fragmentation:
@Override
public final void onEnable() {
boot(this, getClass());
onLrfEnable();
}
@Override
public final void onDisable() {
try {
onLrfDisable();
} finally {
ScheduleProcessor.cancelAllSchedules();
ShutdownRegistry.executeShutdownSequence();
cleanUp(this, getClass());
}
}
2.2. User Implementation Guide (Concrete Main Class)
Developers implement user-level setup and teardown logic via protected lifecycle hooks:
package com.lazberry.myplugin;
import Framework.LazberryRegistryFramework.LazberryRegistryFramework;
import lombok.extern.slf4j.Slf4j;
@Slf4j
public final class MyPluginMain extends LazberryRegistryFramework {
@Override
protected void onLrfEnable() {
// Invoked IMMEDIATELY AFTER LRF IoC Container and Proxy initialization
log.info("MyPlugin successfully booted on LRF Core!");
}
@Override
protected void onLrfDisable() {
// Invoked IMMEDIATELY BEFORE Task Cancellation & IoC Container Teardown
log.info("MyPlugin initiating safe shutdown sequence...");
}
}
- Implicit Package Topology Discovery: Calling
boot(this, getClass()) automatically intercepts mainClass.getPackageName(). This establishes the implicit reflection scanning boundary without hardcoded package string parameters.
3. Global Component Matrix and Package Structure
3.1. Root Domain Configuration (Framework)
Framework.Annotation: Core structural markers governing component boundaries (@Component.Include, @Conditional), instantiation selection (@Inject), template classification (@ConsumableClass, @Virtual), and runtime semantic declarations (@Document, @Transactional).
Framework.FrameworkExceptions: Terminal boundary violation exceptions that halt bootstrapping upon structural invariants breach.
Framework.Utils: Low-level, high-throughput primitives (ParseEnum, ColorUtils, IDGenerator).
- Lifecycle & Topology Abstractions: Contextual environment markers (
Local, Global) registered into ServerType prior to scanning.
3.2. Engine Core (Framework.LazberryRegistryFramework)
Framework.LazberryRegistryFramework.Annotation: Spigot/Paper specific hooks (@Commands, @Listeners, @Schedule, @ConfigObject, @GracefulShutdown, @InboundChannel, @OutboundChannel).
Framework.LazberryRegistryFramework.Monitoring: Microsecond-precision telemetric subsystem (PerformanceRegistry, MetricData).
- Core Orchestration Engines: Classpath traversal (
PackageScanner), reflection caching (Reflections), dependency graph assembly (DependencyContainer), type-safe config mapping (ConfigObjectMapper), AOP proxy generation (LrfProxyFactory), and network message routing (PluginMessageRouter).
4. Component Scanning, O/R Mapping, and Pipeline Filters
The PackageScanner pipeline enforces multi-stage filtering to isolate runtime components.
[Classpath Traversal] ──► [Interface / Abstract Check]
│
▼
[Consumable / Virtual Filter]
│
▼
[Server Compatibility Check]
│
├─────────────────────────┐
▼ ▼
[@ConfigObject Mapping] [Component Collection]
│ │
▼ ▼
[Direct IoC Registration] [Conditional Verification]
│
▼
[Target Assembly List]
4.1. Configuration O/R Mapping (@ConfigObject)
To eliminate raw FileConfiguration.get() calls and guarantee type-safety, LRF features a zero-boilerplate YAML-to-POJO/Record mapping engine (ConfigObjectMapper).
- Record Support: Supports immutable Java Records (Java 16+) and standard POJOs.
- Instantiation Phase: Executed during scanning before constructor injection, registering mapped config instances into
DependencyContainer.
@ConfigObject(path = "database", file = "config.yml")
public record DatabaseConfig(
String host,
int port,
String username,
String password,
int maxPoolSize
) {}
4.2. Virtual Blueprint Guard (@Virtual)
Abstract templates, mock structures, or base classes meant for inheritance are annotated with @Virtual. PackageScanner drops these targets immediately, preventing incomplete blueprints from polluting the IoC container.
5. IoC Assembly Line & Topological Graph Resolution
The DependencyContainer manages a transactional, top-down assembly line to compile concrete application components.
5.1. Resolution Strategy
- Cache Interception: Scans
BEAN_CONTAINER using Class.isAssignableFrom for single-address memory contract representation.
- Strict Abstraction Barrier: Non-concrete types passed directly into the assembly line trigger a
VirtualClassInjectException.
- Cyclic Lock Defusion: The
CONSTRUCTION_STACK (LinkedHashSet) tracks active construction chains. Detecting an active type token in a nested parameter immediately raises a CircularDependencyException.
5.2. Constructor Selection & Parameter Injection
- Constructor preference is given to
@Inject decorated constructors, falling back to public zero-arg handles.
- Parameters annotated with
@ConfigValue route to ConfigInjection.resolve().
- Parameter classes annotated with
@ConfigObject or standard @Component models recursively resolve via DependencyContainer.getOrCreateBean().
6. Defensive Exception Framework Architecture
| Exception Class |
Root Cause Trigger |
Architectural Purpose |
VirtualClassInjectException |
Direct injection attempt of an interface, abstract class, or @Virtual token. |
Guarantees that only concrete, instantiable singletons populate the IoC context. |
CircularDependencyException |
Self-referential loop intercepted in the active constructor stack trace. |
Prevents thread freezing and infinite recursion stack overflow crashes. |
NotCompatibleWithServerException |
Component environmental requirements fail the active platform check. |
Prevents class-loading crashes caused by missing NMS versions or invalid server bindings. |
NotValidInitializeTimingException |
Initialization hook executed out-of-bounds from the current container phase. |
Enforces strict chronological order across multi-module managers. |
InvalidConfigInjectException |
Missing configuration nodes or structural type mismatch during value resolution. |
Ensures that corrupted or incomplete files fail early before runtime errors occur. |
7. Teardown and Resource Purging Pipeline
To prevent JVM classloader memory leaks during hot-reloads (/reload), LRF enforces an inverted teardown sequence:
- User Teardown Dispatch: Executes developer logic in
onLrfDisable().
- Task Freezing:
ScheduleProcessor.cancelAllSchedules() systematically cancels active asynchronous/synchronous task loops.
- Prioritized Shutdown: Handlers tagged with
@GracefulShutdown execute in prioritized sequence to dump memory caches and persist database state.
- Static Container Purge:
cleanUp() unregisters ServerType references and wipes static container maps, releasing classloader handles for complete Garbage Collection.
评论 0
登录后参与评分
还没有评论,来抢沙发吧