# Tasker实现规范指南

## 1. Tasker架构概述

Tasker是系统中用于执行异步任务的核心框架，主要用于处理耗时操作并提供实时进度反馈。Tasker架构包括：

- **Tasker基类**：提供任务执行的基础框架和通信功能
- **WebSocketServerTasker接口**：定义WebSocket通信任务的规范
- **MessageHolder**：用于在任务执行过程中传递消息和更新进度

## 2. 服务器端Tasker实现规范

### 2.1 基本结构

服务器端Tasker实现应遵循以下结构：

```java
@Data
@EqualsAndHashCode(callSuper = true)
public class YourTaskNameTask extends Tasker<Object> implements WebSocketServerTasker {
    // 服务依赖
    @Setter
    private YourService service;
    
    @Override
    public void init(JsonNode argsNode) {
        // 初始化任务标题
        updateTitle("任务标题");
        // 初始化参数
    }
    
    @Override
    protected Object execute(MessageHolder holder) throws Exception {
        // 实现业务逻辑
        // 使用holder.info()、holder.error()等方法反馈消息
        return null;
    }
}
```

### 2.2 关键注意事项

1. **继承与实现**：
   - 必须继承`Tasker<Object>`基类
   - 必须实现`WebSocketServerTasker`接口

2. **方法实现**：
   - **不要重复实现**Tasker基类已提供的handler设置方法：`setMessageHandler`、`setTitleHandler`、`setPropertyHandler`、`setProgressHandler`
   - 必须实现`init`方法，设置任务标题和初始化参数
   - 必须实现`execute`方法，实现具体业务逻辑

3. **进度和消息反馈**：
   - 使用`updateProgress`方法提供进度更新
   - 使用`MessageHolder`的`info`、`error`、`debug`等方法提供消息反馈

4. **任务取消**：
   - 在适当的地方检查`isCancelled()`状态，支持任务取消

5. **注册要求**：
   - 任务类必须在`tasker_mapper.json`中注册

## 3. 客户端Tasker实现规范

客户端Tasker实现应遵循：

```java
public class YourTaskNameTask extends Tasker<Object> {
    @Override
    protected Object execute(MessageHolder holder) throws Exception {
        // 客户端任务逻辑
        return null;
    }
}
```

## 4. 通信规范

### 4.1 命名规范

- 客户端和服务器端对应的Tasker类应使用**相同的类名**
- 示例：客户端的`ContractSyncAllTask`对应服务器端的`ContractSyncAllTask`

### 4.2 消息传递

- 使用`MessageHolder`进行消息传递
- 支持不同级别的消息：INFO、ERROR、DEBUG

## 5. 最佳实践

1. **任务拆分**：
   - 将大型任务拆分为多个小任务，提高可维护性

2. **异常处理**：
   - 捕获并正确处理异常，使用`holder.error()`提供详细错误信息

3. **资源管理**：
   - 确保及时释放资源，特别是在任务取消的情况下

4. **日志记录**：
   - 使用`holder.debug()`记录调试信息
   - 使用`holder.info()`记录进度信息

5. **状态检查**：
   - 定期检查`isCancelled()`状态，确保任务可以被及时取消

## 6. 代码示例

### 6.1 服务器端Tasker示例

```java
@Data
@EqualsAndHashCode(callSuper = true)
public class ExampleSyncTask extends Tasker<Object> implements WebSocketServerTasker {
    @Setter
    private ExampleService exampleService;
    
    @Override
    public void init(JsonNode argsNode) {
        updateTitle("示例同步任务");
        // 从argsNode初始化参数
    }
    
    @Override
    protected Object execute(MessageHolder holder) throws Exception {
        try {
            // 获取总记录数
            long total = exampleService.getTotalCount();
            holder.info("开始同步数据，共" + total + "条记录");
            
            // 分批处理
            long processed = 0;
            List<ExampleEntity> entities = exampleService.getAllEntities();
            
            for (ExampleEntity entity : entities) {
                // 检查是否取消
                if (isCancelled()) {
                    holder.info("任务已取消");
                    return null;
                }
                
                // 处理单个实体
                exampleService.processEntity(entity);
                processed++;
                
                // 更新进度
                updateProgress(processed, total);
                if (processed % 100 == 0) {
                    holder.info("已处理" + processed + "/" + total + "条记录");
                }
            }
            
            holder.info("同步完成，共处理" + processed + "条记录");
            return processed;
        } catch (Exception e) {
            holder.error("同步失败: " + e.getMessage());
            throw e;
        }
    }
}
```

## 7. 常见错误和避免方法

1. **重复实现handler方法**：
   - 错误：在子类中重复实现setMessageHandler等方法
   - 解决：删除子类中的这些方法，直接使用Tasker基类提供的实现

2. **缺少任务注册**：
   - 错误：任务类没有在tasker_mapper.json中注册
   - 解决：确保所有服务器端Tasker类都在配置文件中正确注册

3. **类名不匹配**：
   - 错误：客户端和服务器端Tasker类名不一致
   - 解决：确保两端使用相同的类名

4. **进度更新不正确**：
   - 错误：进度计算错误或没有更新
   - 解决：正确计算和更新进度，提高用户体验

5. **资源泄漏**：
   - 错误：未及时关闭数据库连接等资源
   - 解决：使用try-with-resources或在finally块中关闭资源