up

2025-11-26 16:10:17 +08:00
parent f0e85c5a18
commit c10bd369c0
83 changed files with 1755 additions and 541 deletions
--- a/.trae/rules/tasker_implementation_guide.md
+++ b/.trae/rules/tasker_implementation_guide.md
@@ -0,0 +1,182 @@
+# 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块中关闭资源