Spring Boot夜间定时任务工程化实践：从分布式锁到告警排查

一条“今晚见吗？”出现在团队群里，经常不是约饭，而是在问：凌晨的定时任务到底还跑不跑？如果把这句话补完整，其实就是“今晚执行这个批处理，是个好主意吗？”很多后端工程师都经历过类似场景：白天不敢跑批量任务，于是把数据归档、报表计算、缓存预热排到凌晨两点。深夜执行看起来避开了业务高峰，但随之而来的是一系列更麻烦的问题：时区怎么统一、多实例会不会重复执行、失败之后有没有人能马上看到、日志能不能定位到是哪一批数据出了问题。

这篇文章围绕“夜间定时任务”这一场景展开，讲清楚为什么深夜执行容易变成坏主意，以及如何用 Spring Boot 和常见调度手段，把任务设计成可执行、可验证、可排查的工程能力。适合后端开发、运维工程师和负责批处理任务的同学阅读。读完可以形成一套自己的夜间任务评价清单，也能实际写出一个带锁、带日志、带告警的最小任务。

1. “今晚见吗”背后的真实问题：夜间任务为什么容易变成坏主意

1.1 夜间执行不等于风险低

很多团队把批量任务排在凌晨，理由是白天业务高峰资源紧张，数据库压力大，用户操作频繁，跑全量更新容易拖垮在线接口。这个判断本身没有错，但它忽略了一个关键变量：夜间执行是在人最少、监控最弱的窗口运行。

白天一条告警出现，五分钟内就会有人跟进。凌晨两点出现告警，大多数时候只能进入值班群，值班同学可能同时在处理多个问题。如果日志没有结构化，任务失败后没有自动重试，负责人第二天早上才看到失败提醒，那么“凌晨执行”并没有降低风险，只是把故障发现时间推迟了。

更常见的情况是，夜间任务失败后处于“半成功”状态：一部分数据已经处理完，另一部分没有处理。到了第二天，业务人员看到数据不完整，又不确定该不该重新跑，最终只能人工核对。这种局面比白天执行更消耗成本。

所以判断一个夜间任务是不是坏主意，不能只看“对在线系统有没有影响”，还要看“失败后能不能被发现、能不能被恢复”。

1.2 适合放夜间和不适合放夜间的任务

不是所有任务都适合放到凌晨。下面这组判断可以帮助快速过滤。

任务类型	是否适合放夜间	原因
全量数据归档、历史数据清理	适合	对在线库影响大，夜间用户负载低
离线报表、指标计算	适合	可延迟执行，失败后可重跑
缓存批量预热	适合但需要验证	预热数据不准确时会直接影响线上
批量发送短信、邮件、站内信	谨慎	用户感知强，短时高峰容易触发限流
支付、退款、结算类任务	不适合	资金敏感，需要审计和人工确认
实时补偿、订单状态流转	不适合	延迟敏感，需要事件驱动实时处理

“适合”不等于“可以直接跑”。即使是数据清理任务，也要先确认清理规则是否正确、是否有备份、失败后能否回滚。真正的判断标准是：如果这个任务在凌晨出错，团队需要多久能发现，又需要多久能恢复到正确状态。

1.3 夜间任务真正的风险点

夜间任务不是只有“跑不跑”的问题，常见的风险点可以归纳为六类。

第一，时区问题。服务器时区是 UTC，应用配置时区是 Asia/Shanghai，cron 表达式按哪个时区解释，直接决定任务会不会在错误的时间执行。

第二，任务重叠。上一次任务因为数据量大还没跑完，下一次触发时间已经到了，两个任务同时处理同一批数据。

第三，多实例重复执行。应用部署了两个节点，同一个 cron 表达式会在两台机器上同时触发，如果没有分布式锁或幂等机制，数据会被处理两次。

第四，时钟漂移。服务器系统时间不准，导致任务提前或延后执行。单机部署时影响不大，多机部署时会造成执行窗口不一致。

第五，依赖未就绪。凌晨外部接口可能正在维护，数据库可能在切换，文件源可能还没有上传，任务没有做依赖检查就直接开始。

第六，不可观测。没有日志、没有执行记录、没有监控指标，任务失败后根本不知道从哪里查起。

后面的内容会围绕这六类风险，逐步给出可落地的处理方式。

2. 环境准备：先跑通一个最小的 Spring Boot 夜间任务

2.1 依赖与项目结构

建议使用 Spring Boot 搭建一个最小工程。定时任务本身只需要spring-boot-starter，但为了能手动触发验证，通常再加上spring-boot-starter-web。

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>使用你项目匹配的 Spring Boot 版本</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies>

这里没有写死 Spring Boot 版本，因为不同团队的基础工程版本差别很大。落地前要先确认项目当前的 Spring Boot 版本，避免依赖冲突。

最小目录结构如下：

demo-night-job/ pom.xml src/main/java/com/example/nightjob/ NightJobApplication.java job/CleanDataJob.java job/JobRunLogService.java src/main/resources/ application.yml

NightJobApplication是启动类，负责开启调度能力。CleanDataJob是具体的夜间任务。JobRunLogService负责记录任务执行状态，后面会用到。

2.2 最小可执行代码

启动类需要加上@EnableScheduling，否则@Scheduled注解不会生效。

package com.example.nightjob; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.scheduling.annotation.EnableScheduling; @SpringBootApplication @EnableScheduling public class NightJobApplication { public static void main(String[] args) { SpringApplication.run(NightJobApplication.class, args); } }

任务类先写一个最简单的版本，每天凌晨两点执行一次清理任务。当前阶段只打印日志，不处理真实业务。

package com.example.nightjob.job; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; @Component public class CleanDataJob { private static final Logger log = LoggerFactory.getLogger(CleanDataJob.class); @Scheduled(cron = "0 0 2 * * ?", zone = "Asia/Shanghai") public void cleanExpiredData() { log.info("clean expired data task start"); // 这里先只记录日志，实际项目中替换为清理逻辑 log.info("clean expired data task end"); } }

这里要特别说明 cron 表达式。Spring 的@Scheduled使用六位 cron：秒、分、时、日、月、周。0 0 2 * * ?表示每天 02:00:00 执行。最后一位使用?表示“不指定”，避免和周字段冲突。

zone参数用来指定 cron 按哪个时区解析。这里固定为Asia/Shanghai，表示无论服务器是 UTC 还是其他时区，都按北京时间凌晨两点触发。为什么要单独设置？因为很多服务器默认时区是 UTC，如果 cron 写0 0 2 * * ?而不指定时区，实际执行时间可能变成北京时间早上八点或晚上十点，完全偏离预期。

2.3 学习环境如何快速验证

启动应用后，确认日志里没有报错。但凌晨两点的 cron 不方便调试，所以推荐把 cron 表达式放到配置文件中，通过配置覆盖。

spring: task: scheduling: time-zone: Asia/Shanghai pool: size: 4

同时在任务注解中使用配置占位符：

@Scheduled(cron = "${night.job.clean.cron:0 0 2 * * ?}", zone = "${night.job.clean.zone:Asia/Shanghai}") public void cleanExpiredData() { // 执行逻辑 }

测试环境可以在application.yml或环境变量里临时覆盖：

night: job: clean: cron: "0 */1 * * * ?"

这样每整分钟都会触发一次，方便验证。

注意：测试环境临时改成每分钟执行没问题，生产环境不要用这种覆盖方式。夜间任务一旦跑错，影响的是真实数据。

3. 把“坏主意”改造成“好主意”：可靠性设计

3.1 cron 表达式、时区和线程池要一起确认

cron 表达式看起来很直观，实际最容易出错。

字段	取值	说明
秒	0-59	第几秒触发
分	0-59	第几分钟触发
时	0-23	第几小时触发
日	1-31	月中第几天
月	1-12	几月
周	0-7 或 SUN-SAT	星期几，0 和 7 都是周日

初学者常犯的错误是把0 0 2 * * *当成“每天两点”。在 Spring 六位表达式中，最后一位是周，*表示每天都会匹配，而日的*也表示每天匹配，日和周同时为*时规则不明确，所以推荐使用?表示不指定。

时区方面，生产环境最稳妥的做法是：

• 服务器操作系统统一使用 UTC。
• 应用代码中手动指定 cron 时区为Asia/Shanghai。
• 日志输出时加入业务时区信息。
• 数据库时间字段统一使用DATETIME并按业务时区写入。

不要把时区判断散落在各处。只要有一个地方用了服务器默认时区，另一个地方用Asia/Shanghai，就会出现“昨天”“今天”边界混乱的问题。

线程池也需要注意。Spring Boot 默认的调度线程数只有 1。如果项目里有多个@Scheduled任务，其中一个任务长时间阻塞，其他任务会被卡住。可以配置调度线程池大小。

spring: task: scheduling: pool: size: 4

线程池大小不是越多越好。需要评估任务是否允许并行。如果两个任务都操作同一张表，并行执行可能会造成锁等待。调度线程池只解决“多个任务排队”的问题，不解决“业务资源争抢”的问题。

3.2 多实例部署时必须加分布式锁

应用一旦部署多个节点，同一个 cron 表达式会在每个节点上触发。比如两个实例都跑cleanExpiredData，同一批过期数据会被处理两次。

如果任务只是重新计算结果，幂等性还好。如果任务是清理数据、累加金额、发送消息，重复执行就是事故。

最简单的保护方式是使用 Redis 分布式锁。

import org.springframework.data.redis.core.StringRedisTemplate; import org.springframework.data.redis.core.script.DefaultRedisScript; import org.springframework.data.redis.core.script.RedisScript; import java.time.Duration; import java.util.Collections; @Component public class CleanDataJobWithLock { private static final Logger log = LoggerFactory.getLogger(CleanDataJobWithLock.class); private static final String LOCK_KEY = "job:clean:lock"; private static final Duration LOCK_TIMEOUT = Duration.ofMinutes(30); private final StringRedisTemplate redisTemplate; public CleanDataJobWithLock(StringRedisTemplate redisTemplate) { this.redisTemplate = redisTemplate; } @Scheduled(cron = "${night.job.clean.cron:0 0 2 * * ?}", zone = "${night.job.clean.zone:Asia/Shanghai}") public void cleanExpiredData() { String requestId = UUID.randomUUID().toString(); Boolean locked = redisTemplate.opsForValue() .setIfAbsent(LOCK_KEY, requestId, LOCK_TIMEOUT); if (!Boolean.TRUE.equals(locked)) { log.info("获取分布式锁失败，其他节点正在执行"); return; } try { log.info("clean expired data task start"); // 执行业务逻辑 log.info("clean expired data task end"); } finally { releaseLock(LOCK_KEY, requestId); } } private void releaseLock(String key, String requestId) { String scriptText = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end"; RedisScript<Long> script = new DefaultRedisScript<>(scriptText, Long.class); redisTemplate.execute(script, Collections.singletonList(key), requestId); } }

这里有几个关键点。

锁的过期时间必须大于任务最大执行时间。如果任务正常要跑 20 分钟，锁只设置 10 分钟，任务还没结束锁就过期了，另一个节点可能再次进入，造成重复执行。

释放锁时要校验requestId。不要直接redisTemplate.delete(key)，否则可能把其他节点刚获取的锁删掉。上面用 Lua 脚本完成“判断后删除”，保证原子性。

分布式锁能防止多实例重复执行，但不能防止任务内部的数据错误。锁只是第一道防线，后面的执行记录和幂等判断仍然需要。

3.3 执行记录、幂等与重试

即使有锁，任务也可能在业务执行一半时报错。为了能定位问题，也为了支持手动重跑，需要为每个任务维护一张执行记录表。

CREATE TABLE job_run_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, job_code VARCHAR(64) NOT NULL COMMENT '任务编码', biz_date VARCHAR(20) NOT NULL COMMENT '业务日期', executor_ip VARCHAR(64) COMMENT '执行节点 IP', trigger_time DATETIME COMMENT '触发时间', start_time DATETIME COMMENT '开始时间', end_time DATETIME COMMENT '结束时间', status VARCHAR(16) COMMENT 'RUNNING/SUCCESS/FAILED', error_msg TEXT COMMENT '失败信息', retry_count INT DEFAULT 0 COMMENT '重试次数', UNIQUE KEY uk_job_biz (job_code, biz_date) ) COMMENT '定时任务执行记录';

核心是唯一键(job_code, biz_date)。同一个任务同一天只能有一条执行记录。第一次执行时插入一条RUNNING记录，成功或失败后更新状态。这样即使手动重跑和自动触发同时到达，数据库也会拒绝第二条记录。

任务代码大致结构如下：

public void cleanExpiredData(String bizDate) { if (jobRunLogService.existsSuccess("cleanData", bizDate)) { log.info("任务当天已成功，跳过执行"); return; } jobRunLogService.markRunning("cleanData", bizDate, currentIp()); try { doClean(bizDate); jobRunLogService.markSuccess("cleanData", bizDate); } catch (Exception e) { jobRunLogService.markFailed("cleanData", bizDate, e.getMessage()); throw e; } }

这里有很多团队会忽略一个细节：任务失败后是否自动重试。

自动重试只适合网络抖动、依赖临时不可用这类错误。如果是数据本身有问题，或者业务规则不允许，自动重试只会反复失败，甚至把问题扩大。建议的做法是：

• 可重试错误：延迟一段时间后重试，最多重试 2 到 3 次。
• 不可重试错误：标记失败，进入人工处理列表。
• 重试必须有上限，避免无限循环。

3.4 告警与日志要能回答三个问题

告警不是“发出一条消息”就结束了。一条合格的告警必须能回答三个问题：哪个任务失败了、影响哪一天的数据、执行节点在哪里。

最简单的告警方式是在任务失败后调用告警平台接口。比如使用 Webhook 发送到值班群。

if [ $? -ne 0 ]; then curl -s -X POST "$ALERT_URL" \ -H 'Content-Type: application/json' \ -d "{\"title\":\"night job failed\", \"job\":\"cleanData\", \"bizDate\":\"2026-04-25\"}" fi

日志方面，不要只打印start和end，还要打印业务日期、处理数量、执行耗时、节点 IP。

推荐格式：

job=cleanData bizDate=2026-04-25 node=node-1 start job=cleanData bizDate=2026-04-25 deleted=156 costMs=2333 end

只要日志里有这些信息，第二天排查时就能直接定位是哪个节点、哪一天、处理了多少数据。如果日志里只有“success”，一旦数据有问题，所有节点都要重新查一遍。

4. 运行验证：从启动到看到结果的完整闭环

4.1 手动触发与业务日期构造

定时任务不能只靠 cron 触发。生产环境经常需要手动补跑某一天的数据，因此任务方法最好设计成接收bizDate参数，而不是每次都取“当前日期”。

Controller 可以这样写：

@RestController @RequestMapping("/job") public class JobDebugController { private final CleanDataJob cleanDataJob; public JobDebugController(CleanDataJob cleanDataJob) { this.cleanDataJob = cleanDataJob; } @PostMapping("/clean/run") public String run(@RequestParam String bizDate) { cleanDataJob.cleanExpiredData(bizDate); return "ok"; } }

手动触发时的操作目标是：确认任务能处理指定业务日期的数据，并且执行状态正确写入job_run_log。

操作内容：

1. 在测试库中插入一批过期数据和一批正常数据。
2. 调用POST /job/clean/run?bizDate=2026-04-25。
3. 检查过期数据是否被清理，正常数据是否保留。
4. 检查job_run_log中状态是否为SUCCESS。

这里要注意，手动触发接口不能在生产环境随意暴露。至少需要加权限控制，或者只允许从内网访问。否则任何人都可以触发一个凌晨任务，对数据库产生影响。

4.2 日志与指标检查

运行完成后，日志应该包含以下信息：

2026-04-26 02:00:00.123 INFO node-1 job=cleanData bizDate=2026-04-25 start 2026-04-26 02:00:02.456 INFO node-1 job=cleanData bizDate=2026-04-25 deleted=156 costMs=2333 end

这里deleted=156就是影响行数。没有这个数字，日志就只是“跑完了”，无法判断数据量是否符合预期。

监控指标方面，建议至少接入以下指标：

指标名	类型	含义
job_execute_total	Counter	任务总执行次数
job_execute_success_total	Counter	任务成功次数
job_execute_failed_total	Counter	任务失败次数
job_execute_duration_seconds	Histogram	任务耗时分布
job_execute_running	Gauge	当前正在执行的任务数
job_latest_success_time	Gauge	最近一次成功执行时间戳

其中job_latest_success_time很关键。它用来回答“任务到底有没有跑”。很多团队只监控失败告警，但任务因为调度器故障根本没有触发，这时候不会有失败告警，只有“最近成功时间越来越旧”。加上这个指标后，可以通过类似“超过 24 小时没有新成功记录”的规则，发现漏跑任务。

4.3 模拟故障验证恢复能力

验证不只是跑通一次正常链路。至少要模拟三种故障场景。

第一，让任务失败。可以故意传入一个不存在的业务日期，或者让任务里的 SQL 报错。确认job_run_log的状态变成FAILED，日志里出现异常堆栈，告警能发出来。

第二，模拟两个节点同时触发。在两个实例上同时调用手动触发接口，确认只有其中一个执行。另一个实例应该输出“获取分布式锁失败”或“任务当天已成功”，而不是继续跑业务。

第三，失败后手动重跑。修复问题后，再次调用手动触发接口，确认job_run_log中同一条记录被更新为SUCCESS，而不是插入一条新记录。这样才能保证补数和自动任务不冲突。

这些验证必须在测试环境完成，不能直接在生产环境演练。

5. 常见问题排查：凌晨被电话叫醒的几类原因

5.1 任务没有执行

现象：到了预定时间，没有任何日志，job_run_log里也没有新记录。

可能原因：

• cron 表达式写错，尤其是日和周的配置冲突。
• 时区配置不统一，导致执行时间偏移。
• 应用虽然启动了，但调度线程池被某个长时间任务占满。
• 机器时钟漂移，提前或延后执行。
• 如果使用系统 cron，crond服务未运行。

检查方式：

date -R timedatectl crontab -l

在应用日志中搜索Initializing ExecutorService或调度相关的注册日志。同时查询job_run_log当天的记录：

SELECT * FROM job_run_log WHERE job_code = 'cleanData' AND biz_date = '2026-04-25';

处理建议：统一时区，cron 表达式用在线工具校验，调度线程池留出足够大小。如果单机调度不可靠，可以引入外部调度平台作为兜底。

5.2 任务重复执行

现象：job_run_log中同一job_code和biz_date出现多条记录，或者数据被处理两次。

可能原因：

• 多实例部署但没有加分布式锁。
• 自动调度和手动重跑同时触发。
• Redis 锁过期时间太短，任务还没结束锁就释放了。
• 多个节点使用的锁 key 不一致，比如带上了节点 IP。

检查方式：

SELECT * FROM job_run_log WHERE job_code = 'cleanData' AND biz_date = '2026-04-25';

同时查看 Redis 中锁 key 是否存在：

redis-cli EXISTS job:clean:lock

处理建议：使用带随机值且带过期时间的分布式锁，释放时用 Lua 校验。执行记录表增加唯一键(job_code, biz_date)，让数据库层面拒绝重复。

5.3 任务卡死

现象：日志停在start，一直没有end，任务执行时间远超预期。

可能原因：

• 外部 HTTP 调用没有设置超时时间。
• 数据库连接池耗尽，任务在等待连接。
• 慢 SQL 造成锁等待。
• 内存不足触发频繁 Full GC，业务线程长时间暂停。
• 循环处理数据时出现死循环。

检查方式：

先看线程栈：

jstack <pid> | grep -A 20 "cleanData"

再看数据库当前事务和锁：

SELECT * FROM information_schema.innodb_trx; SHOW PROCESSLIST;

处理建议：所有外部调用必须设置超时时间和熔断降级。大批量任务要分批处理，每批提交一次事务，避免一个超长事务锁住大量数据。同时设置任务最大执行时间监控，超过阈值直接告警。

5.4 数据不对但状态显示成功

现象：任务日志显示SUCCESS，但业务数据不符合预期，比如清理的数据多了、少了，或者汇总金额不对。

可能原因：

• 时区导致业务日期窗口错误，处理了不该处理的数据。
• 事务边界不对，部分成功但整体没有回滚。
• 读取的是缓存或从库，主从延迟导致结果不一致。
• 任务处理的数据被其他任务并发修改。

检查方式：看日志里deleted或处理数量是否符合预期。在任务末尾增加对账查询，比如统计清理前后的数据量，如果差值不等于预期就标记失败。

处理建议：不要只监控“是否执行成功”，还要监控“执行结果是否符合预期”。在任务末尾增加结果校验函数，金额、数量、状态分布都可以作为校验项。

5.5 排查顺序

凌晨被叫醒时，不要先翻代码。按顺序来：

1. 查job_run_log，确认任务有没有触发、状态是什么。
2. 查应用日志，确认开始时间和结束时间，以及异常堆栈。
3. 查监控指标，确认失败次数、耗时、最近成功时间。
4. 查线程栈和数据库锁，确认是不是卡死。
5. 确认数据结果，判断是不是执行成功但数据错误。

这个顺序的目的，是先确定“任务到底有没有跑”和“结果对不对”，再往代码层面走。很多人一上来就改代码，结果发现任务是没触发，或只是外部接口超时，白白浪费大量时间。

6. 工程保障：发布前和执行后的检查清单

6.1 变更评估：先回答六个问题

上线一个夜间任务前，不要只问“cron 写对没有”。更重要的六个问题是：

1. 这个任务能不能不在夜间跑？
2. 如果任务失败，会造成什么影响？
3. 任务最晚必须几点完成？
4. 失败后能不能自动恢复？
5. 恢复是否需要人工介入？
6. 这个任务的负责人是谁？

如果六个问题都回答清楚，写代码时就有明确边界。比如“最晚必须 02:30 完成”，那么 30 分钟就是任务超时阈值，超过就要告警。如果“失败后不能自动恢复”，就不能把任务设计成无限重试，而是应该跳过并等待人工处理。

6.2 可复用检查清单

下面这份清单适用于绝大多数夜间批处理任务。

类别	检查项	通过标准
时间	cron 表达式通过工具校验	执行时间符合预期
时间	时区统一配置	cron 按业务时区触发
并发	有分布式锁或幂等键	多实例不会重复执行
日志	开始、结束、数量、耗时都有记录	失败后能定位问题
监控	有失败告警和最近成功时间监控	失败后 5 分钟内能感知
补偿	有手动重跑入口	能按业务日期补跑
依赖	外部接口有超时和熔断	不会无限等待
数据	任务末尾有结果校验	数据正确性可验证
权限	手动触发接口有权限控制	生产环境不会乱触发
回滚	有备份或可逆方案	数据出错能恢复

这份清单不复杂，但可以有效避免“任务上线后只能靠人盯”的局面。

6.3 运维响应机制

夜间任务不能只靠开发同学盯。需要有一条明确的响应链路。

任务失败告警发出后，值班人员应该先查看 `job