# task-scheduler-sdk

**Repository Path**: AhGeng/task-scheduler-sdk

## Basic Information

- **Project Name**: task-scheduler-sdk
- **Description**: 初始化
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-03
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

```
# 🧠 Task Scheduler SDK 使用文档

> 本 SDK 提供了一套轻量级异步任务调度能力，支持本地执行（Local）与远程执行（Remote）两种模式。适用于需要快速构建、提交并消费任务的场景。

---

## 📦 功能概览

| 功能 | 描述 |
|------|------|
| ✅ **本地任务** | 支持 lambda 回调、即时执行、线程池调度 |
| ✅ **远程任务** | 基于 Redisson 实现分布式队列，支持延迟、持久化、重试机制 |
| ✅ **任务模型** | 泛化任务结构，支持任意类型任务定义 |
| ✅ **回调机制** | 支持成功/失败回调，支持 Spring 全局监听器 |
| ✅ **Spring Boot 自动装配** | 开箱即用，自动注册执行器、配置 Redisson |

---

## 🧱 核心组件说明

| 组件                           | 职责 |
|------------------------------|------|
| `GenericTask`                | 任务模型类，定义任务参数、执行器、回调等 |
| `TaskExecutor`               | 执行器接口，由用户实现具体业务逻辑 |
| `TaskService`                | 对外任务提交接口 |
| `RedissonTaskQueueService`   | 远程任务服务，基于 Redisson 队列实现 |
| `LocalTaskQueueService`      | 本地任务服务，适合开发调试 |
| `HybridTaskService`          | 混合任务服务，根据 executionMode 自动路由 |
| `TaskEventHandlerRegistrar`  | 注册全局事件回调（onSuccess/onFailure） |
| `TaskEvent`                  | Spring 事件对象，用于通知任务执行结果 |
```

## 🚀 快速开始

### 1. 引入依赖（Maven）

```xml
<dependency>
    <groupId>com.task.scheduler</groupId>
    <artifactId>task-scheduler-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

---

### 2. 配置Redis（application.yml）

```yaml
task:
  scheduler:
    redisson:
      host: 127.0.0.1
      port: 6379
      password: ""
```

---

### 3. 构建并提交任务

#### ✅ 方式一：本地任务（Lambda 回调）

```java
GenericTask task = GenericTask.localTask()
    .taskType("HTTP")
    .jsonParams("{\"url\": \"http://api.example.com\"}")
    .executor((t) -> "{ \"code\": 0 }")
    .onSuccess((t, r) -> System.out.println("本地成功：" + r))
    .onFailure((t, e) -> System.err.println("本地失败：" + e.getMessage()))
    .build();
taskService.submit(task);
```

#### ✅ 方式二：远程任务（通过 Redisson 队列）

##### 定义执行器

```java
@Component
@TaskType("HTTP")
public class HttpTaskExecutor implements TaskExecutor {

    @Override
    public String execute(GenericTask task) {
        System.out.println("远程调用！🚀 HTTP 任务被触发！");
        System.out.println("任务类型: " + task.getTaskType());
        System.out.println("参数内容: " + task.getJsonParams());
        return "{\"code\":0, \"msg\":\"http success\"}";
    }
}
```

##### 定义全局回调（可选）

```java
@Component
public class HttpTaskHandler {
    
    public HttpTaskHandler(TaskEventHandlerRegistrar registrar) {
        registrar.onSuccess("HTTP", this::handleHttpSuccess);
        registrar.onFailure("HTTP", this::handleHttpFailure);
    }

    private void handleHttpSuccess(GenericTask task, String result) {
        System.out.println("✅ HTTP 任务成功：" + result);
    }

    private void handleHttpFailure(GenericTask task, Exception e) {
        System.err.println("❌ HTTP 任务失败：" + e.getMessage());
    }
}
```

##### 提交远程任务

```java
GenericTask task = GenericTask.remoteTask()
    .taskType("HTTP")
    .jsonParams("{\"url\": \"http://api.example.com\"}")
    .maxRetry(3)
    .delaySeconds(10)
    .build();
taskService.submit(task);
```

---

## 📐 任务执行流程图

```
+-------------------+
| 用户提交任务       |
| taskService.submit()|
+-------------------+
|
v
+------------------------+
| 判断 executionMode      |
| Local → LocalQueue      |
| Remote → RedissonQueue  |
+------------------------+
|
v
+------------------------+
| 消费任务               |
| Redisson / 线程池      |
+------------------------+
|
v
+------------------------+
| 执行任务               |
| executor.execute(task) |
+------------------------+
|
+-----+-------+
|             |
+----+ Success +----+    +----+ Failed +----+
| 触发 onSuccess 回调 |    | 触发 onFailure 回调 |
| 或发布 TaskEvent 事件 |    | 或发布 TaskEvent 事件 |
+--------------------+    +---------------------+
```

---

## ⚙️ 任务字段说明

| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| taskId | String | 否 | 默认 UUID，可用于幂等性控制 |
| taskType | String | 是 | 用于匹配执行器 |
| jsonParams | String | 是 | 任务参数（JSON 格式） |
| maxRetry | int | 否 | 最大重试次数，默认 3 |
| delaySeconds | long | 否 | 延迟执行时间（秒） |
| executor | TaskExecutor | 本地必填 | 不参与远程传输 |
| onSuccess | BiConsumer | 本地可选 | 不参与远程传输 |
| onFailure | BiConsumer | 本地可选 | 不参与远程传输 |
| executionMode | TaskExecutionMode | 是 | LOCAL / REMOTE |

---

## 📋 配置说明（application.yml）

```yaml
task:
  scheduler:
    redisson:
      host: 127.0.0.1
      port: 6379
      password: ""
```

---

## 📈 运行时行为对比表

| 行为 | 本地任务（LOCAL） | 远程任务（REMOTE） |
|------|------------------|-------------------|
| 是否支持 lambda 回调 | ✅ 是 | ❌ 否 |
| 是否跨 JVM 执行 | ❌ 否 | ✅ 是 |
| 是否持久化任务 | ❌ 否 | ✅ 是（Redisson 队列） |
| 是否支持重试 | ✅ 是 | ✅ 是 |
| 是否触发 Spring 事件 | ❌ 否 | ✅ 是 |
| 是否必须指定 executor | ✅ 是 | ❌ 否（自动注册 Bean） |

---

## 📚 最佳实践建议

| 场景 | 推荐使用方式 |
|------|--------------|
| 快速响应、单机部署 | ✅ 本地任务（LOCAL） |
| 微服务架构、高可用需求 | ✅ 远程任务（REMOTE） |
| Lambda 回调验证 | ✅ 本地任务 |
| 分布式任务调度 | ✅ 远程任务 |
| 开发测试环境 | ✅ 本地任务 |
| 生产环境 | ✅ 远程任务 |

---

## 🧪 注意事项与限制

| 注意事项 | 说明                    |
|----------|-----------------------|
| ❗ Lambda 回调无法远程传输 | 仅在本地任务中有效             |
| ❗ 本地任务无持久化 | 重启后丢失                 |
| ❗ 远程任务不能设置回调 | 只能通过配置的方式进行匹配         |
| ❗ 本地任务不能自动匹配执行器 | 必须显式 `.executor(...)` |
| ❗ 重试策略统一配置 | 可扩展为按任务类型定制           |

---

## 🧩 设计模式与原则

| 模式 | 说明 |
|------|------|
| ✅ 观察者模式 | Spring ApplicationEventPublisher |
| ✅ 策略模式 | 根据 taskType 匹配执行器 |
| ✅ 发布-订阅模式 | TaskEvent + 多个监听器响应 |
| ✅ 工厂模式 | GenericTask.builder() / localTask() / remoteTask() |
| ✅ 单一职责原则 | 每个类只负责一个核心功能 |
| ✅ 开闭原则 | 新增任务不需修改已有代码 |
| ✅ 依赖倒置原则 | 面向接口编程，解耦实现细节 |

---

## 🔧 未来扩展

| 扩展方向 | 方案                              |
|----------|---------------------------------|
| 💡 死信队列 | 添加失败次数上限后的落库/落盘机制               |
| 💡 任务优先级 | 支持多队列、不同优先级处理                   |
| 💡 监控埋点 | 使用 Micrometer 或 Prometheus 指标采集 |
| 💡 日志增强 | 在关键节点添加 traceId、日志上下文           |
| 💡 任务取消 | 支持主动取消未执行任务                     |

---