定时任务模块技术文档

一、模块概述

功能定位：

本模块基于Spring Task实现定时任务调度，用于处理异步/延迟业务场景（如订单状态流转、数据统计、佣金解冻等）。任务配置中心化管理，支持动态调整执行策略。

核心特性：

集中管理：所有任务类统一存放于com.zbkj.admin.task包
灵活配置：Cron表达式动态维护，支持界面化配置
执行监控：集成日志追踪与异常告警机制
低侵入性：新增任务只需遵循规范创建类与方法

二、新增定时任务指南

1. 创建任务类

路径规范：

# 项目路径
crmeb-admin/src/main/java/com/zbkj/admin/task/[业务模块]/XxxTask.java

示例代码：

package com.zbkj.admin.task.order;

import com.zbkj.common.utils.DateUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

/**
 * 订单自动确认任务
 */
@Component("OrderAutoConfirmTask")
public class orderAutoConfirmTask {
    private static final Logger logger = LoggerFactory.getLogger(OrderAutoConfirmTask.class);

    /**
     * 执行订单自动确认
     */
    public void execute() {
        logger.info("[定时任务] 订单自动确认开始 {}", DateUtil.nowDateTime());
        try {
            // 业务逻辑实现
            orderService.autoConfirm();
        } catch (Exception e) {
            logger.error("订单自动确认任务异常: {}", e.getMessage());
        }
        logger.info("[定时任务] 订单自动确认结束");
    }
}

2. PC端添加定时任务

管理端配置步骤：

进入【维护】→【定时任务】
点击【添加任务】按钮

填写表单：

定时任务类名：OrderAutoConfirmTask
Cron表达式：0 0 2 ?
方法名：orderAutoConfirmTask
参数：（允许为空）
备注：每天凌晨自动确认收货超时订单
保存并启用任务

三、开发规范

1. 命名规范

2. 日志规范

必须在方法入口/出口记录执行日志
捕获异常并记录详细堆栈信息

public void execute() {
    logger.info("[定时任务] 开始执行-订单超时关闭");
    try {
        orderService.closeTimeoutOrders();
    } catch (Exception e) {
        logger.error("订单超时关闭任务异常", e); // 记录完整堆栈
    }
    logger.info("[定时任务] 结束执行-订单超时关闭");
}

3.常见问题

1. 任务未按预期执行

检查项：
Cron表达式是否正确
Bean名称和方法名是否与代码完全一致（区分大小写）
服务器时间是否与业务时区一致

2. 任务重复执行

解决方案：

// 分布式锁示例
public void execute() {
    String lockKey = "task:OrderAutoConfirmTask:lock";
    Boolean lock = redisUtil.setIfAbsent(lockKey, "1", 30, TimeUnit.SECONDS);
    if (!lock) {
        logger.warn("任务正在其他节点执行，跳过本次处理");
        return;
    }
    try {
        // 业务逻辑
    } finally {
        redisUtil.delete(lockKey);
    }
}