# ricks-main

**Repository Path**: mo-wei-git/ricks-main

## Basic Information

- **Project Name**: ricks-main
- **Description**: 游戏 游戏开发 游戏架构 
 IOC容器  定时器  事件  网络层支持 http  tcp udp kcp协议，orm 自动生成mysql table 表结构
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 4
- **Created**: 2024-10-14
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ricks-main

# QQ群：1032394160

#### 介绍
游戏架构， IOC  定时器  事件  网络层使用的是smart-socket支持 http  tcp udp，zfoo-orm mongodb 
使用了 jdk24 classfile特性进行字节增强，优化反射调用

#### 软件架构
# 框架jdk版本：jdk25，jdk21版本切成一个分支
# 支持增删方法级别代码热更

Ricks-Main 项目详细说明文档
一、项目概述

Ricks-Main是一个基于Java的游戏服务器框架，提供完整的游戏开发基础设施支持。该项目最初从ricks-core迁移而来。

二、核心特性

1. 架构组件‌

轻量级IOC容器
高精度定时器系统
事件驱动机制
多协议网络层（支持HTTP/TCP/UDP）


3. 性能优化‌

网络路由采用JDK24 classfile 字节增强技术 （jdk内部维护了一套asm语法糖lambda表达式就是基于内部的asm生成的 ,jdk24 classfile特性提供了api 给开发者使用）
自动生成switch(action)字节码
反射性能接近直接方法调用
三、开发环境要求
JDK版本：25
构建工具：Maven/Gradle


核心 IOC 容器 (RicksContext)
这是整个框架的基石，负责管理对象的生命周期和依赖注入。


核心职责：

类扫描与 Bean 注册：通过 ClassScanner.scanPackage 扫描指定包路径下的类，识别带有特定注解的类，并将其注册为 Bean。
Bean 定义与存储：使用 BeanDefinition（及其实现类 DefaultBeanDefinition、ConfigurationBeanDefinition）来描述和管理 Bean 的元数据（如类型、实例、依赖关系）。所有 Bean 定义存储在 beanDefinitionMap 中。
依赖注入 (DI)：

@Autowired：用于字段注入，根据类型自动装配其他 Bean。
@Value：用于配置注入，从配置文件（通过 RicksPropertiesLoader 加载）中读取值并注入到字段。


生命周期管理：

@Init：标记初始化方法，在 Bean 所有依赖注入完成后，按优先级 (priority) 执行。
@PreDestroy：标记销毁方法，在容器关闭时按优先级执行。


后置处理器：通过 BeanAnalysisProcessor 接口（如 EventRegisterProcessor, SchedulerRegisterProcessor）提供扩展点，在 Bean 初始化后执行自定义逻辑（如事件监听器、定时任务注册）。



关键注解：

@Bean：标记一个类为可被容器管理的 Bean。
@Controller：一种特殊的 Bean 注解。
@Configuration：标记配置类，其内部使用 @Bean 标注的方法也会被解析并注册为 Bean。
@Autowired / @Value：如上所述，用于依赖注入。



启动流程 (Ricks.run)：

加载配置（命令行参数 > 本地配置文件）。
实例化启动类（需实现 Lifecycle 接口）并调用其 start() 方法。
RicksContext.init() 被触发，执行类扫描、Bean 实例化、依赖注入、调用 @Init 方法。
发布 RicksContextStartedIEvent 事件。
容器关闭时，调用 @PreDestroy 方法并发布 RicksContextStoppedIEvent。



二、 配置管理


RicksPropertiesLoader：

负责从多个来源加载配置，优先级为：命令行参数 (--key=value) > 本地配置文件。
支持多环境配置，如 application.properties 和 application-dev.properties。
提供 getString、getBoolean、getInt 等方法读取配置。



EnvConfigHolder：

配置的全局持有者，通过 buildLoadFunction 绑定 RicksPropertiesLoader 的加载逻辑。
提供静态方法供 @Value 注入时获取配置值。



三、 事件总线 (EventBus)
一个基于发布-订阅模式的事件驱动模块，用于解耦组件通信。


核心概念：

IEvent：事件接口，所有事件需实现此接口。可以通过重写 executorHash() 方法来指定事件在哪个线程池执行。
IEventReceiver / EventReceiverDefinition：事件接收者（监听器）。EventReceiverDefinition 是对被 @EventReceiver 注解方法的包装。
@EventReceiver：注解在方法上，标记该方法为某个 IEvent 类型事件的监听器。可以指定 Bus 类型（CurrentThread, AsyncThread, VirtualThread）来控制事件执行的线程策略。



工作原理：

EventRegisterProcessor（一个 BeanAnalysisProcessor）在 Bean 初始化后，扫描所有带有 @EventReceiver 的方法，并将其注册到 EventBus.receiverMap 中。
调用 EventBus.post(event) 发布事件时，EventBus 会根据事件类型找到所有监听器，并根据其 Bus 设置决定是在当前线程同步执行，还是提交到异步线程池执行。
线程池 (executors) 是基于 CPU 核心数创建的一组单线程池，通过 executorHash() 实现事件的路由，可以将相关事件路由到同一个线程顺序执行，避免加锁。



增强与热更：

EnhanceUtils.createEventReceiver：在 Java 24+ 环境下，使用 java.lang.classfile API 动态生成 IEventReceiver 实现类字节码，以替代反射调用，提升性能。
支持热更：EventReceiverDefinition.getBean() 方法会优先返回热更后的类实例。



四、 定时任务调度 (SchedulerBus)
一个功能强大的定时任务调度框架，支持多种触发策略。


核心概念：

IScheduler：任务执行器接口，只有一个 invoke() 方法。
SchedulerDefinition：任务定义，包含触发器 (Trigger)、执行器 (IScheduler)、下次触发时间、任务ID等。
Trigger 及其实现：

DelayTrigger：一次性延迟任务。
FixedRateTrigger：固定频率的周期性任务。
CronTrigger：基于 Cron 表达式的任务。


@Scheduled：注解在方法上，标记该方法为一个调度任务。支持 cron、initialDelay、fixedRate 参数。



工作原理：

SchedulerRegisterProcessor（另一个 BeanAnalysisProcessor）在 Bean 初始化后，扫描所有带有 @Scheduled 的方法，根据注解参数创建对应的 SchedulerDefinition 并注册到 SchedulerBus。
SchedulerBus 内部维护一个按触发时间排序的优先队列 (schedulerQueue) 和一个任务映射 (taskMap)。
一个独立的调度线程 (executor) 每隔 100ms 触发一次 (triggerPerSecond)，检查并执行到达触发时间的任务。
任务的实际执行被提交到一个独立的线程池 (taskExecutor) 中，避免阻塞调度线程。
同样支持通过 EnhanceUtils.createScheduler 进行字节码增强以优化性能。



高级特性：

时间回拨处理：当系统时间发生回拨时，能重新校准任务的触发时间。
任务取消：提供 cancelTask、cancelTasksForClass 等方法，可以精确取消任务。
与事件集成：可以通过 EventScheduler 将 IEvent（如 DelayEvent, FixRateEvent, CronEvent）包装成调度任务来发布。



五、 热修复 (HotfixManager)
一个支持在不重启应用的情况下更新类代码的模块。


核心机制：

使用一个自定义的 HotfixClassLoader（继承自 ClassLoader）来加载新的类字节码。
热更后的类被缓存到 HOTFIX_CLASSES 映射中。
在 DefaultBeanDefinition.getBean() 和 EventReceiverDefinition.getBean() 等方法中，会优先检查并返回热更后的类实例。
通过 RicksContext.refreshBean(Class) 方法，可以触发对指定类的 Bean 进行重新注入和处理器调用。



流程：

传入新版本的类字节码。
HotfixManager.hotfixClass 使用自定义类加载器定义新类。
调用 RicksContext.refreshBean，该方法会：

取消与该类相关的所有定时任务 (SchedulerBus.cancelTasksForClass)。
使用新类创建新实例，并通过 copyFieldValues 将旧实例的字段值复制过去。
重新执行依赖注入 (injection()) 和后置处理器 (beanAnalysisProcessor)。





六、 工具与辅助类

TaskBus：另一个线程池管理器，用于执行 CPU 密集型任务。与 EventBus 的线程池隔离。通过 calTaskExecutorHash 方法将任务路由到特定的单线程池执行，常用于保证同一玩家的请求顺序处理。
CronExpression：一个独立的 Cron 表达式解析器，用于 CronTrigger。
EnhanceUtils：利用 Java 24+ 的 java.lang.classfile API 进行运行时字节码生成的工具类，用于优化事件和调度任务的调用性能，避免反射开销。

七、 设计特点总结

轻量级与高内聚：代码结构清晰，核心容器、事件、调度、热更等模块职责分明，但又紧密集成。
注解驱动：大量使用注解（@Bean, @Autowired, @EventReceiver, @Scheduled）来声明和配置，开发体验接近 Spring。
线程模型优秀：

EventBus 和 TaskBus 都采用一组单线程池，通过哈希路由保证特定上下文（如同一玩家、同一实体）的操作在同一个线程内顺序执行，天然避免了并发问题，性能高。
调度任务执行与调度检查线程分离，互不阻塞。


扩展性强：

通过 BeanAnalysisProcessor 接口可以轻松插入自定义的 Bean 处理逻辑。
事件和调度系统本身也是通过后置处理器接入 IOC 容器的。


生产级特性：

支持热修复，这在游戏服务器等需要高可用性的场景中非常关键。
调度系统考虑了时间回拨等边界情况。
配置系统支持多环境、外部化配置。


性能优化：

在支持高版本 Java 时，使用原生字节码生成 API 替代反射，提升事件和调度方法的调用速度。
使用并发集合 (ConcurrentHashMap, ConcurrentSkipListSet) 保证线程安全。



总体而言，ricks-ioc 是一个设计精良、功能完备的 Java 应用框架，特别适合需要高性能、高可控性、以及在线热更新能力的场景，例如游戏服务器、实时数据处理系统等。 它吸收了 Spring 等成熟框架的设计思想，并在特定领域（如线程模型、热更）做了深度优化和定制。



![输入图片说明](readme-image/Ricks%20IOC%E6%A1%86%E6%9E%B6%E6%A0%B8%E5%BF%83%E6%9E%B6%E6%9E%84_ima%E8%84%91%E5%9B%BE.jpeg)