# 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-04-23
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# LiteDelay
> 轻量级延迟任务调度框架，零外部中间件依赖，嵌入式部署，开箱即用。
[](https://www.oracle.com/java/)
[](https://spring.io/projects/spring-boot)
[]()
---
## 简介
LiteDelay 是一个轻量级延迟任务调度框架，适用于**任务量不大、不值得引入重型中间件**的场景——比如订单超时关闭、待办超时提醒、会员到期预警等日常业务需求。
**如果任务量大、并发高，RabbitMQ 依然是最佳选择。**
---
## 特性
- **零中间件依赖** — 核心模块纯 Java 实现，不依赖 Redis、MQ 等任何中间件
- **嵌入式部署** — 与主项目一体部署，无需单独搭建和维护额外服务
- **毫秒级精度** — 基于有序任务队列 + 精确等待，无空转轮询
- **可插拔架构** — 存储器、执行器均有标准接口，按需引入，按需替换
- **Web 控制台** — 可视化任务管理界面，支持任务提交、查询、统计、操作
---
## 快速开始（Spring Boot 2.x）
### 1. 引入依赖
**基础依赖（自动装配）：**
```xml
cn.ingrun
lite-delay-sb-starter
1.0.0
```
**持久化依赖（二选一）：**
> 默认使用内存存储，应用重启后任务丢失。
>
[MySQL](#mysql-持久化可选)：
```xml
cn.ingrun
lite-delay-sb-mysql
${version}
```
[Redis](#redis-持久化可选)：
```xml
cn.ingrun
lite-delay-sb-redis
${version}
```
### 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) {
// 推荐格式：group:model:action
return "order:pay:timeout".equals(route);
}
@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);
```
### 4. 任务管理
```java
LiteDelay.cancel(taskId); // 取消任务（WAITING / PAUSE 状态可取消）
LiteDelay.pause(taskId); // 暂停任务
LiteDelay.resume(taskId); // 恢复任务
LiteDelay.getTask(taskId); // 查询任务
LiteDelay.retry(taskId); // 重试失败任务（ERROR 状态，立即执行）
LiteDelay.retry(taskId, 5000); // 重试失败任务，延迟 5 秒后再执行
LiteDelay.executeNow(taskId); // 立即执行（跳过等待时间，WAITING 状态有效）
```
---
> ⚠️ 执行失败时框架记录错误日志，**不自动重试**（避免业务逻辑重复执行）。
> 重试需通过 `LiteDelay.retry(taskId)` 手动触发。
---
## 非 Spring Boot 项目
不依赖 Spring，只用核心模块 `lite-delay-core`：
### 1. 引入依赖
```xml
cn.ingrun
lite-delay-core
```
### 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()` 会自动以默认配置启动。
---
## Mysql 持久化（可选）
1. 引入依赖
```xml
cn.ingrun
lite-delay-sb-mysql
${version}
```
2. 执行建表脚本（`lite-delay-sb-mysql/src/main/resources/sql/schema.sql`）：
```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，支持高性能批量查询。
引入依赖后，配置 Redis 连接即可自动生效：
```xml
cn.ingrun
lite-delay-sb-redis
${version}
```
## WEB 监控面板（可选）
引入依赖后，访问：`http://localhost:8080/litedelay/`
```xml
cn.ingrun
lite-delay-sb-web
${version}
```
---
## 规划中
- [ ] **Spring Boot 3.x 适配** — sb3-starter 模块完善
- [x] **Web 监控面板** — 任务查询、手动操作、统计分析的可视化界面 ✅
- [ ] **多实例部署** — 分布式选主机制，支持集群部署