在实际项目开发中尤其是涉及复杂业务流程、数据流转或多人协作的场景我们经常需要记录每个关键步骤的执行状态、输入输出、耗时和异常信息。这种“技能实战记录”机制不仅能帮助排查问题还能用于审计、监控和性能分析。标题中的“74-Skill”可能指代某个具体项目编号或技能分类但核心需求是通用的我们需要一套可复用的任务步骤记录方案。本文将围绕如何设计并实现一个高可用的任务步骤记录系统展开涵盖数据模型设计、记录时机选择、存储方案、查询优化和常见问题处理。无论你是需要为工作流引擎添加执行跟踪还是想为批处理任务加入详细日志都可以参考这里的思路和代码。1. 理解任务步骤记录的核心价值任务步骤记录不同于普通日志它更结构化、更面向业务并且通常需要持久化到数据库供后续查询分析。在没有专门记录机制时开发人员往往只能通过散落的日志文件来还原执行过程效率低下且容易遗漏关键信息。1.1 步骤记录应该包含哪些信息一个完整的步骤记录至少需要以下字段步骤ID唯一标识符用于区分同一任务的不同步骤任务ID关联到父任务支持任务维度的查询步骤名称业务意义的步骤描述如数据校验、文件下载步骤类型分类步骤如开始、处理、结束、判断执行状态成功、失败、进行中、超时等开始时间精确到毫秒的时间戳结束时间用于计算步骤耗时输入参数步骤执行前的关键参数快照输出结果步骤执行后的结果数据错误信息失败时的异常堆栈或错误描述执行主机在多机环境下标识执行节点1.2 步骤记录的典型应用场景业务流程监控实时查看订单处理、审批流程的当前状态问题排查当任务失败时快速定位到具体失败的步骤和原因性能分析分析各步骤耗时找出瓶颈点进行优化审计合规满足行业监管对关键操作留痕的要求用户反馈向用户展示任务执行进度提升体验2. 设计步骤记录的数据模型基于上述需求我们设计数据库表结构。以下以MySQL为例其他数据库类型可相应调整。2.1 核心表结构设计CREATE TABLE task_step_record ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 主键ID, task_id VARCHAR(64) NOT NULL COMMENT 任务ID业务唯一标识, step_id VARCHAR(128) NOT NULL COMMENT 步骤ID任务内唯一, step_name VARCHAR(256) NOT NULL COMMENT 步骤名称, step_type VARCHAR(64) NOT NULL DEFAULT PROCESS COMMENT 步骤类型START/PROCESS/JUDGE/END, execute_status VARCHAR(32) NOT NULL DEFAULT RUNNING COMMENT 执行状态RUNNING/SUCCESS/FAILED/TIMEOUT, start_time DATETIME(3) NOT NULL COMMENT 开始时间精确到毫秒, end_time DATETIME(3) COMMENT 结束时间, input_params JSON COMMENT 输入参数JSON, output_result JSON COMMENT 输出结果JSON, error_message TEXT COMMENT 错误信息, execute_host VARCHAR(128) COMMENT 执行主机标识, cost_time INT COMMENT 耗时单位毫秒, create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), update_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), INDEX idx_task_id (task_id), INDEX idx_step_id (step_id), INDEX idx_create_time (create_time), INDEX idx_status (execute_status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT任务步骤记录表;2.2 关键字段设计说明任务ID和步骤ID的组合索引设计task_id和step_id需要建立组合索引但顺序很重要。由于我们更多是按任务维度查询所有步骤所以将task_id放在前面ALTER TABLE task_step_record ADD INDEX idx_task_step (task_id, step_id);JSON字段的使用考虑MySQL 5.7支持JSON类型便于存储结构化数据。如果使用较低版本或希望更好的查询性能可以考虑将常用查询字段提取出来单独存储。时间字段的精度选择使用DATETIME(3)支持毫秒精度这对于性能分析很重要。如果数据量很大可以考虑按时间分表。3. 实现步骤记录的核心组件下面我们通过Java代码实现一个可复用的步骤记录组件。采用Spring Boot框架便于集成到现有项目中。3.1 定义步骤记录实体类Data Entity Table(name task_step_record) org.hibernate.annotations.DynamicInsert org.hibernate.annotations.DynamicUpdate public class TaskStepRecord { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(name task_id, length 64, nullable false) private String taskId; Column(name step_id, length 128, nullable false) private String stepId; Column(name step_name, length 256, nullable false) private String stepName; Column(name step_type, length 64, nullable false) private String stepType PROCESS; Column(name execute_status, length 32, nullable false) private String executeStatus RUNNING; Column(name start_time, nullable false) private LocalDateTime startTime; Column(name end_time) private LocalDateTime endTime; Column(name input_params, columnDefinition json) Convert(converter JsonConverter.class) private MapString, Object inputParams; Column(name output_result, columnDefinition json) Convert(converter JsonConverter.class) private MapString, Object outputResult; Column(name error_message) private String errorMessage; Column(name execute_host, length 128) private String executeHost; Column(name cost_time) private Integer costTime; Column(name create_time, nullable false) private LocalDateTime createTime; Column(name update_time, nullable false) private LocalDateTime updateTime; }3.2 JSON转换器实现Converter public class JsonConverter implements AttributeConverterMapString, Object, String { private static final ObjectMapper objectMapper new ObjectMapper(); Override public String convertToDatabaseColumn(MapString, Object attribute) { try { return objectMapper.writeValueAsString(attribute); } catch (JsonProcessingException e) { throw new RuntimeException(JSON转换失败, e); } } Override public MapString, Object convertToEntityAttribute(String dbData) { if (dbData null || dbData.trim().isEmpty()) { return new HashMap(); } try { return objectMapper.readValue(dbData, new TypeReferenceMapString, Object() {}); } catch (JsonProcessingException e) { throw new RuntimeException(JSON解析失败, e); } } }3.3 步骤记录服务类Service Slf4j public class TaskStepRecordService { Autowired private TaskStepRecordRepository recordRepository; Autowired private ApplicationContext applicationContext; /** * 开始记录一个步骤 */ public TaskStepRecord startStep(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { TaskStepRecord record new TaskStepRecord(); record.setTaskId(taskId); record.setStepId(stepId); record.setStepName(stepName); record.setStepType(stepType); record.setExecuteStatus(RUNNING); record.setStartTime(LocalDateTime.now()); record.setInputParams(inputParams); record.setExecuteHost(getHostName()); return recordRepository.save(record); } /** * 成功完成步骤 */ public void completeStepSuccess(TaskStepRecord record, MapString, Object outputResult) { completeStep(record, SUCCESS, outputResult, null); } /** * 步骤执行失败 */ public void completeStepFailed(TaskStepRecord record, String errorMessage) { completeStep(record, FAILED, null, errorMessage); } /** * 步骤执行失败带异常 */ public void completeStepFailed(TaskStepRecord record, Exception exception) { String errorMessage ExceptionUtils.getStackTrace(exception); completeStep(record, FAILED, null, errorMessage); } private void completeStep(TaskStepRecord record, String status, MapString, Object outputResult, String errorMessage) { record.setExecuteStatus(status); record.setEndTime(LocalDateTime.now()); record.setOutputResult(outputResult); record.setErrorMessage(errorMessage); // 计算耗时 Duration duration Duration.between(record.getStartTime(), record.getEndTime()); record.setCostTime((int) duration.toMillis()); recordRepository.save(record); } private String getHostName() { try { return InetAddress.getLocalHost().getHostName(); } catch (UnknownHostException e) { return unknown; } } /** * 查询任务的所有步骤记录 */ public ListTaskStepRecord getStepsByTaskId(String taskId) { return recordRepository.findByTaskIdOrderByStartTimeAsc(taskId); } /** * 查询步骤详情 */ public OptionalTaskStepRecord getStepDetail(String taskId, String stepId) { return recordRepository.findByTaskIdAndStepId(taskId, stepId); } }3.4 仓库接口定义Repository public interface TaskStepRecordRepository extends JpaRepositoryTaskStepRecord, Long { ListTaskStepRecord findByTaskIdOrderByStartTimeAsc(String taskId); OptionalTaskStepRecord findByTaskIdAndStepId(String taskId, String stepId); Query(SELECT r FROM TaskStepRecord r WHERE r.taskId :taskId AND r.executeStatus :status) ListTaskStepRecord findByTaskIdAndStatus(Param(taskId) String taskId, Param(status) String status); }4. 在实际业务中集成步骤记录有了基础组件后我们看看如何在实际业务代码中使用。以下以一个文件处理任务为例。4.1 定义任务步骤枚举public enum FileProcessStep { START(start, 开始处理, START), VALIDATE_FILE(validate, 文件校验, PROCESS), PARSE_CONTENT(parse, 内容解析, PROCESS), TRANSFORM_DATA(transform, 数据转换, PROCESS), SAVE_RESULT(save, 结果保存, PROCESS), END(end, 处理完成, END); private final String stepId; private final String stepName; private final String stepType; FileProcessStep(String stepId, String stepName, String stepType) { this.stepId stepId; this.stepName stepName; this.stepType stepType; } // getters... }4.2 业务处理类示例Service Slf4j public class FileProcessService { Autowired private TaskStepRecordService recordService; public void processFile(String taskId, String filePath) { TaskStepRecord currentStep null; try { // 步骤1: 开始处理 MapString, Object startInput new HashMap(); startInput.put(filePath, filePath); startInput.put(taskId, taskId); currentStep recordService.startStep(taskId, FileProcessStep.START.getStepId(), FileProcessStep.START.getStepName(), FileProcessStep.START.getStepType(), startInput); // 步骤2: 文件校验 currentStep executeValidateStep(taskId, filePath); // 步骤3: 内容解析 currentStep executeParseStep(taskId, filePath); // 步骤4: 数据转换 currentStep executeTransformStep(taskId, currentStep); // 步骤5: 结果保存 executeSaveStep(taskId, currentStep); // 步骤6: 处理完成 recordFinalStep(taskId); } catch (Exception e) { log.error(文件处理失败, taskId: {}, taskId, e); if (currentStep ! null) { recordService.completeStepFailed(currentStep, e); } throw new RuntimeException(文件处理失败, e); } } private TaskStepRecord executeValidateStep(String taskId, String filePath) { MapString, Object input new HashMap(); input.put(filePath, filePath); TaskStepRecord step recordService.startStep(taskId, FileProcessStep.VALIDATE_FILE.getStepId(), FileProcessStep.VALIDATE_FILE.getStepName(), FileProcessStep.VALIDATE_FILE.getStepType(), input); try { // 实际校验逻辑 File file new File(filePath); if (!file.exists()) { throw new RuntimeException(文件不存在: filePath); } if (file.length() 0) { throw new RuntimeException(文件内容为空); } MapString, Object output new HashMap(); output.put(fileSize, file.length()); output.put(lastModified, file.lastModified()); recordService.completeStepSuccess(step, output); return step; } catch (Exception e) { recordService.completeStepFailed(step, e); throw e; } } // 其他步骤方法类似... }5. 步骤记录的查询与监控记录步骤数据后我们需要提供查询接口和监控面板。这里给出几个关键查询示例。5.1 任务执行详情查询RestController RequestMapping(/api/task-steps) public class TaskStepController { Autowired private TaskStepRecordService recordService; /** * 获取任务执行详情 */ GetMapping(/{taskId}) public ApiResponseTaskDetailVO getTaskDetail(PathVariable String taskId) { ListTaskStepRecord steps recordService.getStepsByTaskId(taskId); TaskDetailVO detail new TaskDetailVO(); detail.setTaskId(taskId); detail.setSteps(steps.stream().map(this::convertToVO).collect(Collectors.toList())); // 计算总体状态和耗时 calculateOverallStatus(detail); return ApiResponse.success(detail); } private TaskStepVO convertToVO(TaskStepRecord record) { TaskStepVO vo new TaskStepVO(); vo.setStepId(record.getStepId()); vo.setStepName(record.getStepName()); vo.setStepType(record.getStepType()); vo.setExecuteStatus(record.getExecuteStatus()); vo.setStartTime(record.getStartTime()); vo.setEndTime(record.getEndTime()); vo.setCostTime(record.getCostTime()); vo.setErrorMessage(record.getErrorMessage()); return vo; } private void calculateOverallStatus(TaskDetailVO detail) { if (detail.getSteps().isEmpty()) { detail.setOverallStatus(UNKNOWN); return; } boolean hasRunning detail.getSteps().stream() .anyMatch(s - RUNNING.equals(s.getExecuteStatus())); boolean hasFailed detail.getSteps().stream() .anyMatch(s - FAILED.equals(s.getExecuteStatus())); if (hasRunning) { detail.setOverallStatus(RUNNING); } else if (hasFailed) { detail.setOverallStatus(FAILED); } else { detail.setOverallStatus(SUCCESS); } // 计算总耗时 LocalDateTime start detail.getSteps().get(0).getStartTime(); LocalDateTime end detail.getSteps().get(detail.getSteps().size() - 1).getEndTime(); if (start ! null end ! null) { detail.setTotalCostTime(Duration.between(start, end).toMillis()); } } }5.2 监控统计查询-- 今日任务执行统计 SELECT execute_status, COUNT(*) as count, AVG(cost_time) as avg_cost FROM task_step_record WHERE DATE(create_time) CURDATE() GROUP BY execute_status; -- 最近一小时内各步骤平均耗时 SELECT step_name, AVG(cost_time) as avg_cost, COUNT(*) as execute_count FROM task_step_record WHERE create_time DATE_SUB(NOW(), INTERVAL 1 HOUR) GROUP BY step_name ORDER BY avg_cost DESC;6. 性能优化与生产环境建议当步骤记录数据量增大时需要考虑性能优化问题。6.1 数据库优化策略分区表设计如果数据量很大比如日均百万记录建议按时间分区CREATE TABLE task_step_record ( -- 字段定义同上 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 PARTITION BY RANGE (YEAR(create_time)*100 MONTH(create_time)) ( PARTITION p202401 VALUES LESS THAN (202402), PARTITION p202402 VALUES LESS THAN (202403), PARTITION p202403 VALUES LESS THAN (202404), PARTITION p_max VALUES LESS THAN MAXVALUE );索引优化除了基本索引外根据查询模式添加组合索引-- 用于监控统计查询 ALTER TABLE task_step_record ADD INDEX idx_status_time (execute_status, create_time); -- 用于步骤耗时分析 ALTER TABLE task_step_record ADD INDEX idx_step_cost (step_id, cost_time);6.2 异步记录机制对于高频任务同步记录可能影响性能。可以采用异步方式Service Slf4j public class AsyncTaskStepRecordService { Autowired private TaskStepRecordService recordService; Async(taskStepExecutor) public void recordStepAsync(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { try { recordService.startStep(taskId, stepId, stepName, stepType, inputParams); } catch (Exception e) { log.error(异步记录步骤失败, e); } } Async(taskStepExecutor) public void completeStepAsync(TaskStepRecord record, String status, MapString, Object outputResult, String errorMessage) { try { recordService.completeStep(record, status, outputResult, errorMessage); } catch (Exception e) { log.error(异步完成步骤失败, e); } } }配置线程池spring: task: execution: pool: core-size: 5 max-size: 20 queue-capacity: 1000 thread-name-prefix: task-step-async-7. 常见问题与排查指南在实际使用中可能会遇到以下典型问题。7.1 步骤记录丢失问题现象任务执行了但数据库中没有对应的步骤记录。排查步骤检查数据库连接是否正常查看应用日志是否有异常堆栈确认任务ID生成规则避免重复或空值检查异步记录时线程池是否饱和解决方案// 添加记录失败的重试机制 Retryable(value Exception.class, maxAttempts 3, backoff Backoff(delay 1000)) public TaskStepRecord startStepWithRetry(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { return recordService.startStep(taskId, stepId, stepName, stepType, inputParams); }7.2 步骤状态不一致问题现象步骤显示为RUNNING状态但实际已经执行完成。排查步骤检查是否有异常导致complete方法未执行确认事务边界避免事务回滚导致状态更新失败检查网络超时或应用重启情况解决方案// 添加状态补偿机制 Scheduled(fixedRate 300000) // 5分钟执行一次 public void compensateTimeoutSteps() { LocalDateTime timeoutThreshold LocalDateTime.now().minusMinutes(10); ListTaskStepRecord timeoutSteps recordRepository .findByExecuteStatusAndStartTimeBefore(RUNNING, timeoutThreshold); for (TaskStepRecord step : timeoutSteps) { step.setExecuteStatus(TIMEOUT); step.setErrorMessage(步骤执行超时系统自动标记); step.setEndTime(LocalDateTime.now()); recordRepository.save(step); log.warn(补偿超时步骤: taskId{}, stepId{}, step.getTaskId(), step.getStepId()); } }7.3 数据量过大导致查询慢现象查询任务历史时响应很慢。解决方案建立合适的数据归档策略添加查询条件限制如时间范围对历史数据建立只读副本-- 每月初归档上上月数据到历史表 INSERT INTO task_step_record_history SELECT * FROM task_step_record WHERE create_time DATE_SUB(CURDATE(), INTERVAL 2 MONTH); DELETE FROM task_step_record WHERE create_time DATE_SUB(CURDATE(), INTERVAL 2 MONTH);8. 最佳实践总结基于多个项目的实践经验总结以下最佳实践8.1 步骤粒度控制步骤不是越细越好要平衡可观测性和性能开销关键决策点必须记录步骤耗时操作必须记录步骤如外部API调用、大数据量处理可能失败的操作必须记录步骤简单内存操作可以合并步骤8.2 参数记录策略输入输出参数记录要兼顾信息量和隐私安全记录关键业务ID不要记录完整业务对象敏感信息密码、密钥必须脱敏大数据量字段记录摘要而非完整内容使用JSON格式便于后续查询分析8.3 监控告警配置建立关键监控指标步骤失败率超过阈值告警步骤平均耗时异常增长告警长时间RUNNING状态的步骤告警记录失败率监控反映系统健康度8.4 版本兼容考虑当业务逻辑变更时步骤记录可能需要适应新增步骤类型时保持向后兼容步骤ID变更时考虑数据迁移方案保留历史步骤记录的查询能力文档化步骤变更历史通过这套完整的任务步骤记录方案我们能够清晰掌握复杂任务的执行全过程快速定位问题优化系统性能。在实际项目中可以根据具体需求调整实现细节但核心的设计思路和最佳实践具有普适性。 高可用任务步骤记录系统设计与实现：从原理到实践
在实际项目开发中尤其是涉及复杂业务流程、数据流转或多人协作的场景我们经常需要记录每个关键步骤的执行状态、输入输出、耗时和异常信息。这种“技能实战记录”机制不仅能帮助排查问题还能用于审计、监控和性能分析。标题中的“74-Skill”可能指代某个具体项目编号或技能分类但核心需求是通用的我们需要一套可复用的任务步骤记录方案。本文将围绕如何设计并实现一个高可用的任务步骤记录系统展开涵盖数据模型设计、记录时机选择、存储方案、查询优化和常见问题处理。无论你是需要为工作流引擎添加执行跟踪还是想为批处理任务加入详细日志都可以参考这里的思路和代码。1. 理解任务步骤记录的核心价值任务步骤记录不同于普通日志它更结构化、更面向业务并且通常需要持久化到数据库供后续查询分析。在没有专门记录机制时开发人员往往只能通过散落的日志文件来还原执行过程效率低下且容易遗漏关键信息。1.1 步骤记录应该包含哪些信息一个完整的步骤记录至少需要以下字段步骤ID唯一标识符用于区分同一任务的不同步骤任务ID关联到父任务支持任务维度的查询步骤名称业务意义的步骤描述如数据校验、文件下载步骤类型分类步骤如开始、处理、结束、判断执行状态成功、失败、进行中、超时等开始时间精确到毫秒的时间戳结束时间用于计算步骤耗时输入参数步骤执行前的关键参数快照输出结果步骤执行后的结果数据错误信息失败时的异常堆栈或错误描述执行主机在多机环境下标识执行节点1.2 步骤记录的典型应用场景业务流程监控实时查看订单处理、审批流程的当前状态问题排查当任务失败时快速定位到具体失败的步骤和原因性能分析分析各步骤耗时找出瓶颈点进行优化审计合规满足行业监管对关键操作留痕的要求用户反馈向用户展示任务执行进度提升体验2. 设计步骤记录的数据模型基于上述需求我们设计数据库表结构。以下以MySQL为例其他数据库类型可相应调整。2.1 核心表结构设计CREATE TABLE task_step_record ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 主键ID, task_id VARCHAR(64) NOT NULL COMMENT 任务ID业务唯一标识, step_id VARCHAR(128) NOT NULL COMMENT 步骤ID任务内唯一, step_name VARCHAR(256) NOT NULL COMMENT 步骤名称, step_type VARCHAR(64) NOT NULL DEFAULT PROCESS COMMENT 步骤类型START/PROCESS/JUDGE/END, execute_status VARCHAR(32) NOT NULL DEFAULT RUNNING COMMENT 执行状态RUNNING/SUCCESS/FAILED/TIMEOUT, start_time DATETIME(3) NOT NULL COMMENT 开始时间精确到毫秒, end_time DATETIME(3) COMMENT 结束时间, input_params JSON COMMENT 输入参数JSON, output_result JSON COMMENT 输出结果JSON, error_message TEXT COMMENT 错误信息, execute_host VARCHAR(128) COMMENT 执行主机标识, cost_time INT COMMENT 耗时单位毫秒, create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), update_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), INDEX idx_task_id (task_id), INDEX idx_step_id (step_id), INDEX idx_create_time (create_time), INDEX idx_status (execute_status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT任务步骤记录表;2.2 关键字段设计说明任务ID和步骤ID的组合索引设计task_id和step_id需要建立组合索引但顺序很重要。由于我们更多是按任务维度查询所有步骤所以将task_id放在前面ALTER TABLE task_step_record ADD INDEX idx_task_step (task_id, step_id);JSON字段的使用考虑MySQL 5.7支持JSON类型便于存储结构化数据。如果使用较低版本或希望更好的查询性能可以考虑将常用查询字段提取出来单独存储。时间字段的精度选择使用DATETIME(3)支持毫秒精度这对于性能分析很重要。如果数据量很大可以考虑按时间分表。3. 实现步骤记录的核心组件下面我们通过Java代码实现一个可复用的步骤记录组件。采用Spring Boot框架便于集成到现有项目中。3.1 定义步骤记录实体类Data Entity Table(name task_step_record) org.hibernate.annotations.DynamicInsert org.hibernate.annotations.DynamicUpdate public class TaskStepRecord { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(name task_id, length 64, nullable false) private String taskId; Column(name step_id, length 128, nullable false) private String stepId; Column(name step_name, length 256, nullable false) private String stepName; Column(name step_type, length 64, nullable false) private String stepType PROCESS; Column(name execute_status, length 32, nullable false) private String executeStatus RUNNING; Column(name start_time, nullable false) private LocalDateTime startTime; Column(name end_time) private LocalDateTime endTime; Column(name input_params, columnDefinition json) Convert(converter JsonConverter.class) private MapString, Object inputParams; Column(name output_result, columnDefinition json) Convert(converter JsonConverter.class) private MapString, Object outputResult; Column(name error_message) private String errorMessage; Column(name execute_host, length 128) private String executeHost; Column(name cost_time) private Integer costTime; Column(name create_time, nullable false) private LocalDateTime createTime; Column(name update_time, nullable false) private LocalDateTime updateTime; }3.2 JSON转换器实现Converter public class JsonConverter implements AttributeConverterMapString, Object, String { private static final ObjectMapper objectMapper new ObjectMapper(); Override public String convertToDatabaseColumn(MapString, Object attribute) { try { return objectMapper.writeValueAsString(attribute); } catch (JsonProcessingException e) { throw new RuntimeException(JSON转换失败, e); } } Override public MapString, Object convertToEntityAttribute(String dbData) { if (dbData null || dbData.trim().isEmpty()) { return new HashMap(); } try { return objectMapper.readValue(dbData, new TypeReferenceMapString, Object() {}); } catch (JsonProcessingException e) { throw new RuntimeException(JSON解析失败, e); } } }3.3 步骤记录服务类Service Slf4j public class TaskStepRecordService { Autowired private TaskStepRecordRepository recordRepository; Autowired private ApplicationContext applicationContext; /** * 开始记录一个步骤 */ public TaskStepRecord startStep(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { TaskStepRecord record new TaskStepRecord(); record.setTaskId(taskId); record.setStepId(stepId); record.setStepName(stepName); record.setStepType(stepType); record.setExecuteStatus(RUNNING); record.setStartTime(LocalDateTime.now()); record.setInputParams(inputParams); record.setExecuteHost(getHostName()); return recordRepository.save(record); } /** * 成功完成步骤 */ public void completeStepSuccess(TaskStepRecord record, MapString, Object outputResult) { completeStep(record, SUCCESS, outputResult, null); } /** * 步骤执行失败 */ public void completeStepFailed(TaskStepRecord record, String errorMessage) { completeStep(record, FAILED, null, errorMessage); } /** * 步骤执行失败带异常 */ public void completeStepFailed(TaskStepRecord record, Exception exception) { String errorMessage ExceptionUtils.getStackTrace(exception); completeStep(record, FAILED, null, errorMessage); } private void completeStep(TaskStepRecord record, String status, MapString, Object outputResult, String errorMessage) { record.setExecuteStatus(status); record.setEndTime(LocalDateTime.now()); record.setOutputResult(outputResult); record.setErrorMessage(errorMessage); // 计算耗时 Duration duration Duration.between(record.getStartTime(), record.getEndTime()); record.setCostTime((int) duration.toMillis()); recordRepository.save(record); } private String getHostName() { try { return InetAddress.getLocalHost().getHostName(); } catch (UnknownHostException e) { return unknown; } } /** * 查询任务的所有步骤记录 */ public ListTaskStepRecord getStepsByTaskId(String taskId) { return recordRepository.findByTaskIdOrderByStartTimeAsc(taskId); } /** * 查询步骤详情 */ public OptionalTaskStepRecord getStepDetail(String taskId, String stepId) { return recordRepository.findByTaskIdAndStepId(taskId, stepId); } }3.4 仓库接口定义Repository public interface TaskStepRecordRepository extends JpaRepositoryTaskStepRecord, Long { ListTaskStepRecord findByTaskIdOrderByStartTimeAsc(String taskId); OptionalTaskStepRecord findByTaskIdAndStepId(String taskId, String stepId); Query(SELECT r FROM TaskStepRecord r WHERE r.taskId :taskId AND r.executeStatus :status) ListTaskStepRecord findByTaskIdAndStatus(Param(taskId) String taskId, Param(status) String status); }4. 在实际业务中集成步骤记录有了基础组件后我们看看如何在实际业务代码中使用。以下以一个文件处理任务为例。4.1 定义任务步骤枚举public enum FileProcessStep { START(start, 开始处理, START), VALIDATE_FILE(validate, 文件校验, PROCESS), PARSE_CONTENT(parse, 内容解析, PROCESS), TRANSFORM_DATA(transform, 数据转换, PROCESS), SAVE_RESULT(save, 结果保存, PROCESS), END(end, 处理完成, END); private final String stepId; private final String stepName; private final String stepType; FileProcessStep(String stepId, String stepName, String stepType) { this.stepId stepId; this.stepName stepName; this.stepType stepType; } // getters... }4.2 业务处理类示例Service Slf4j public class FileProcessService { Autowired private TaskStepRecordService recordService; public void processFile(String taskId, String filePath) { TaskStepRecord currentStep null; try { // 步骤1: 开始处理 MapString, Object startInput new HashMap(); startInput.put(filePath, filePath); startInput.put(taskId, taskId); currentStep recordService.startStep(taskId, FileProcessStep.START.getStepId(), FileProcessStep.START.getStepName(), FileProcessStep.START.getStepType(), startInput); // 步骤2: 文件校验 currentStep executeValidateStep(taskId, filePath); // 步骤3: 内容解析 currentStep executeParseStep(taskId, filePath); // 步骤4: 数据转换 currentStep executeTransformStep(taskId, currentStep); // 步骤5: 结果保存 executeSaveStep(taskId, currentStep); // 步骤6: 处理完成 recordFinalStep(taskId); } catch (Exception e) { log.error(文件处理失败, taskId: {}, taskId, e); if (currentStep ! null) { recordService.completeStepFailed(currentStep, e); } throw new RuntimeException(文件处理失败, e); } } private TaskStepRecord executeValidateStep(String taskId, String filePath) { MapString, Object input new HashMap(); input.put(filePath, filePath); TaskStepRecord step recordService.startStep(taskId, FileProcessStep.VALIDATE_FILE.getStepId(), FileProcessStep.VALIDATE_FILE.getStepName(), FileProcessStep.VALIDATE_FILE.getStepType(), input); try { // 实际校验逻辑 File file new File(filePath); if (!file.exists()) { throw new RuntimeException(文件不存在: filePath); } if (file.length() 0) { throw new RuntimeException(文件内容为空); } MapString, Object output new HashMap(); output.put(fileSize, file.length()); output.put(lastModified, file.lastModified()); recordService.completeStepSuccess(step, output); return step; } catch (Exception e) { recordService.completeStepFailed(step, e); throw e; } } // 其他步骤方法类似... }5. 步骤记录的查询与监控记录步骤数据后我们需要提供查询接口和监控面板。这里给出几个关键查询示例。5.1 任务执行详情查询RestController RequestMapping(/api/task-steps) public class TaskStepController { Autowired private TaskStepRecordService recordService; /** * 获取任务执行详情 */ GetMapping(/{taskId}) public ApiResponseTaskDetailVO getTaskDetail(PathVariable String taskId) { ListTaskStepRecord steps recordService.getStepsByTaskId(taskId); TaskDetailVO detail new TaskDetailVO(); detail.setTaskId(taskId); detail.setSteps(steps.stream().map(this::convertToVO).collect(Collectors.toList())); // 计算总体状态和耗时 calculateOverallStatus(detail); return ApiResponse.success(detail); } private TaskStepVO convertToVO(TaskStepRecord record) { TaskStepVO vo new TaskStepVO(); vo.setStepId(record.getStepId()); vo.setStepName(record.getStepName()); vo.setStepType(record.getStepType()); vo.setExecuteStatus(record.getExecuteStatus()); vo.setStartTime(record.getStartTime()); vo.setEndTime(record.getEndTime()); vo.setCostTime(record.getCostTime()); vo.setErrorMessage(record.getErrorMessage()); return vo; } private void calculateOverallStatus(TaskDetailVO detail) { if (detail.getSteps().isEmpty()) { detail.setOverallStatus(UNKNOWN); return; } boolean hasRunning detail.getSteps().stream() .anyMatch(s - RUNNING.equals(s.getExecuteStatus())); boolean hasFailed detail.getSteps().stream() .anyMatch(s - FAILED.equals(s.getExecuteStatus())); if (hasRunning) { detail.setOverallStatus(RUNNING); } else if (hasFailed) { detail.setOverallStatus(FAILED); } else { detail.setOverallStatus(SUCCESS); } // 计算总耗时 LocalDateTime start detail.getSteps().get(0).getStartTime(); LocalDateTime end detail.getSteps().get(detail.getSteps().size() - 1).getEndTime(); if (start ! null end ! null) { detail.setTotalCostTime(Duration.between(start, end).toMillis()); } } }5.2 监控统计查询-- 今日任务执行统计 SELECT execute_status, COUNT(*) as count, AVG(cost_time) as avg_cost FROM task_step_record WHERE DATE(create_time) CURDATE() GROUP BY execute_status; -- 最近一小时内各步骤平均耗时 SELECT step_name, AVG(cost_time) as avg_cost, COUNT(*) as execute_count FROM task_step_record WHERE create_time DATE_SUB(NOW(), INTERVAL 1 HOUR) GROUP BY step_name ORDER BY avg_cost DESC;6. 性能优化与生产环境建议当步骤记录数据量增大时需要考虑性能优化问题。6.1 数据库优化策略分区表设计如果数据量很大比如日均百万记录建议按时间分区CREATE TABLE task_step_record ( -- 字段定义同上 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 PARTITION BY RANGE (YEAR(create_time)*100 MONTH(create_time)) ( PARTITION p202401 VALUES LESS THAN (202402), PARTITION p202402 VALUES LESS THAN (202403), PARTITION p202403 VALUES LESS THAN (202404), PARTITION p_max VALUES LESS THAN MAXVALUE );索引优化除了基本索引外根据查询模式添加组合索引-- 用于监控统计查询 ALTER TABLE task_step_record ADD INDEX idx_status_time (execute_status, create_time); -- 用于步骤耗时分析 ALTER TABLE task_step_record ADD INDEX idx_step_cost (step_id, cost_time);6.2 异步记录机制对于高频任务同步记录可能影响性能。可以采用异步方式Service Slf4j public class AsyncTaskStepRecordService { Autowired private TaskStepRecordService recordService; Async(taskStepExecutor) public void recordStepAsync(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { try { recordService.startStep(taskId, stepId, stepName, stepType, inputParams); } catch (Exception e) { log.error(异步记录步骤失败, e); } } Async(taskStepExecutor) public void completeStepAsync(TaskStepRecord record, String status, MapString, Object outputResult, String errorMessage) { try { recordService.completeStep(record, status, outputResult, errorMessage); } catch (Exception e) { log.error(异步完成步骤失败, e); } } }配置线程池spring: task: execution: pool: core-size: 5 max-size: 20 queue-capacity: 1000 thread-name-prefix: task-step-async-7. 常见问题与排查指南在实际使用中可能会遇到以下典型问题。7.1 步骤记录丢失问题现象任务执行了但数据库中没有对应的步骤记录。排查步骤检查数据库连接是否正常查看应用日志是否有异常堆栈确认任务ID生成规则避免重复或空值检查异步记录时线程池是否饱和解决方案// 添加记录失败的重试机制 Retryable(value Exception.class, maxAttempts 3, backoff Backoff(delay 1000)) public TaskStepRecord startStepWithRetry(String taskId, String stepId, String stepName, String stepType, MapString, Object inputParams) { return recordService.startStep(taskId, stepId, stepName, stepType, inputParams); }7.2 步骤状态不一致问题现象步骤显示为RUNNING状态但实际已经执行完成。排查步骤检查是否有异常导致complete方法未执行确认事务边界避免事务回滚导致状态更新失败检查网络超时或应用重启情况解决方案// 添加状态补偿机制 Scheduled(fixedRate 300000) // 5分钟执行一次 public void compensateTimeoutSteps() { LocalDateTime timeoutThreshold LocalDateTime.now().minusMinutes(10); ListTaskStepRecord timeoutSteps recordRepository .findByExecuteStatusAndStartTimeBefore(RUNNING, timeoutThreshold); for (TaskStepRecord step : timeoutSteps) { step.setExecuteStatus(TIMEOUT); step.setErrorMessage(步骤执行超时系统自动标记); step.setEndTime(LocalDateTime.now()); recordRepository.save(step); log.warn(补偿超时步骤: taskId{}, stepId{}, step.getTaskId(), step.getStepId()); } }7.3 数据量过大导致查询慢现象查询任务历史时响应很慢。解决方案建立合适的数据归档策略添加查询条件限制如时间范围对历史数据建立只读副本-- 每月初归档上上月数据到历史表 INSERT INTO task_step_record_history SELECT * FROM task_step_record WHERE create_time DATE_SUB(CURDATE(), INTERVAL 2 MONTH); DELETE FROM task_step_record WHERE create_time DATE_SUB(CURDATE(), INTERVAL 2 MONTH);8. 最佳实践总结基于多个项目的实践经验总结以下最佳实践8.1 步骤粒度控制步骤不是越细越好要平衡可观测性和性能开销关键决策点必须记录步骤耗时操作必须记录步骤如外部API调用、大数据量处理可能失败的操作必须记录步骤简单内存操作可以合并步骤8.2 参数记录策略输入输出参数记录要兼顾信息量和隐私安全记录关键业务ID不要记录完整业务对象敏感信息密码、密钥必须脱敏大数据量字段记录摘要而非完整内容使用JSON格式便于后续查询分析8.3 监控告警配置建立关键监控指标步骤失败率超过阈值告警步骤平均耗时异常增长告警长时间RUNNING状态的步骤告警记录失败率监控反映系统健康度8.4 版本兼容考虑当业务逻辑变更时步骤记录可能需要适应新增步骤类型时保持向后兼容步骤ID变更时考虑数据迁移方案保留历史步骤记录的查询能力文档化步骤变更历史通过这套完整的任务步骤记录方案我们能够清晰掌握复杂任务的执行全过程快速定位问题优化系统性能。在实际项目中可以根据具体需求调整实现细节但核心的设计思路和最佳实践具有普适性。