contract-manager/.trae/rules/tasker_implementation_guide.md

Tasker实现规范指南

1. Tasker架构概述

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

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

2. 服务器端Tasker实现规范

2.1 基本结构

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

@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实现应遵循：

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示例

@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块中关闭资源