# tiny
**Repository Path**: xnat/tiny
## Basic Information
- **Project Name**: tiny
- **Description**: 小巧的java应用微内核通用框架, 可用于构建小工具，web，各种大大小小的应用
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 68
- **Forks**: 15
- **Created**: 2020-12-10
- **Last Updated**: 2026-06-20
## Categories & Tags
**Categories**: Uncategorized
**Tags**: 异步, 轻量级, 事件驱动, 多线程, 微内核
## README
# Tiny
> 小巧的 Java 应用微内核框架，基于事件驱动架构
## 前置条件
- JDK 8+
- Maven 3.x
- 支持 MySQL / MariaDB / OceanBase / PostgreSQL / SQLite / Oracle / DB2 / H2 等主流数据库（XQL 模块）
## 目录
- [特性概览](#特性概览)
- [安装](#安装)
- [快速开始](#快速开始)
- [统一事件驱动 EP](#统一事件驱动-ep)
- [配置](#配置)
- [X-ap 同名节点数据同步](#x-ap-同名节点数据同步)
- [定时任务调度 Sched](#定时任务调度-sched)
- [服务基础类 BeanTpl](#服务基础类-beantpl)
- [队列执行器 XQueue](#_队列执行器_-xqueue)
- [数据库工具 XQL](#数据库工具-xql)
- [HTTP 客户端](#http-客户端)
- [对象拷贝器](#对象拷贝器)
- [缓存 Cacher](#简单缓存-cacher)
- [其他工具](#其他工具)
- [应用示例](#应用示例)
- [参与贡献](#参与贡献)
## 特性概览
| 模块 | 说明 |
|------|------|
| **EP (事件驱动)** | 统一的协议空间+路径事件模型，解耦控制层/服务层/DAO层 |
| **XQueue** | 轻量级队列执行器(伪协程)，控制并发、速度、暂停/恢复 |
| **XQL** | 轻量 ORM，注解建表、链式查询、事务支持 |
| **Sched** | 五种调度模式：Cron、时间点、延迟、固定间隔、动态调度 |
| **HTTP** | 基于事件驱动的 HTTP 服务 + HTTP 客户端工具 |
| **Cacher** | 简单内存缓存，支持 Hash 结构和过期策略 |
| **X-ap** | 同名节点间数据变更同步 |
## 介绍
目前大部分高级语言都解决了编程中的内存自动管理问题(垃圾回收)， 但并没有解决 CPU 资源自动管理的问题。
基本上都是程序员主动创建线程或线程池，这些线程是否被充分利用了？在应用不同的地方创建是否有必要？
太多的线程是否造成竞争性能损耗？毕竟线程再多，决定并发的是 CPU 的个数。
所以需要框架来实现一个智能执行器(线程池)：根据应用的忙碌程度自动创建和销毁线程，
即线程池会自己根据排队的任务数和当前池中线程数的比例判断是否需要新创建线程（与传统固定大小线程池不同）。
会 catch 所有异常，不会因业务异常而终止（常驻运行）。
程序只需配置最大最小资源即可自动适配。这样既能充分利用线程资源，
也减少线程的空转和线程过多调度的性能浪费，代码不用直接和线程交互。
> 所以系统性能只由线程池大小属性 sys.exec.corePoolSize=8, sys.exec.maximumPoolSize=16 和 jvm内存参数 -Xmx1g 控制
框架设计一种轻量级执行器(伪协程): __XQueue__ 来控制执行模式(并发,暂停/恢复,速度等)
上层服务应该只关注怎么组装执行任务，然后提交给 __XQueue__ 或直接给执行线程池。如下图：
## 安装
```xml
cn.xnatural
tiny
3.0.test7
```
## 快速开始
```java
App.source(new XQL("db.test"));
// 应用启动(会自动扫描并创建当前包下所有@bean注解的类, 依次触发系统事件)
App.start("需要扫描的包");
```
### 启动流程
```
App.source(服务实例...) ← 启动前手动注册服务(可选)
App.start("扫描包路径") ← 入口
│
├─ 1. 注册 JVM 关闭钩子 (kill 时触发 sys/stopping)
│
├─ 2. 扫描包, 自动创建 @Bean 类并加入容器
│ └─ 先扫框架包 cn.xnatural, 再扫用户包
│
├─ 3. 解析所有 bean 的 @EL 方法, 注册为事件监听器
│
├─ 4. @Inject 字段自动注入
│
└─ 5. 依次触发系统事件:
sys/inited → 环境配置、线程池、事件中心就绪
sys/starting → 各服务执行自己的初始化逻辑
sys/started → 各服务开始运行, 应用启动完成
EP 事件驱动
│
├─ resolve: 扫描 @EL 方法 → 按 ns(协议空间) + path(路径) 注册监听器
│
├─ fire: 触发事件 → 匹配监听器 → 执行
│
└─ 执行策略:
├─ 同步/异步 (async)
├─ 并发控制 (parallel)
└─ 排队顺序 (order)
```
## 统一事件驱动 EP
EP（Event Protocol）是 Tiny 的核心通信机制。事件由 **协议空间（ns）+ 路径（path）** 唯一标识，任何组件都可以发布或订阅事件，无需直接依赖。
```
发布者 ──fire("user/login")──→ EP 事件中心 ──匹配──→ 所有监听器执行
```
### @EL 注解
```java
@EL(ns = "协议空间", path = "事件路径")
void handler(参数...) { ... }
```
| 属性 | 说明 | 默认值 |
|------|------|--------|
| `ns` | 协议空间，用于分类事件 | 空 |
| `path` | 事件路径，`/` 分隔，支持 `{变量}` | 必填 |
| `async` | 是否异步执行（不排队） | `false` |
| `parallel` | 并发数（同一事件多个监听器同时执行） | `1` |
| `order` | 执行顺序（数字越小越先） | `0` |
| `exclusive` | 排他模式（优先于其他监听器执行） | `false` |
### 发布事件
```java
// 简单触发
ep.fire("order/created");
// 带参数
ep.fire("order/created", orderId, userId);
// 带协议空间（需构造 EC）
ep.fire(new EC("sys", "started"));
```
### 监听事件
```java
@Bean
public class OrderService extends BeanTpl {
// 监听订单创建
@EL(path = "order/created")
void onOrderCreated(String orderId, String userId) {
log.info("订单已创建: {}", orderId);
}
// 同一事件可以有多个监听器，按 order 排序执行
@EL(path = "order/created", order = 10)
void sendNotification(String orderId, String userId) {
// 发通知...
}
}
```
### 系统生命周期事件
App 启动后依次触发，服务在这些事件中完成初始化：
```
sys/inited → 基础设施就绪（配置、线程池、事件中心）
sys/starting → 各服务执行初始化逻辑
sys/started → 应用启动完成，各服务开始运行
sys/stopping → 应用关闭（kill 时触发）
```
```java
@Bean
public class CacheService extends BeanTpl {
@EL(ns = "sys", path = "starting")
void init() {
// 加载缓存数据...
}
@EL(ns = "sys", path = "stopping")
void destroy() {
// 持久化缓存...
}
}
```
### HTTP 事件
HTTP 请求也是事件，`ns = "HTTP"`，`path` = URL 路径。类级 `@EL` 需加 `exclusive = true`，确保请求只由匹配的控制器处理，不会穿透到其他监听器。
```properties
### app.properties
xnet.hp=:8080
# xnet.webDir=web # 静态资源目录（相对运行目录）
# cluster.detect=http://localhost:7070 # 集群探测地址
```
```java
@Bean
@EL(ns = "HTTP", path = "api/user", exclusive = true)
public class UserCtrl extends BeanTpl {
@EL(path = "list", op = "get")
R> list(Integer limit) {
return R.ok(userService.list(limit));
}
@EL(path = "{id}", op = "get")
R get(String id) {
return R.ok(userService.get(id));
}
@EL(path = "save")
R save(User user) {
return R.ok(userService.save(user));
}
// 异步响应：返回 CompletableFuture
@EL(path = "async")
CompletableFuture async() {
CompletableFuture f = new CompletableFuture<>();
App.exec(() -> f.complete("done"));
return f;
}
// 文件下载
@EL(path = "download/{fName}", op = "get")
File download(String fName, XResponse response) {
response.contentDisposition("attachment;filename=" + fName);
return new File("/tmp/" + fName);
}
}
```
#### HTTP 扩展点
通过特殊协议空间拦截 HTTP 处理流程：
```java
// 自定义错误处理
@EL(ns = "http:error", path = "{_}", exclusive = true)
R onError(XContext ctx, Throwable ex) {
log.error(ctx.ep.logStr(ctx), ex);
return R.fail(ex == null ? null : ex.getMessage());
}
// 自定义 JSON 序列化
@EL(ns = "http:response:json", path = "{_}", exclusive = true)
Object toJson(XResponse resp) {
Object r = resp.ctx.result();
if (r instanceof String) return r;
return JSON.toJSONString(r);
}
// 自定义会话管理
@EL(ns = "http:session", path = "{_}", exclusive = true)
Map session(XContext ctx) {
// 从 cookie 获取 sessionId，返回会话 Map
// ...
}
```
### 自定义事件
任意定义协议空间和路径，用于业务解耦：
```java
// 发布
ep.fire("order/paid", orderId);
// 监听
@EL(path = "order/paid")
void onPaid(String orderId) { ... }
// 数据库就绪事件（无协议空间）
@EL(path = "/db/test/started", async = true)
void onDbReady() { ... }
```
## 配置
> 配置文件加载顺序(优先级从低到高):
* classpath: app.properties, classpath: app-[profile].properties
* file: ./app.properties, file: ./app-[profile].properties
* configDir: app.properties, configDir: app-[profile].properties
* 自定义环境属性配置(重写方法): App#customEnv
* System.getProperties()
>+ 系统属性(-DconfigName): configName 指定配置文件名. 默认: app
>+ 系统属性(-Dprofile): profile 指定启用特定的配置
>+ 系统属性(-DconfigDir): configDir 指定额外配置文件目录
* 只读取properties文件. 按顺序读取app.properties, app-[profile].properties 两个配置文件
* 配置文件支持简单的 ${} 属性替换
## X-ap: 同名节点数据同步
> 扩展协议 X-Upgrade: X-ap
一般用于同名多节点有内存缓存，缓存更改后和其他节点之间的数据同步通知
### 变更监听器
```java
@EL(path = "user", ns = AP.DATA_VERSION)
void ap_user(String dataKey, Long version) {
// 处理同名应用其他节点的用户数据更改通知
}
```
### 变更通知
```java
ap.update("user", "user1", System.currentTimeMillis());
```
## 定时任务调度 Sched
### Cron 时间表达式
```java
sched.cron("0 0/5 * * * ? ", () -> {
System.out.println("每隔5分钟执行");
})
```
```java
sched.cron("0 0/5 8-11:20,13:10-17:50 * * ? ", () -> {
System.out.println("在(8-11:20,13:10-17:50)范围内每隔5分钟执行");
})
```
### 在将来的某个时间点执行
```java
sched.time(
new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2020-12-12 11:55:33"),
() -> System.out.println("2020-12-12 11:55:33 执行")
);
```
### 一段时间之后执行
```java
sched.after(Duration.ofMinutes(3), () -> {
System.out.println("3分钟之后执行")
});
```
### 任务间隔执行
#### fixedDelay
```java
sched.fixedDelay(Duration.ofSeconds(10), Duration.ofSeconds(5), () -> {
System.out.println("fixedDelay====第一次执行延时5秒执行");
});
```
```java
sched.fixedDelay(Duration.ofSeconds(10), () -> {
System.out.println("fixedDelay====");
});
```
#### fixedRate
```java
sched.fixedRate(Duration.ofSeconds(10), Duration.ofSeconds(5), () -> {
System.out.println("fixedRate====第一次执行延时5秒执行");
});
```
```java
sched.fixedRate(Duration.ofSeconds(10), () -> {
System.out.println("fixedRate====");
});
```
### 动态任务调度执行. 自定义下次执行时间
#### dynRate
```java
sched.dynRate(() -> { //每次执行完任务函数,会获取一次下次执行时间
if (new Random().nextInt(100) == 70) return null; // 返回null任务停止
Calendar cal = Calendar.getInstance();
cal.add(Calendar.MINUTE, new Random().nextInt(30) + 10);
return cal.getTime();
}, () -> System.out.println("动态任务执行"));
```
#### dynDelay
```java
sched.dynDelay(() -> { //每次执行完任务函数,会获取一次下次执行时间
if (new Random().nextInt(100) == 70) return null; // 返回null任务停止
Calendar cal = Calendar.getInstance();
cal.add(Calendar.MINUTE, new Random().nextInt(30) + 10);
return cal.getTime();
}, () -> System.out.println("动态任务执行"));
```
## 动态按需添加服务
```java
@EL(ns = "sys", name = "inited")
void inited() {
if (!app.attrs("redis").isEmpty()) { //根据配置是否有redis,创建redis客户端工具
app.source(new RedisClient());
}
}
```
## 服务基础类 BeanTpl
> 推荐所有被加入到App中的服务都是BeanTpl的子类
```properties
### app.properties
服务名.prop=1
```
```java
app.source(new BeanTpl("服务名") {
@EL(ns = "sys", path = "starting")
void start() {
// 初始化服务
}
})
```
### bean注入 @Inject(name = "beanName")
> 注入匹配规则: (已经存在值则不需要再注入)
> > 1. 如果 @Inject name 没配置
> > > 先按 字段类型 和 字段名 匹配, 如无匹配 再按 字段类型 匹配
> > 2. 则按 字段类型 和 @Inject(name = "beanName") beanName 匹配
```java
app.source(new BeanTpl() {
@Inject XQL repo; //自动注入
@EL(ns = "sys", path = "started")
void init() {
List