1. 项目概述为什么我们需要一个“带锁”的定时任务如果你在项目中用过Spring的Scheduled注解来跑定时任务大概率遇到过这样的场景一个简单的数据统计任务在单机环境下跑得好好的一旦部署到多台机器上问题就来了——同一个任务在多个实例上同时被触发导致数据重复计算、资源争抢甚至引发业务逻辑的混乱。我最早遇到这个问题是在一个用户积分清算的系统里凌晨的清算任务因为多实例同时执行导致部分用户的积分被重复增减排查起来相当头疼。这就是分布式环境下定时任务面临的核心挑战如何保证一个任务在同一时刻在整个集群中只被一个实例执行一次。Spring自带的Scheduled只管触发不管协调它无法感知集群中其他实例的存在。于是一个专门为解决此问题而生的方案——SchedulerLock便进入了我们的视野。它并非Spring官方出品而是来自一个名为“ShedLock”的第三方库这个库的设计理念非常纯粹利用一个所有应用实例都能访问的共享存储比如数据库、Redis、ZooKeeper通过“锁”的机制来协调任务的执行。简单来说SchedulerLock给我们的定时任务加了一把“全局锁”。任务执行前实例会去尝试获取这把锁谁拿到了锁谁就有权执行任务其他实例则自动跳过。任务执行完毕或失败后锁会被释放或设置一个最长持有时间防止死锁。这样无论集群有多少个节点任务都能被安全、有序地执行。接下来我们就深入拆解这个轻量级却至关重要的组件。2. 核心机制与设计原理深度解析2.1 锁模型与实现基石ShedLock的核心是一个朴素的“互斥锁”思想但其实现考虑了分布式环境的复杂性。它的锁模型包含几个关键属性锁名称每个需要同步的任务必须有一个全局唯一的名称。这通常是SchedulerLock注解中name属性的值。锁名称是协调的基础所有实例都通过这个名称来识别和竞争同一把锁。锁持有者成功获取锁的实例会将自己的一个唯一标识默认为主机名进程ID记录为锁的持有者。这主要用于监控和调试知道当前是哪个实例在执行任务。锁有效期这是ShedLock设计中最精妙的一点。它不像传统的锁那样需要显式释放。当一个实例获取锁时它会为这把锁设置一个“至少直到”的时间戳即lockAtLeastUntil。任务执行时间必须短于这个时间。同时它还会设置一个“最多直到”的时间戳即lockAtMostUntil。即使任务执行超时或实例崩溃锁也会在这个时间点后自动失效避免死锁。这个“最多直到”的时间就是注解中的lockAtMost参数。其实现依赖于一个所有应用实例共享的锁提供者。以最常用的JDBC为例ShedLock会在数据库中创建一张表默认为shedlock结构大致如下字段名类型说明namevarchar(64)锁的唯一名称主键。lock_untiltimestamp锁的最晚有效时间lockAtMostUntil。locked_attimestamp锁的获取时间。locked_byvarchar(255)锁持有者的标识如主机名。当一个实例要执行任务时它会执行一个类似“原子性”的SQL操作去抢占锁例如MySQL的INSERT ... ON DUPLICATE KEY UPDATE并判断lock_until now()成功插入或更新记录即视为获取锁。2.2 与Spring Scheduling的集成原理ShedLock并没有替换Spring的调度器而是巧妙地与之协作。它通过Spring AOP面向切面编程来实现。当你给一个方法加上SchedulerLock注解后ShedLock会为该方法的执行创建一个切面。这个切面的工作流程可以概括为拦截调用Spring调度器触发Scheduled方法。尝试获取锁在执行实际业务逻辑前切面逻辑介入尝试从配置的锁提供者如数据库获取指定名称的锁。决策如果获取成功则继续执行原方法业务逻辑如果获取失败锁已被其他实例持有则直接跳过本次执行方法体根本不会运行。释放/更新锁方法执行结束后无论成功或异常切面会立即更新数据库将lock_until设置为当前时间即释放锁。注意这里依赖的是lockAtLeast参数锁的实际持有时间会至少是lockAtLeast指定的时长。如果任务执行得非常快比如1秒但lockAtLeast设置为10秒那么锁会在10秒后才真正释放这是为了防止在非常短的时间间隔内锁被释放后又立刻被另一个实例获取导致任务在集群中“抖动式”地频繁切换执行实例这在某些场景下可能引发问题。注意这里容易产生一个误解。lockAtMost是防止任务崩溃导致死锁的“安全网”而lockAtLeast是为了保证任务执行稳定性的“缓冲垫”。理解这两者的区别对于正确配置参数至关重要。3. 详细配置与实战应用指南3.1 项目引入与基础配置首先在pom.xml中添加依赖。ShedLock提供了多种锁提供者的实现最常用的是JDBC和Redis。!-- 使用JDBC (MySQL) 作为锁提供者 -- dependency groupIdnet.javacrumbs.shedlock/groupId artifactIdshedlock-spring/artifactId version5.10.2/version !-- 请使用最新版本 -- /dependency dependency groupIdnet.javacrumbs.shedlock/groupId artifactIdshedlock-provider-jdbc-template/artifactId version5.10.2/version /dependency接下来是Spring Boot的配置类。这里以MySQL为例import net.javacrumbs.shedlock.core.LockProvider; import net.javacrumbs.shedlock.provider.jdbctemplate.JdbcTemplateLockProvider; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.sql.DataSource; Configuration public class ShedLockConfig { Bean public LockProvider lockProvider(DataSource dataSource) { // 使用你的数据源创建锁提供者 return new JdbcTemplateLockProvider( JdbcTemplateLockProvider.Configuration.builder() .withJdbcTemplate(new JdbcTemplate(dataSource)) .usingDbTime() // 使用数据库时间避免服务器间时间不同步问题 .build() ); } }关键点解析usingDbTime()强烈建议在生产环境开启。它确保锁的超时判断基于数据库服务器的时间而不是应用服务器的时间。如果集群中服务器时间不同步不使用此选项可能导致锁协调失效。表名默认会创建shedlock表。你可以通过.withTableName(“your_table_name”)自定义。然后在数据库中创建对应的表以MySQL为例CREATE TABLE shedlock ( name VARCHAR(64) NOT NULL, lock_until TIMESTAMP(3) NOT NULL, locked_at TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), locked_by VARCHAR(255) NOT NULL, PRIMARY KEY (name) );3.2 SchedulerLock注解参数详解与实战示例现在我们可以在任意的Spring Bean方法上组合使用Scheduled和SchedulerLock。import net.javacrumbs.shedlock.spring.annotation.SchedulerLock; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; Component public class MyScheduledTasks { // 示例1基础用法每天凌晨1点执行的数据清理任务 Scheduled(cron 0 0 1 * * ?) // Spring的cron表达式 SchedulerLock( name scheduledTaskName_cleanup, // 锁名称必须唯一且具有辨识度 lockAtMost 30m, // 最大锁持有时间必须设置。假设任务最多跑30分钟。 lockAtLeast 2s // 最小锁持有时间可选。防止快速任务在集群中抖动。 ) public void scheduledDataCleanup() { // 你的业务逻辑在这里 // 这个方法在同一时间整个集群只会有一个实例执行 log.info(开始执行分布式数据清理任务...); // ... 清理逻辑 } // 示例2高频短任务每10秒执行一次的心跳或状态同步 Scheduled(fixedDelay 10000) // 上次执行结束后10秒再执行 SchedulerLock( name shortRunningTask_statusSync, lockAtMost 15s, // 最大锁时间略大于执行间隔防止任务堆积导致并发 lockAtLeast 5s // 最小锁时间接近执行间隔保证执行节奏稳定 ) public void statusSyncTask() { // 快速的状态同步逻辑 // 即使多个实例也不会在10秒内重复执行 } }参数配置心得name命名要有意义通常结合任务功能和方法名。它是锁的唯一标识不同任务绝对不能重复。lockAtMost这是必须设置的参数。它的值应该大于你预估的任务最坏情况下的执行时间。如果任务因未知原因挂起或执行极慢超过这个时间后锁会自动失效其他实例可以接手。设置过短会导致任务被意外中断两个实例同时跑设置过长则意味着故障恢复时间变长。我通常会在预估最大时间上增加20%-50%的缓冲。lockAtLeast这是一个“软性”约束。对于执行时间很短毫秒级但执行间隔也短的任务设置一个合理的lockAtLeast比如500ms可以避免锁在释放后瞬间被另一个实例获取造成不必要的集群内部竞争。对于执行时间较长分钟级或间隔长的任务这个参数的意义不大可以忽略或设置一个很小的值。3.3 多种锁提供者选型对比除了JDBCShedLock还支持其他存储选择哪种取决于你的技术栈和性能要求。提供者依赖模块适用场景优点注意事项JDBCshedlock-provider-jdbc-template绝大多数有关系型数据库的项目。部署简单无需额外中间件利用现有数据库事务可靠性高。对数据库有一定压力高频任务需注意性能需要建表。Redisshedlock-provider-redis-spring高性能、高并发场景已在使用Redis的项目。性能极高读写速度快支持丰富的Redis部署模式单机、哨兵、集群。引入Redis依赖和运维成本需注意Redis的持久化策略避免锁信息丢失。MongoDBshedlock-provider-mongo技术栈以MongoDB为主的项目。文档模型天然适合存储锁信息与MongoDB生态集成好。同Redis需额外维护中间件。ZooKeepershedlock-provider-zookeeper-curator对强一致性要求极高的复杂分布式系统。ZooKeeper保证强一致性和顺序性是最可靠的方案之一。重量级运维复杂性能相对较低适用于非高频任务。选型建议对于大多数Spring Boot应用如果已经有MySQL/PostgreSQL等数据库JDBC提供者是最稳妥、最简单的选择。除非你的定时任务数量极多、频率极高例如每秒数次且对数据库性能有顾虑否则没必要引入Redis。ZooKeeper通常用于已有ZK集群的系统中。4. 高级特性、监控与问题排查4.1 配合Spring的异步与重试机制SchedulerLock只负责锁的获取与释放它不关心任务本身的执行方式。你可以轻松地将其与Spring的其他功能结合。Component public class AdvancedTask { Async // 结合Async让任务异步执行不阻塞调度线程 Scheduled(fixedRate 300000) // 每5分钟 SchedulerLock(name asyncReportGeneration, lockAtMost 20m) public void generateReportAsync() { // 这是一个耗时的报表生成任务异步执行避免阻塞其他定时任务 // 锁机制依然有效保证集群内唯一执行 } // 结合Spring Retry在任务执行失败时自动重试 Retryable(value {RemoteAccessException.class}, maxAttempts 3, backoff Backoff(delay 2000)) Scheduled(cron 0 */5 * * * ?) // 每5分钟 SchedulerLock(name retryableApiSync, lockAtMost 10m) public void syncWithExternalApi() { // 调用外部API可能因网络波动失败 // Retryable会在抛出RemoteAccessException时自动重试最多3次每次间隔2秒 // 在整个重试期间锁依然被当前实例持有其他实例不会介入 } }重要提示当结合Async时务必理解锁的释放时机。锁会在原方法调用结束时释放而不是在异步线程执行完毕时。这意味着如果异步任务执行时间很长但原方法很快返回锁可能提前释放导致并发问题。在这种情况下你需要手动管理锁的生命周期或者确保异步任务是“fire-and-forget”类型且允许重叠执行这通常违背了使用锁的初衷。更安全的做法是将耗时逻辑放在同步方法内或者使用CompletableFuture并在其完成后手动更新锁状态这需要更复杂的代码。4.2 锁状态监控与管理在生产环境中我们需要知道锁被谁持有、是否健康。ShedLock提供了简单的监控接口。查看数据库最直接的方式是查询shedlock表。观察locked_by持有者、locked_at获取时间和lock_until最晚释放时间。如果发现某个锁的lock_until远早于当前时间但locked_by仍有值可能意味着持有该锁的实例崩溃了锁已自动失效这是正常现象。通过LockProvider接口你可以注入LockProvider调用其getLock方法来检查特定锁的状态但API较为底层。自定义健康检查可以编写一个健康指示器检查是否有预期应被定期获取的锁长时间未被获取这可能意味着调度器或锁机制出现了问题。Component public class ShedLockHealthIndicator implements HealthIndicator { Autowired private JdbcTemplate jdbcTemplate; Override public Health health() { try { // 检查一个关键任务锁最近是否被活跃获取 // 例如一个应该每5分钟运行一次的任务其锁记录应该在最近10分钟内被更新过 String sql SELECT COUNT(*) FROM shedlock WHERE name ? AND locked_at ?; Instant tenMinutesAgo Instant.now().minus(10, ChronoUnit.MINUTES); Integer count jdbcTemplate.queryForObject(sql, Integer.class, criticalTaskName, Timestamp.from(tenMinutesAgo)); if (count ! null count 0) { return Health.up().withDetail(criticalTaskLock, active).build(); } else { return Health.down().withDetail(criticalTaskLock, stale_or_missing).build(); } } catch (Exception e) { return Health.down(e).build(); } } }4.3 常见问题与排查技巧实录在实际使用中我踩过不少坑这里总结几个典型问题和解决方法。问题1任务没有按预期加锁在多实例上同时执行了。排查步骤检查依赖和配置确认shedlock-spring和锁提供者如jdbc-template的依赖已正确引入且版本兼容。检查ShedLockConfig配置类是否被Spring扫描到。检查锁表直接查询数据库中的shedlock表看对应name的锁记录是否存在。执行任务时观察locked_at和locked_by字段是否更新。检查注解位置SchedulerLock必须和Scheduled注解在同一个方法上并且该方法必须是一个Spring Bean的public方法。检查AOP代理如果任务类使用了final方法、private方法或者类本身不是Spring Bean例如通过new创建AOP将无法生效锁机制会失效。确保任务类被Component等注解标记且方法可被代理。问题2任务执行时间过长锁提前失效导致另一个实例又开始执行。原因与解决lockAtMost时间设置得太短小于任务的实际执行时间。解决重新评估任务的最长执行时间考虑网络延迟、数据量增长等边界情况并适当增加lockAtMost的值。例如从10m调整为30m。同时应该优化任务本身尝试减少执行时间。问题3数据库连接池耗尽或锁表出现死锁。原因高频任务如每秒一次且lockAtLeast设置得很短导致频繁的锁获取和释放操作对数据库造成压力。解决优化任务频率重新评估是否真的需要如此高的频率。调整锁参数适当增加lockAtLeast减少竞争频率。数据库优化确保shedlock表的主键索引有效。对于MySQL可以使用SELECT ... FOR UPDATE的悲观锁模式ShedLock默认使用乐观的CAS方式但需在配置中指定。JdbcTemplateLockProvider.Configuration.builder().withIsolationLevel(Connection.TRANSACTION_SERIALIZABLE)慎用性能影响大。切换锁提供者如果性能是瓶颈考虑切换到Redis提供者。问题4在单元测试中SchedulerLock不生效或报错。原因测试环境可能没有配置锁提供者或者Spring的调度器被禁用了。解决在测试配置中可以提供一个基于内存的锁提供者如net.javacrumbs.shedlock.provider.inmemory.InMemoryLockProvider来模拟。或者在测试类上使用SpringBootTest时通过属性spring.main.web-application-typenone和spring.task.scheduling.enabledfalse来禁用调度专注于测试业务逻辑本身。踩坑记录我曾经遇到一个最隐蔽的问题任务在预发环境正常上线后锁失效。最终发现是服务器时区不一致。实例A和实例B的系统时间相差几分钟导致基于应用服务器时间的锁判断逻辑混乱。这就是为什么在配置中强烈推荐使用.usingDbTime()的原因——让数据库这个唯一的时间源来仲裁彻底解决时钟同步问题。5. 架构思考与替代方案浅析虽然SchedulerLockShedLock解决了一个非常具体的痛点且做得足够轻量和优雅但在进行技术选型时我们也需要将其放在更大的架构视角下来审视。ShedLock的定位它是一个库而非服务。它的目标是在应用层面以最小的侵入性和成本解决分布式定时任务互斥的问题。它假设你的应用已经是多实例部署并且有一个共享的存储数据库/Redis等。何时选择ShedLock项目已使用Spring Scheduling改造成本要低。定时任务数量不多频率不高分钟级及以上。团队希望保持技术栈简单不想引入重量级的分布式调度中间件。任务逻辑相对独立不需要复杂的工作流、依赖管理、失败重试策略这些可通过Spring Retry等补充基础能力。何时考虑更重量级的替代方案 当你的定时任务系统变得越来越复杂出现以下需求时可能需要考虑如Quartz Cluster、Elastic-Job、XXL-Job或Apache DolphinScheduler等专门的分布式任务调度平台任务可视化与管理需要统一的Web控制台来动态添加、修改、触发、暂停任务。任务分片一个超大数据量的处理任务需要被拆分成多个子任务分发给多个实例并行执行最后汇总结果。复杂的依赖与工作流任务B必须在任务A成功后执行任务C和D可以并行形成一个DAG有向无环图工作流。丰富的路由策略支持故障转移、忙碌转移、一致性哈希等更复杂的执行器路由逻辑。完整的执行历史与日志需要集中查看所有任务的历史执行记录、成功/失败状态以及详细日志。告警与监控任务失败后能自动通过邮件、钉钉、微信等渠道告警。个人体会在微服务架构中我倾向于根据场景分层使用。对于服务内部的、轻量的、业务逻辑紧密的定时任务比如缓存预热、本地状态清理ShedLock是首选它简洁不重完美融入Spring生态。而对于跨服务的、重要的、需要集中管控的业务定时任务比如日终对账、全量数据同步则会建立一个独立的调度中心如XXL-Job来统一管理。这种“轻重结合”的方式既能满足简单场景的敏捷性又能应对复杂场景的管控需求。SchedulerLock就像一把精准的瑞士军刀在它适用的场景里你几乎找不到比它更趁手的工具。 Spring定时任务分布式锁ShedLock原理与实战配置详解
1. 项目概述为什么我们需要一个“带锁”的定时任务如果你在项目中用过Spring的Scheduled注解来跑定时任务大概率遇到过这样的场景一个简单的数据统计任务在单机环境下跑得好好的一旦部署到多台机器上问题就来了——同一个任务在多个实例上同时被触发导致数据重复计算、资源争抢甚至引发业务逻辑的混乱。我最早遇到这个问题是在一个用户积分清算的系统里凌晨的清算任务因为多实例同时执行导致部分用户的积分被重复增减排查起来相当头疼。这就是分布式环境下定时任务面临的核心挑战如何保证一个任务在同一时刻在整个集群中只被一个实例执行一次。Spring自带的Scheduled只管触发不管协调它无法感知集群中其他实例的存在。于是一个专门为解决此问题而生的方案——SchedulerLock便进入了我们的视野。它并非Spring官方出品而是来自一个名为“ShedLock”的第三方库这个库的设计理念非常纯粹利用一个所有应用实例都能访问的共享存储比如数据库、Redis、ZooKeeper通过“锁”的机制来协调任务的执行。简单来说SchedulerLock给我们的定时任务加了一把“全局锁”。任务执行前实例会去尝试获取这把锁谁拿到了锁谁就有权执行任务其他实例则自动跳过。任务执行完毕或失败后锁会被释放或设置一个最长持有时间防止死锁。这样无论集群有多少个节点任务都能被安全、有序地执行。接下来我们就深入拆解这个轻量级却至关重要的组件。2. 核心机制与设计原理深度解析2.1 锁模型与实现基石ShedLock的核心是一个朴素的“互斥锁”思想但其实现考虑了分布式环境的复杂性。它的锁模型包含几个关键属性锁名称每个需要同步的任务必须有一个全局唯一的名称。这通常是SchedulerLock注解中name属性的值。锁名称是协调的基础所有实例都通过这个名称来识别和竞争同一把锁。锁持有者成功获取锁的实例会将自己的一个唯一标识默认为主机名进程ID记录为锁的持有者。这主要用于监控和调试知道当前是哪个实例在执行任务。锁有效期这是ShedLock设计中最精妙的一点。它不像传统的锁那样需要显式释放。当一个实例获取锁时它会为这把锁设置一个“至少直到”的时间戳即lockAtLeastUntil。任务执行时间必须短于这个时间。同时它还会设置一个“最多直到”的时间戳即lockAtMostUntil。即使任务执行超时或实例崩溃锁也会在这个时间点后自动失效避免死锁。这个“最多直到”的时间就是注解中的lockAtMost参数。其实现依赖于一个所有应用实例共享的锁提供者。以最常用的JDBC为例ShedLock会在数据库中创建一张表默认为shedlock结构大致如下字段名类型说明namevarchar(64)锁的唯一名称主键。lock_untiltimestamp锁的最晚有效时间lockAtMostUntil。locked_attimestamp锁的获取时间。locked_byvarchar(255)锁持有者的标识如主机名。当一个实例要执行任务时它会执行一个类似“原子性”的SQL操作去抢占锁例如MySQL的INSERT ... ON DUPLICATE KEY UPDATE并判断lock_until now()成功插入或更新记录即视为获取锁。2.2 与Spring Scheduling的集成原理ShedLock并没有替换Spring的调度器而是巧妙地与之协作。它通过Spring AOP面向切面编程来实现。当你给一个方法加上SchedulerLock注解后ShedLock会为该方法的执行创建一个切面。这个切面的工作流程可以概括为拦截调用Spring调度器触发Scheduled方法。尝试获取锁在执行实际业务逻辑前切面逻辑介入尝试从配置的锁提供者如数据库获取指定名称的锁。决策如果获取成功则继续执行原方法业务逻辑如果获取失败锁已被其他实例持有则直接跳过本次执行方法体根本不会运行。释放/更新锁方法执行结束后无论成功或异常切面会立即更新数据库将lock_until设置为当前时间即释放锁。注意这里依赖的是lockAtLeast参数锁的实际持有时间会至少是lockAtLeast指定的时长。如果任务执行得非常快比如1秒但lockAtLeast设置为10秒那么锁会在10秒后才真正释放这是为了防止在非常短的时间间隔内锁被释放后又立刻被另一个实例获取导致任务在集群中“抖动式”地频繁切换执行实例这在某些场景下可能引发问题。注意这里容易产生一个误解。lockAtMost是防止任务崩溃导致死锁的“安全网”而lockAtLeast是为了保证任务执行稳定性的“缓冲垫”。理解这两者的区别对于正确配置参数至关重要。3. 详细配置与实战应用指南3.1 项目引入与基础配置首先在pom.xml中添加依赖。ShedLock提供了多种锁提供者的实现最常用的是JDBC和Redis。!-- 使用JDBC (MySQL) 作为锁提供者 -- dependency groupIdnet.javacrumbs.shedlock/groupId artifactIdshedlock-spring/artifactId version5.10.2/version !-- 请使用最新版本 -- /dependency dependency groupIdnet.javacrumbs.shedlock/groupId artifactIdshedlock-provider-jdbc-template/artifactId version5.10.2/version /dependency接下来是Spring Boot的配置类。这里以MySQL为例import net.javacrumbs.shedlock.core.LockProvider; import net.javacrumbs.shedlock.provider.jdbctemplate.JdbcTemplateLockProvider; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.sql.DataSource; Configuration public class ShedLockConfig { Bean public LockProvider lockProvider(DataSource dataSource) { // 使用你的数据源创建锁提供者 return new JdbcTemplateLockProvider( JdbcTemplateLockProvider.Configuration.builder() .withJdbcTemplate(new JdbcTemplate(dataSource)) .usingDbTime() // 使用数据库时间避免服务器间时间不同步问题 .build() ); } }关键点解析usingDbTime()强烈建议在生产环境开启。它确保锁的超时判断基于数据库服务器的时间而不是应用服务器的时间。如果集群中服务器时间不同步不使用此选项可能导致锁协调失效。表名默认会创建shedlock表。你可以通过.withTableName(“your_table_name”)自定义。然后在数据库中创建对应的表以MySQL为例CREATE TABLE shedlock ( name VARCHAR(64) NOT NULL, lock_until TIMESTAMP(3) NOT NULL, locked_at TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), locked_by VARCHAR(255) NOT NULL, PRIMARY KEY (name) );3.2 SchedulerLock注解参数详解与实战示例现在我们可以在任意的Spring Bean方法上组合使用Scheduled和SchedulerLock。import net.javacrumbs.shedlock.spring.annotation.SchedulerLock; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; Component public class MyScheduledTasks { // 示例1基础用法每天凌晨1点执行的数据清理任务 Scheduled(cron 0 0 1 * * ?) // Spring的cron表达式 SchedulerLock( name scheduledTaskName_cleanup, // 锁名称必须唯一且具有辨识度 lockAtMost 30m, // 最大锁持有时间必须设置。假设任务最多跑30分钟。 lockAtLeast 2s // 最小锁持有时间可选。防止快速任务在集群中抖动。 ) public void scheduledDataCleanup() { // 你的业务逻辑在这里 // 这个方法在同一时间整个集群只会有一个实例执行 log.info(开始执行分布式数据清理任务...); // ... 清理逻辑 } // 示例2高频短任务每10秒执行一次的心跳或状态同步 Scheduled(fixedDelay 10000) // 上次执行结束后10秒再执行 SchedulerLock( name shortRunningTask_statusSync, lockAtMost 15s, // 最大锁时间略大于执行间隔防止任务堆积导致并发 lockAtLeast 5s // 最小锁时间接近执行间隔保证执行节奏稳定 ) public void statusSyncTask() { // 快速的状态同步逻辑 // 即使多个实例也不会在10秒内重复执行 } }参数配置心得name命名要有意义通常结合任务功能和方法名。它是锁的唯一标识不同任务绝对不能重复。lockAtMost这是必须设置的参数。它的值应该大于你预估的任务最坏情况下的执行时间。如果任务因未知原因挂起或执行极慢超过这个时间后锁会自动失效其他实例可以接手。设置过短会导致任务被意外中断两个实例同时跑设置过长则意味着故障恢复时间变长。我通常会在预估最大时间上增加20%-50%的缓冲。lockAtLeast这是一个“软性”约束。对于执行时间很短毫秒级但执行间隔也短的任务设置一个合理的lockAtLeast比如500ms可以避免锁在释放后瞬间被另一个实例获取造成不必要的集群内部竞争。对于执行时间较长分钟级或间隔长的任务这个参数的意义不大可以忽略或设置一个很小的值。3.3 多种锁提供者选型对比除了JDBCShedLock还支持其他存储选择哪种取决于你的技术栈和性能要求。提供者依赖模块适用场景优点注意事项JDBCshedlock-provider-jdbc-template绝大多数有关系型数据库的项目。部署简单无需额外中间件利用现有数据库事务可靠性高。对数据库有一定压力高频任务需注意性能需要建表。Redisshedlock-provider-redis-spring高性能、高并发场景已在使用Redis的项目。性能极高读写速度快支持丰富的Redis部署模式单机、哨兵、集群。引入Redis依赖和运维成本需注意Redis的持久化策略避免锁信息丢失。MongoDBshedlock-provider-mongo技术栈以MongoDB为主的项目。文档模型天然适合存储锁信息与MongoDB生态集成好。同Redis需额外维护中间件。ZooKeepershedlock-provider-zookeeper-curator对强一致性要求极高的复杂分布式系统。ZooKeeper保证强一致性和顺序性是最可靠的方案之一。重量级运维复杂性能相对较低适用于非高频任务。选型建议对于大多数Spring Boot应用如果已经有MySQL/PostgreSQL等数据库JDBC提供者是最稳妥、最简单的选择。除非你的定时任务数量极多、频率极高例如每秒数次且对数据库性能有顾虑否则没必要引入Redis。ZooKeeper通常用于已有ZK集群的系统中。4. 高级特性、监控与问题排查4.1 配合Spring的异步与重试机制SchedulerLock只负责锁的获取与释放它不关心任务本身的执行方式。你可以轻松地将其与Spring的其他功能结合。Component public class AdvancedTask { Async // 结合Async让任务异步执行不阻塞调度线程 Scheduled(fixedRate 300000) // 每5分钟 SchedulerLock(name asyncReportGeneration, lockAtMost 20m) public void generateReportAsync() { // 这是一个耗时的报表生成任务异步执行避免阻塞其他定时任务 // 锁机制依然有效保证集群内唯一执行 } // 结合Spring Retry在任务执行失败时自动重试 Retryable(value {RemoteAccessException.class}, maxAttempts 3, backoff Backoff(delay 2000)) Scheduled(cron 0 */5 * * * ?) // 每5分钟 SchedulerLock(name retryableApiSync, lockAtMost 10m) public void syncWithExternalApi() { // 调用外部API可能因网络波动失败 // Retryable会在抛出RemoteAccessException时自动重试最多3次每次间隔2秒 // 在整个重试期间锁依然被当前实例持有其他实例不会介入 } }重要提示当结合Async时务必理解锁的释放时机。锁会在原方法调用结束时释放而不是在异步线程执行完毕时。这意味着如果异步任务执行时间很长但原方法很快返回锁可能提前释放导致并发问题。在这种情况下你需要手动管理锁的生命周期或者确保异步任务是“fire-and-forget”类型且允许重叠执行这通常违背了使用锁的初衷。更安全的做法是将耗时逻辑放在同步方法内或者使用CompletableFuture并在其完成后手动更新锁状态这需要更复杂的代码。4.2 锁状态监控与管理在生产环境中我们需要知道锁被谁持有、是否健康。ShedLock提供了简单的监控接口。查看数据库最直接的方式是查询shedlock表。观察locked_by持有者、locked_at获取时间和lock_until最晚释放时间。如果发现某个锁的lock_until远早于当前时间但locked_by仍有值可能意味着持有该锁的实例崩溃了锁已自动失效这是正常现象。通过LockProvider接口你可以注入LockProvider调用其getLock方法来检查特定锁的状态但API较为底层。自定义健康检查可以编写一个健康指示器检查是否有预期应被定期获取的锁长时间未被获取这可能意味着调度器或锁机制出现了问题。Component public class ShedLockHealthIndicator implements HealthIndicator { Autowired private JdbcTemplate jdbcTemplate; Override public Health health() { try { // 检查一个关键任务锁最近是否被活跃获取 // 例如一个应该每5分钟运行一次的任务其锁记录应该在最近10分钟内被更新过 String sql SELECT COUNT(*) FROM shedlock WHERE name ? AND locked_at ?; Instant tenMinutesAgo Instant.now().minus(10, ChronoUnit.MINUTES); Integer count jdbcTemplate.queryForObject(sql, Integer.class, criticalTaskName, Timestamp.from(tenMinutesAgo)); if (count ! null count 0) { return Health.up().withDetail(criticalTaskLock, active).build(); } else { return Health.down().withDetail(criticalTaskLock, stale_or_missing).build(); } } catch (Exception e) { return Health.down(e).build(); } } }4.3 常见问题与排查技巧实录在实际使用中我踩过不少坑这里总结几个典型问题和解决方法。问题1任务没有按预期加锁在多实例上同时执行了。排查步骤检查依赖和配置确认shedlock-spring和锁提供者如jdbc-template的依赖已正确引入且版本兼容。检查ShedLockConfig配置类是否被Spring扫描到。检查锁表直接查询数据库中的shedlock表看对应name的锁记录是否存在。执行任务时观察locked_at和locked_by字段是否更新。检查注解位置SchedulerLock必须和Scheduled注解在同一个方法上并且该方法必须是一个Spring Bean的public方法。检查AOP代理如果任务类使用了final方法、private方法或者类本身不是Spring Bean例如通过new创建AOP将无法生效锁机制会失效。确保任务类被Component等注解标记且方法可被代理。问题2任务执行时间过长锁提前失效导致另一个实例又开始执行。原因与解决lockAtMost时间设置得太短小于任务的实际执行时间。解决重新评估任务的最长执行时间考虑网络延迟、数据量增长等边界情况并适当增加lockAtMost的值。例如从10m调整为30m。同时应该优化任务本身尝试减少执行时间。问题3数据库连接池耗尽或锁表出现死锁。原因高频任务如每秒一次且lockAtLeast设置得很短导致频繁的锁获取和释放操作对数据库造成压力。解决优化任务频率重新评估是否真的需要如此高的频率。调整锁参数适当增加lockAtLeast减少竞争频率。数据库优化确保shedlock表的主键索引有效。对于MySQL可以使用SELECT ... FOR UPDATE的悲观锁模式ShedLock默认使用乐观的CAS方式但需在配置中指定。JdbcTemplateLockProvider.Configuration.builder().withIsolationLevel(Connection.TRANSACTION_SERIALIZABLE)慎用性能影响大。切换锁提供者如果性能是瓶颈考虑切换到Redis提供者。问题4在单元测试中SchedulerLock不生效或报错。原因测试环境可能没有配置锁提供者或者Spring的调度器被禁用了。解决在测试配置中可以提供一个基于内存的锁提供者如net.javacrumbs.shedlock.provider.inmemory.InMemoryLockProvider来模拟。或者在测试类上使用SpringBootTest时通过属性spring.main.web-application-typenone和spring.task.scheduling.enabledfalse来禁用调度专注于测试业务逻辑本身。踩坑记录我曾经遇到一个最隐蔽的问题任务在预发环境正常上线后锁失效。最终发现是服务器时区不一致。实例A和实例B的系统时间相差几分钟导致基于应用服务器时间的锁判断逻辑混乱。这就是为什么在配置中强烈推荐使用.usingDbTime()的原因——让数据库这个唯一的时间源来仲裁彻底解决时钟同步问题。5. 架构思考与替代方案浅析虽然SchedulerLockShedLock解决了一个非常具体的痛点且做得足够轻量和优雅但在进行技术选型时我们也需要将其放在更大的架构视角下来审视。ShedLock的定位它是一个库而非服务。它的目标是在应用层面以最小的侵入性和成本解决分布式定时任务互斥的问题。它假设你的应用已经是多实例部署并且有一个共享的存储数据库/Redis等。何时选择ShedLock项目已使用Spring Scheduling改造成本要低。定时任务数量不多频率不高分钟级及以上。团队希望保持技术栈简单不想引入重量级的分布式调度中间件。任务逻辑相对独立不需要复杂的工作流、依赖管理、失败重试策略这些可通过Spring Retry等补充基础能力。何时考虑更重量级的替代方案 当你的定时任务系统变得越来越复杂出现以下需求时可能需要考虑如Quartz Cluster、Elastic-Job、XXL-Job或Apache DolphinScheduler等专门的分布式任务调度平台任务可视化与管理需要统一的Web控制台来动态添加、修改、触发、暂停任务。任务分片一个超大数据量的处理任务需要被拆分成多个子任务分发给多个实例并行执行最后汇总结果。复杂的依赖与工作流任务B必须在任务A成功后执行任务C和D可以并行形成一个DAG有向无环图工作流。丰富的路由策略支持故障转移、忙碌转移、一致性哈希等更复杂的执行器路由逻辑。完整的执行历史与日志需要集中查看所有任务的历史执行记录、成功/失败状态以及详细日志。告警与监控任务失败后能自动通过邮件、钉钉、微信等渠道告警。个人体会在微服务架构中我倾向于根据场景分层使用。对于服务内部的、轻量的、业务逻辑紧密的定时任务比如缓存预热、本地状态清理ShedLock是首选它简洁不重完美融入Spring生态。而对于跨服务的、重要的、需要集中管控的业务定时任务比如日终对账、全量数据同步则会建立一个独立的调度中心如XXL-Job来统一管理。这种“轻重结合”的方式既能满足简单场景的敏捷性又能应对复杂场景的管控需求。SchedulerLock就像一把精准的瑞士军刀在它适用的场景里你几乎找不到比它更趁手的工具。