# lite-delay
**Repository Path**: ingrun/lite-delay
## Basic Information
- **Project Name**: lite-delay
- **Description**: 一个简单好用的延时任务框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-06-02
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# LiteDelay
> 轻量级延迟任务调度框架，零外部中间件依赖，嵌入式部署，开箱即用。
[](https://www.oracle.com/java/)
[](https://spring.io/projects/spring-boot)
[]()
---
## 简介
LiteDelay 是一个轻量级延迟任务调度框架，适用于**任务量不大、不值得引入重型中间件**的场景——比如订单超时关闭、待办超时提醒、会员到期预警等日常业务需求。
**如果任务量大、并发高，RabbitMQ 依然是最佳选择。**
---
## 特性
- **零中间件依赖** — 核心模块纯 Java 实现，不依赖 Redis、MQ 等任何中间件
- **毫秒级精度** — 基于有序任务队列 + 精确等待，无空转轮询
- **多实例部署** — 所有节点对等调度，通过乐观锁 CAS 防重复执行，无需选主
- **多持久化支持** — 内置内存、MySQL、Redis 三种持久化方案，自由切换
- **Web 控制台** — 可视化任务管理界面，支持提交、查询、统计等操作
---
## 快速开始（Spring Boot 2.x）
只需三步即可接入：
### 1. 引入依赖
```xml
cn.ingrun
lite-delay-sb-starter
1.0.4
```
默认使用内存存储，零配置即可运行。需要持久化可参考下方 [MySQL](#mysql-持久化) 或 [Redis](#redis-持久化) 配置。
---
### 2. 实现任务处理器
```java
@Slf4j
@Component
public class OrderTimeoutHandler implements TaskHandler {
@Override
public void execute(Task task) {
String orderId = task.getParams().get("orderId");
log.info("订单 {} 支付超时，执行取消操作", orderId);
// 你的业务逻辑
}
@Override
public boolean match(String route) {
return "order:pay:timeout".equals(route);
}
@Override
public String getRoute() {
return "order:pay:timeout";
}
@Override
public long order() {
return 1;
}
}
```
---
### 3. 提交任务
```java
Task task = new Task();
task.setTaskName("订单超时关闭");
task.setRoute("order:pay:timeout");
task.setTriggerTime(System.currentTimeMillis() + 30 * 60 * 1000L); // 30 分钟后
Map params = new HashMap<>();
params.put("orderId", "ORDER-123456");
task.setParams(params);
String taskId = LiteDelay.submit(task);
```
启动应用后，任务到期自动调度执行，无需任何额外配置。
---
> ⚠️ 执行失败时框架记录错误日志，**不自动重试**（避免业务逻辑重复执行）。
> 重试需通过 `LiteDelay.retry(taskId)` 手动触发。
---
## 持久化方案
### 内存存储（默认）
使用内存存储任务数据，无需额外依赖，适合开发测试环境或重启不保留任务的场景。
### MySQL 持久化
基于 MySQL 数据库存储任务数据，支持数据持久化，应用重启后任务不丢失。
**引入依赖：**
```xml
cn.ingrun
lite-delay-sb-mysql
1.0.4
```
**配置数据源：**
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/lite_delay?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
username: litedelay
password: your_password
driver-class-name: com.mysql.cj.jdbc.Driver
```
**建表脚本：**
系统会自动执行建表脚本，也可手动执行：
```sql
CREATE DATABASE lite_delay DEFAULT CHARACTER SET utf8mb4;
CREATE TABLE IF NOT EXISTS lite_delay_task
(
task_id VARCHAR(64) NOT NULL COMMENT '任务ID',
task_name VARCHAR(255) NOT NULL COMMENT '任务名称',
status VARCHAR(20) NOT NULL COMMENT 'WAITING/RUNNING/FINISH/ERROR/PAUSE',
trigger_time BIGINT NOT NULL COMMENT '触发时间（毫秒时间戳）',
params TEXT COMMENT '任务参数（JSON格式）',
route VARCHAR(255) COMMENT '路由匹配标识',
PRIMARY KEY (task_id),
INDEX idx_status_trigger_time (status, trigger_time)
) ENGINE = InnoDB
DEFAULT CHARSET = utf8mb4;
CREATE TABLE IF NOT EXISTS lite_delay_exec_log
(
record_id VARCHAR(64) NOT NULL COMMENT '记录ID',
task_id VARCHAR(64) NOT NULL COMMENT '任务ID',
status VARCHAR(20) NOT NULL COMMENT '执行状态',
message TEXT COMMENT '执行信息',
create_time BIGINT NOT NULL COMMENT '创建时间',
execute_duration BIGINT NOT NULL DEFAULT 0 COMMENT '执行时长（毫秒）',
PRIMARY KEY (record_id),
INDEX idx_task_id (task_id)
) ENGINE = InnoDB
DEFAULT CHARSET = utf8mb4;
```
### Redis 持久化
基于 Redis ZSet 实现有序任务队列，触发时间作为 Score，支持高性能批量查询。
**引入依赖：**
```xml
cn.ingrun
lite-delay-sb-redis
1.0.4
```
**配置 Redis 连接：**
```yaml
spring:
redis:
host: localhost
port: 6379
password: your_password
database: 0
```
配置后即可自动生效。
---
## Web 监控面板
引入 `lite-delay-sb-web` 依赖后，启动应用访问：`http://localhost:8080/litedelay/`
**功能特性：**
- 📊 任务列表查看，支持状态筛选
- 🔍 任务详情查看，包括执行记录
- ➕ 在线提交新任务
- 🔄 任务操作：取消、暂停、恢复、重试、立即执行
- 📋 处理器列表查看
- 🔐 可选 Basic Auth 认证
**认证配置（可选）：**
```yaml
litedelay:
web:
# 是否启用 Basic Auth 认证，默认关闭
auth-enabled: false
# 认证用户名
username: admin
# 认证密码
password: admin123
```
---
## 多实例部署
LiteDelay 支持多节点对等部署，所有实例各自独立调度，通过乐观锁 CAS 确保同一任务仅由一个节点执行。
**工作原理：**
所有节点启动时都会从共享存储中加载待执行任务到本地内存队列。当任务到期时，各节点会同时尝试用 CAS（Compare-And-Swap）将任务状态从 `WAITING` 更新为 `RUNNING`，仅成功者获得执行权，其余节点自动跳过。
**特性：**
- 无需选主、零节点间通信
- 无单点故障，任一节点宕机不影响其余节点继续调度
- 节点可动态扩缩，无需停机
- 无需额外配置，使用 MySQL 或 Redis 持久化后自动生效
> ⚠️ 内存存储不支持多实例部署，每个节点有独立的内存空间，任务无法共享。请在生产环境使用 MySQL 或 Redis 持久化。
---
## 非 Spring Boot 项目
不依赖 Spring，只用核心模块 `lite-delay-core`：
### 1. 引入依赖
```xml
cn.ingrun
lite-delay-core
1.0.4
```
### 2. 初始化 + 注册处理器
```java
public class App {
public static void main(String[] args) {
// 创建任务处理器
TaskHandler handler = new OrderTimeoutHandler();
// 初始化调度引擎（可自定义 Repository / Executor，或使用默认内存实现）
LiteDelay.init(
new TaskRepositoryMemoryImpl(), // 任务存储
new SimpleTaskExecutor(), // 执行器
Collections.singletonList(handler) // 处理器列表
);
}
}
```
### 3. 提交任务
```java
Task task = new Task();
task.setTaskName("订单超时关闭");
task.setRoute("order:pay:timeout");
task.setTriggerTime(System.currentTimeMillis() + 30 * 60 * 1000L); // 30 分钟后
task.setParams(Collections.singletonMap("orderId", "ORDER-123456"));
String taskId = LiteDelay.submit(task);
```
### 4. 关闭
```java
// 应用退出时关闭调度器，释放线程资源
LiteDelay.shutdown();
```
> 💡 `LiteDelay.init()` 使用 DCL 单例模式，多次调用无副作用。未主动初始化时，第一次调用 `submit()` 会自动以默认配置启动。
---
## 项目结构
```
lite-delay/
├── lite-delay-parent/ # 父模块
│ ├── lite-delay-core/ # 核心模块
│ ├── lite-delay-sb-starter/ # Spring Boot 启动器
│ ├── lite-delay-sb-mysql/ # MySQL 持久化
│ ├── lite-delay-sb-redis/ # Redis 持久化
│ └── lite-delay-sb-web/ # Web 控制台
└── spring-boot-demo/ # 示例项目
├── lite-delay-sb-demo-mysql/ # MySQL 示例
└── lite-delay-sb-demo-redis/ # Redis 示例
```
---
## 版本说明
| 版本 | 说明 |
|------|------|
| 1.0.4 | 添加乐观锁，支持多实例部署，所有节点对等调度防重复执行 |
| 1.0.3 | 支持 MySQL、Redis 持久化，Web 控制台，任务执行记录 |
| 1.0.2 | 支持任务重试、立即执行 |
| 1.0.1 | 支持暂停、恢复任务 |
| 1.0.0 | 初始版本 |
---
## 适用场景
- ✅ 订单超时自动取消
- ✅ 支付超时提醒
- ✅ 会员到期预警
- ✅ 定时数据同步
- ✅ 延迟消息通知
- ✅ 任务重试机制
---
## 不适用场景
- ❌ 高并发场景（建议使用 RabbitMQ、Kafka 等消息队列）
- ❌ 需要消息可靠性保障的场景
---
## 规划中
- [ ] **Spring Boot 3.x 适配** — sb3-starter 模块完善
- [x] **多实例部署** — 乐观锁 CAS 防重复执行，零通信对等调度
- [ ] **Cron 表达式支持** — 支持周期性任务调度
- [ ] **任务优先级** — 支持任务优先级配置
---
## 许可证
[MIT License](LICENSE)