内容总览

Spring 生态组件 思维导图

Spring Framework 的核心容器解决了对象装配与横切逻辑的重复,但数据访问、缓存、调度、批处理这几类能力,仍然由每个项目自行落地一遍。本篇讨论的是 Spring 生态中承接这些能力的组件:它们把散落在业务代码中的同形态逻辑,收敛为接口契约加统一基础设施加执行记录。

写作顺序按起源、原理、实现、总结展开:先说明核心容器之外还存在哪些重复劳动,再逐类给出抽象机制与失效边界,最后落到配置组织、危险操作标记与常见故障排查。

一、起源:Spring 核心之外的重复劳动

Spring Framework 的两项核心思想——控制反转与面向切面——把对象的创建权和横切逻辑的织入权从业务代码转移到了容器。这两项能力解决的是“对象从哪来”和“逻辑如何插入”的问题,其原理与容器分层见 Spring Framework 核心体系。

容器之外,一个企业应用还需要数据访问、缓存、调度、批处理、外部集成五类能力。它们与业务语义无关,却与业务代码的规模成正比增长,且一旦各自实现,行为难以对齐。

1.1 三类重复劳动

重复劳动 典型形态 不收敛的后果
数据访问样板代码 每个实体重复书写增删改查、分页、排序;结果集到对象的映射逐字段书写 代码量与实体数量线性增长;各模块的分页与排序实现不一致,缺陷分散在多处
缓存与调度的散落实现 每个读方法自行拼接缓存键、判断命中、回填失效;定时逻辑以注解形式分散在各业务类中 键命名与失效路径无统一约束;任务触发时间、并发关系与执行结果不可见
批处理的可靠性要求 循环内逐条写入、失败即中断、无断点、无执行记录 大批量作业失败后只能从头重跑;失败数据无归档,问题无法追溯

三类劳动的共同特征是:与业务语义无关(横切)、形态高度统一(可抽出共性契约)、数量随业务增长(复制而非复用)。凡是同时满足这三点的逻辑,都适合由框架提供统一抽象。

1.2 收敛方式

Spring 生态对这类问题的收敛遵循同一套三段式结构:

层次 职责 对应形态
契约层 以接口或注解声明意图,不规定实现 仓库接口、缓存注解、调度注解、Job/Step 定义
基础设施层 提供统一执行引擎与集中配置 CacheManager、TaskScheduler、TaskExecutor、JobRepository
记录与观测层 把执行结果持久化或暴露为指标 作业仓库表、Actuator 端点、缓存命中率

契约层降低了调用方的样板代码,基础设施层把可变参数(线程数、过期时间、批次大小)集中到配置,记录与观测层则让“是否执行过”“执行了几次”成为可查的事实。三层的分工决定了排查故障时的观察位置:注解不生效属于契约层问题,并发行为异常属于基础设施层问题,而“任务到底跑没跑”属于观测层问题。

收敛的代价是隐式行为增加:注解依赖代理、SQL 由框架生成、框架自身维护状态(持久化上下文、作业仓库)。调试成本相应从“读代码”转向“理解框架的运行时契约”。

1.3 本文范围与引用关系

本篇不重复容器、事务与缓存本身的原理,相关的底层机制由既有文档承载:

主题 承载文档
IoC、AOP、Bean 生命周期、动态代理与内部调用失效 Spring Framework 核心体系
持久层映射路线、连接池、事务传播与回滚规则 Java 持久层
缓存的模式、更新顺序与一致性推导 缓存基础与一致性
Redis 缓存落地、防护清单与多级缓存 Redis 缓存实践与常见问题
消息模型、投递语义与顺序性 消息队列基础
自动装配、外部化配置与 Profiles Spring Boot 主脉络、application.yml 核心配置、Profiles 环境隔离
操作系统层的 cron、at 与 systemd timer 定时任务与定时器
配置中心与分布式治理 Spring Cloud 微服务治理

二、原理

2.1 Spring Data 的仓库抽象

Spring Data 要消除的是数据访问层的第三类重复:同一组增删改查与分页排序逻辑,在每个实体上重复书写。它的做法是把接口作为契约,由框架在运行期生成实现。

2.1.1 接口层次与派生查询

仓库接口按能力分层,逐层叠加:

接口 提供的能力
Repository<T, ID> 标记接口,不提供方法,用于收敛类型参数
CrudRepository<T, ID> 单个实体的保存、批量保存、按主键查询与删除、计数、存在性判断
PagingAndSortingRepository<T, ID> 在 CRUD 基础上追加按 Sort 查询与按 Pageable 分页查询
JpaRepository<T, ID> JPA 专用扩展:批量 flush、批量删除、返回 List 的排序查询、Example 查询
MongoRepository、RedisRepository、ElasticsearchRepository 等 各存储的专用扩展

最省事的能力是方法名派生查询:接口中只声明方法签名,框架在启动期解析方法名,生成对应的查询语句。

方法名片段 含义 示例
findBy / readBy / getBy / queryBy 查询前缀,语义相同 findByUserName
And / Or 条件连接 findByStatusAndType
Between / LessThan / GreaterThanEqual 范围比较 findByCreateTimeBetween
IsNull / IsNotNull / In / NotIn 空值与集合判定 findByIdIn
Containing / StartingWith / Like 字符串匹配 findByUserNameContaining
IgnoreCase 忽略大小写 findByUserNameIgnoreCase
OrderBy...Asc / Desc 排序 findByStatusOrderByCreateTimeDesc
Top / First + 数字 限制返回条数 findTop10ByStatus
existsBy / countBy / deleteBy 非查询语义 existsByUserName

派生查询的价值与代价同在。价值是零 SQL、方法签名即契约;代价有三点:方法名随条件数量增长而不可读(findByStatusAndTypeAndCreateTimeBetweenAndUserNameContaining);生成的语句不可见,性能问题需要打开 SQL 日志才能确认;条件的表达能力有限,涉及子查询、多表关联、聚合时无法表达,只能回退到注解查询。

2.1.2 注解查询与自定义实现

注解查询把语句交还给开发人员,同时保留接口的仓储语义:

写法 机制 适用
@Query("...") 默认 JPQL,面向实体与属性名 与数据库解耦,多表关联与聚合
@Query(value = "...", nativeQuery = true) 原生 SQL,面向表与列名 数据库特有语法、窗口函数、优化后的复杂查询
@Modifying 声明为写操作,配合 @Transactional 批量更新与删除
@Param 为方法参数命名,供语句引用 多参数方法
@Query + countQuery 分页时为原生 SQL 单独提供 count 语句 原生 SQL 分页

自定义实现用于派生查询与注解查询都无法表达的逻辑(含状态判断的多表写入、调用存储过程)。Spring Data 的约定是“片段接口加实现类”:声明一个 UserRepositoryCustom 接口,提供 UserRepositoryCustomImpl 实现,然后让 UserRepository 同时继承两者。实现类的命名后缀由 repositoryImplementationPostfix 配置,默认为 Impl,命名不符时框架不会报错,只会表现为方法找不到实现——这是自定义实现接入失败最常见的原因。

2.1.3 分页与排序抽象

分页与排序被抽象为可传递的值对象,与具体存储无关:

类型 承载内容 说明
Pageable 页码、页大小、Sort 接口,PageRequest.of(page, size, sort) 为常用实现
Sort 排序字段与方向的有序集合 支持多字段与嵌套属性
Page<T> 当前页数据 + 总数 + 总页数 + 是否有下一页 需要额外执行一次 count 查询
Slice<T> 当前页数据 + 是否有下一页 只多取一条判断,不执行 count
Pageable.unpaged() 不分页 返回全集,大表上等于内存分页

Page 与 Slice 的差别是一次 count 查询。count 在复杂条件与大表上本身就是高成本查询,因此列表类交互优先使用 Slice,需要展示总页数或总条数时才使用 Page。分页的物理代价(大偏移量的扫描与丢弃)属于 SQL 层问题,见 3.1 节。

排序字段若来自请求参数,必须经过白名单校验:Sort 的字段名会被直接拼入 ORDER BY,未校验时构成注入面。

2.1.4 投影与动态查询

查询结果不总是需要完整实体。投影用于只取需要的列:

投影方式 写法 特点
接口投影 定义只含 getter 的接口,方法返回该接口 由框架生成代理,只查询被访问的属性(JPA 下为闭合投影时可按需取列)
类投影(DTO) 构造器表达式 select new com.example.dto.UserView(u.id, u.name) 类型安全,无代理,适合跨层传递
动态投影 方法签名的最后一个参数为 Class<T> 同一查询按调用方需求返回不同视图

动态查询用于条件数量不确定的场景,三种手段的定位不同:

手段 表述方式 边界
Specification(JPA Criteria) 类型安全的谓词组合 表达能力强,可读性差,条件复杂时难以维护
Query by Example 以实体实例作为条件模板 只支持等值与简单匹配,不支持范围与嵌套
Querydsl 生成的 Q 类型 编译期校验,需要额外的注解处理器与构建配置

三条路线都增加了构建期或运行期的复杂度。条件数量在可枚举范围内时,若干条显式方法(或 @Query 加动态标签)比引入一套动态查询框架更容易维护,判定标准是“条件组合是否可穷举”。

2.1.5 与 SQL 优先方案的边界

Spring Data 的仓库抽象在 ORM 路线上收益最大,在 SQL 优先路线上收益有限。MyBatis 也有对应的 Mapper 扫描机制,但它的接口方法对应一条手写语句,不承担语句生成职责,因此不存在“方法名派生”这一层能力。

两条路线的取舍维度(SQL 控制权、复杂查询、性能可预测性、混合使用的边界)见 Java 持久层 第 2.5 节。这里只补充与仓库抽象直接相关的三条结论:

  1. 仓库抽象不承担 SQL 质量责任。索引是否命中、是否存在隐式转换、count 语句代价如何,仍由 SQL 与表结构决定。
  2. 同一实体只应由一条路线写入。若 JPA 与 MyBatis 同时写同一张表,仓库抽象下的二级缓存与持久化上下文无法感知手写 SQL 的写入,会出现“查到的还是旧对象”。
  3. 派生查询适合简单形态,注解查询适合复杂形态。把聚合统计与报表类查询强行写成派生方法,会同时损失可读性与性能可控性。

2.2 Spring Cache 的机制

缓存的模式、更新顺序与一致性推导属于缓存理论,见 缓存基础与一致性 第 2.2 节至第 2.4 节。本节讨论的是 Spring Cache 这一层抽象:注解如何工作、键如何生成、条件如何判断、失效由谁负责。

2.2.1 注解语义

Spring Cache 用四个注解覆盖缓存的三种动作:

注解 动作 关键属性 说明
@Cacheable 读缓存,未命中则执行方法并回填 value、key、condition、unless、sync 方法在命中时不会执行
@CachePut 执行方法,并把结果写入缓存 同上,无 sync 方法总会执行
@CacheEvict 删除缓存条目 key、allEntries、beforeInvocation 默认方法成功返回后删除
@Caching 组合以上多个动作 cacheable、put、evict 数组 一次调用需要同时读写多个缓存时使用

调用时序:调用方访问的是代理对象,代理先计算键、查询缓存;命中则直接返回,未命中则执行目标方法并把返回值回填。由此推出三条约束:

  • 方法抛异常时不回填缓存,@CachePut 也不会写入,避免缓存中留下失败结果。
  • 方法返回空值默认不写入(Redis 缓存配置中 disableCachingNullValues 时尤其如此)。空值缓存是防穿透的常规手段,需要显式开启并给出较短过期时间。
  • sync = true 会把回源动作变为互斥,用于抑制同一实例内的缓存击穿。互斥作用范围是单个 JVM,多实例部署下每个实例各有一把锁,热点键的并发回源仍然存在。

@CacheConfig 可在类级别统一声明 cacheNames、keyGenerator、cacheManager,减少方法上的重复属性。

2.2.2 键生成与自定义

键由 key 属性(SpEL 表达式)或 keyGenerator 决定,二者只能选一。未声明时使用 SimpleKeyGenerator,其规则是按参数拼接:

参数数量 生成的键
无参数 SimpleKey.EMPTY
单参数 参数对象本身作为键
多参数 SimpleKey 对象,由全部参数的哈希值构成

默认规则在三种情况下会出问题:一是多参数方法生成的键不可读,排查时无法从键反推入参;二是参数对象未重写 equals 与 hashCode 时,键的比较退化;三是不同方法若共用同一 cacheName 且参数形态相同,可能产生键冲突。因此业务缓存应显式声明 key:

@Cacheable(cacheNames = "user", key = "#tenantId + ':' + #userId")
public UserProfile getProfile(String tenantId, Long userId) {
    return userRepository.findById(userId).orElse(null);
}

键的命名规范、序列化格式与基数控制属于缓存落地范畴,见 Redis 缓存实践与常见问题 第 3.1 节。

2.2.3 条件与 unless

两个条件属性的求值时机不同,这是使用中最容易混淆的一点:

属性 求值时机 可引用内容 典型用途
condition 目标方法执行之前 方法参数 只对部分入参启用缓存,例如仅缓存非测试租户的数据
unless 目标方法执行之后 方法参数与 #result 结果为空时不写入缓存
// 结果为空不缓存;命中缓存的键可被 allEntries 整体清除
@Cacheable(cacheNames = "config", key = "#key", unless = "#result == null")
public String getConfig(String key) { ... }

// 只对生产租户启用缓存
@Cacheable(cacheNames = "user", key = "#userId", condition = "#tenantId != 'test'")
public UserProfile getProfile(String tenantId, Long userId) { ... }

condition 不成立时方法正常执行且不读写缓存,等价于跳过缓存逻辑;unless 不成立(即条件为真)时不写入,但已命中的读取不受影响。需要“读到旧值时也重新执行方法”这类需求,不属于注解的表达范围,应改用逻辑过期加异步刷新等手动方案。

2.2.4 缓存管理器与多缓存的取舍

CacheManager 是缓存的工厂抽象,决定键值落在哪里、如何序列化、过期时间多长:

实现 存储位置 适用
ConcurrentMapCacheManager 进程内 ConcurrentHashMap 本地开发与测试,无过期与容量上限
CaffeineCacheManager 进程内 Caffeine 热点数据本地缓存,可设条目上限与过期
RedisCacheManager Redis 多实例共享,可按键前缀设置不同过期配置
CompositeCacheManager 组合多个管理器 多级缓存,按顺序查找

一个 CacheManager 下可以有多个 cacheName,各自配置不同的过期时间与序列化方式(配置方式见 Spring Boot 企业级项目实践指导手册 第 4.3 节)。这里需要明确的取舍是:每增加一个缓存,就增加一份需要维护一致性的数据副本。缓存数量与失效路径的复杂度成正比,判定是否新增缓存的依据是读放大系数与数据变更频率,而不是“访问多了就该缓存”。

多缓存的另一层取舍是本地缓存与分布式缓存并存(多级缓存)。本地缓存省去网络往返,代价是实例间数据不一致的窗口等于本地过期时间。两者组合的失效传播方式与一致性取舍见 Redis 缓存实践与常见问题 第 3.6 节,本地缓存的容量与失效风险见 日志规范与常用类库 第 2.7 节中“本地缓存的容量与失效”。

2.2.5 代理自调用失效

缓存注解与事务注解、异步注解同源,均通过代理实现。代理只拦截外部对目标对象的调用,类内 this.methodB() 的调用绕过代理,methodB 上的 @Cacheable、@CacheEvict 不生效且不报错。

现象 根因 定位方式
注解“看起来没生效”,命中率恒为 0 自调用绕过代理 检查调用链是否为同类内部调用;打断点观察是否进入代理
部分方法生效、部分不生效 生效的是外部入口,不生效的是内部调用 逐条核对方法调用来源
启动即报错 缓存配置缺失(如 @EnableCaching 未声明) 启动日志中的自动配置报告

处理方式与事务自调用失效一致:自注入本类代理、使用 AopContext.currentProxy()(需开启 exposeProxy)、把方法拆分到另一个 Bean、或改用 CacheManager 直接编程式读写。代理机制与两种代理实现的差别,见 Spring Framework 核心体系 中“动态代理与内部调用失效”一节。

@EnableCaching 未声明时缓存注解完全不起作用——注解保持了合法语法,编译器与运行期都不报错,这是“缓存未生效”最常见的一类原因。

2.2.6 失效路径与一致性

缓存失效有两条路径:

路径 触发方式 特点
主动失效 @CacheEvict 标注在写方法上,或编程式调用 Cache.evict() 变更后立即生效,依赖写路径不遗漏
被动失效 过期时间到期 兜底,收敛任何遗漏;过期时间的长度即不一致窗口的上限

两条路径必须同时存在。只有主动失效时,任何一处遗漏都会造成长期不一致;只有被动失效时,不一致窗口等于过期时间。@CacheEvict 的 beforeInvocation = true 会在方法执行前删除,用于“数据库操作可能失败但缓存必须清空”的场景;默认值 false 表示方法成功返回后删除,语义与“先更新数据库再删除缓存”一致。

缓存与数据库的更新顺序决定了不一致窗口的形状,“先更新数据库、再删除缓存”是窗口最短的选择,四种顺序的对比与延迟双删、变更日志驱动失效的取舍见 缓存基础与一致性 第 2.4 节。与注解使用直接相关的一条约束是:@CacheEvict 若标注在 @Transactional 方法内,删除动作发生在事务提交之前——事务随后回滚时,缓存已被删除且不会恢复,此时若并发读请求把旧值回填,缓存中会留下已被回滚的数据。正确做法是把删除动作绑定到事务提交之后(实现方式见 3.2 节)。

2.3 任务调度

调度解决的是“某段逻辑在指定时间或按固定节奏执行”。与操作系统层的 cron、at、systemd timer(见 定时任务与定时器)相比,应用内调度的差别在于:触发点在应用进程内,能够直接使用应用上下文、连接池与业务代码,但生命周期与进程绑定,且多实例部署时每个实例都会独立触发。

2.3.1 实现方式

方式 声明形态 适用
@Scheduled 方法上的注解,配合 @EnableScheduling 固定节奏、无需持久化与动态变更的任务
SchedulingConfigurer 实现接口,在运行期注册 Trigger 触发规则来自配置或数据库
TaskScheduler 编程式 显式提交 Runnable 需要按条件注册与取消
Quartz JobDetail + Trigger,作业与触发器可持久化 需要持久化、错过补偿、集群化、动态增删改

@Scheduled 的四种属性形态:

属性 语义 起点
fixedDelay 上一次执行结束后延迟固定毫秒数再执行 上次结束时刻
fixedRate 按固定毫秒数周期推进,与上次执行耗时无关 上次开始时刻
cron 按日历表达式触发 日历时间
initialDelay 首次执行的延迟,与前两者或 cron 组合使用 应用启动

固定频率与 cron 的差别有两层。语义上,fixedRate 表达“每隔 N 毫秒一次”,cron 表达“在日历上的某些时刻触发”;跨时区、夏令时、每月末、工作日等规则只有 cron 能表达。实现上,fixedRate 以上次开始时刻为基准累加,cron 每次重新计算下一个日历时刻,因此 cron 不会因为单次执行耗时而漂移,fixedRate 会。

需要注意 Spring 的 cron 表达式有六个字段(秒、分、时、日、月、周),而操作系统 cron 是五个字段(分、时、日、月、周),且前者的日在周两个字段通常需要在其中一个上填 ?。把系统 crontab 的表达式直接搬到注解上会解析失败或触发时间与预期不符。

2.3.2 执行时间超过间隔

调度器的默认线程池只有一个线程。这一默认值带来两个后果:多个 @Scheduled 方法之间相互阻塞(一个任务耗时过长会推迟其他任务的触发);单个任务若执行时间超过间隔,行为取决于声明方式:

声明方式 上次执行未结束时到达下一次触发点 结果
fixedDelay 未结束则不会触发,间隔从结束时刻起算 无重叠,实际周期 = 执行耗时 + 间隔
fixedRate 触发点被记录,任务结束后立即补执行 出现连续执行,实际周期被压缩,堆积时表现为“一直在跑”
cron 与 fixedRate 类似,按日历时刻触发;默认单线程下排队 连续执行,直到追上日历进度

因此固定频率类任务应优先选择 fixedDelay:它的语义是“两次执行之间留出休息时间”,天然避免了重叠。确实需要重叠执行的场景,正确做法是把耗时部分交给独立的线程池异步处理,而不是依赖 fixedRate 的补执行行为——补执行只会拉长队列,不会提高吞吐。

避免任务相互影响的方式是显式配置调度线程池:

@Configuration
@EnableScheduling
public class SchedulingConfig implements SchedulingConfigurer {

    @Override
    public void configureTasks(ScheduledTaskRegistrar registrar) {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        // 按任务数量与最长耗时设置,避免线程过少造成相互阻塞
        scheduler.setPoolSize(4);
        scheduler.setThreadNamePrefix("sched-");
        // 关闭时等待正在执行的任务结束
        scheduler.setWaitForTasksToCompleteOnShutdown(true);
        scheduler.setAwaitTerminationSeconds(30);
        scheduler.initialize();
        registrar.setTaskScheduler(scheduler);
    }
}

高危:修改调度线程池大小与任务触发频率会直接改变任务对数据库与其他下游的并发压力。线程池调大后,原本相互排队的长任务会同时执行,连接池占用与下游 QPS 按并发数放大;频率调密(例如从每 10 分钟改为每分钟)会使单次执行耗时尚未被观测的情况下重复叠加负载。变更前需确认任务的实际执行耗时分布(P99)、单次执行占用的连接数与对下游的调用量,并核算“任务并发数 + 在线并发数 ≤ 连接池上限”,在业务低峰期发布。回滚方式:参数改回原值并重启或触发配置刷新;若已产生积压任务,需先停止调度、清空待执行队列,再按执行记录逐次补数。

2.3.3 异常、重试与幂等

@Scheduled 方法抛出的异常由调度器捕获并记录日志,不会中断后续触发。这一行为有两个推论:一是任务失败不会自动重试,也不会向上传播到任何调用方;二是任务的成功与否只能通过日志与执行记录判断。

由此产生三条实践约束:

  1. 捕获与记录:任务方法内部应捕获异常、记录任务名与关键参数,并暴露成功/失败计数,否则失败只体现为一行日志。
  2. 重试要显式实现:重试只对可恢复异常有意义,且必须带次数上限与退避。重试逻辑应放在任务方法之外或独立任务中,避免单次执行时间无界增长。
  3. 幂等由业务键保证:任何可能重复执行的任务都必须幂等,重复的来源包括补执行、人工重跑、多实例同时触发、以及发布过程中的新旧实例并存。幂等实现依赖数据库唯一约束、状态条件更新(UPDATE ... WHERE status = 'PENDING')或去重表,具体手段见 消息可靠性与幂等设计。

2.3.4 分布式调度的必要性

应用横向扩容后,每个实例都会独立触发 @Scheduled 任务,同一时刻执行 N 份相同逻辑。后果按任务类型分化:

任务类型 多实例重复执行的后果
只读统计、缓存预热 重复计算,资源浪费,指标偏高
批量发送通知、生成单据 业务数据重复,用户可感知
扫描并修改状态的批处理 并发修改同一批数据,可能相互覆盖或死锁

因此进入多实例部署后,调度必须有“同一时刻只由一个执行者负责”的机制。两条实现思路:

思路 机制 优点 边界
选主(抢占式) 各实例定时尝试获取分布式锁,抢到者执行 无需额外组件,改造量小 锁的持有与释放存在失效窗口;任务不可分片;执行记录分散在各实例;无统一的重试与告警;实例漂移会造成触发时间抖动
调度中心(派发式) 中心按配置触发,向注册的实例派发执行请求,实例回报结果 触发唯一,执行记录与重试集中,支持动态变更与分片 引入新的组件与运维面,中心成为必须保障可用性的节点

调度中心的代表实现包括 XXL-JOB 一类平台化工具,以及 Quartz 的集群模式(通过数据库锁实现作业不重复触发的集群调度)。选型的对照维度与迁移注意点见 3.3 节。

分布式调度还要回答任务分片的问题:数据量大的任务需要拆成多个子任务并行处理,每个分片只处理数据的一个子集。分片的边界有三条:分片数在运行时确定(按实例数或固定分片数),扩容缩容会改变分片与数据的映射;分片键的分布决定各分片的负载,倾斜会使并行退化为串行;单个分片失败时的语义需要明确——是整体失败后全量重跑,还是记录失败分片单独重试。分片任务的幂等要求比单实例任务更高,因为扩缩容与重试都会改变分片归属。

2.4 异步与事件

异步解决的是“主流程不应等待某段逻辑完成”。Spring 提供了两个层次的异步:方法级的 @Async 与事件级的 @EventListener 加异步投递。

2.4.1 @Async 的执行路径

@Async 同样基于代理:调用方访问代理,代理把方法调用封装为任务提交给 TaskExecutor 并立即返回。由此产生两条约束:

  • 返回值受限于提交方式。返回 void 表示不关心结果;返回 Future 或 CompletableFuture 才能获取结果与异常。返回其他类型时调用方拿到的是尚未执行完成的对象。
  • 自调用失效,原因与事务、缓存注解一致。

线程池的配置参数与线程池原理(核心线程数、队列、拒绝策略的扩容顺序)见 Java 并发编程 第九节。Spring 封装为 ThreadPoolTaskExecutor,参数含义不变,需额外关注两点:线程池的有界队列优先于最大线程数生效——队列未满时不会创建超过核心数的线程,因此队列容量直接决定“何时开始快速失败”;以及线程名前缀与拒绝策略必须显式设置,否则拒绝发生时无法定位是哪个线程池。

拒绝策略 行为 适用
AbortPolicy 抛出 RejectedExecutionException 需要让调用方感知过载(默认策略)
CallerRunsPolicy 由提交任务的线程执行 允许降级为同步执行,形成天然背压
DiscardPolicy 静默丢弃 仅用于可丢任务,且必须配合计数告警
DiscardOldestPolicy 丢弃队列中最旧的任务后重试提交 队列中任务时效性强于数量时

2.4.2 事务与异步的边界

事务上下文保存在 ThreadLocal 中,不随线程切换传播:

场景 结果
事务方法内调用 @Async 方法 异步方法在新线程执行,不加入外层事务
异步方法读取外层未提交数据 读不到,不同连接、不同事务
异步方法抛异常 不回滚外层事务,外层无感知
外层事务回滚 异步任务已经提交或已执行,不会回滚

最后一行是实践中最容易出问题的一条:在事务内派发异步任务,事务回滚后异步任务仍会执行,造成“业务失败但副作用已产生”。正确做法是把异步派发移到事务提交之后,实现方式见 3.4 节。事务、连接与线程绑定的完整机制见 Java 持久层 第 2.7 节。

异步线程还需要显式传递上下文。ThreadLocal 中的内容(请求标识、用户身份、租户信息)在线程切换后丢失,需要 TaskDecorator 在任务提交时复制、在任务结束时清理。线程池中的线程长期存活,ThreadLocal 的值被线程对象强引用,未清理会造成内存泄漏,机制与判读方式见 JVM 内存与垃圾回收 第 3.5 节。

2.4.3 应用内事件的投递

Spring 的事件机制基于观察者模式,三个角色分别是事件、发布者(ApplicationEventPublisher,应用上下文本身即可用)与监听者(@EventListener 方法)。默认投递是同步的:发布线程会依次执行所有匹配的监听器,监听器的耗时直接累加到发布线程上。

关注点 实现方式 说明
监听顺序 @Order 仅在同步投递时有确定意义
异步投递 监听方法上加 @Async 需要 @EnableAsync 与线程池;监听器异常不再传播给发布者
事务绑定 @TransactionalEventListener 可按阶段绑定:BEFORE_COMMIT、AFTER_COMMIT(默认)、AFTER_ROLLBACK、AFTER_COMPLETION
条件过滤 condition 属性(SpEL)或事件类型区分 避免在监听器内做无意义的早期返回

事务绑定是事件机制在工程上最有价值的一点:AFTER_COMMIT 的监听器只在事务成功提交后执行,天然满足“事务内不做副作用”的约束。需要留意的边界是:AFTER_COMMIT 阶段执行的动作不再有事务,其内部的数据库写入需要自行开启新事务;若希望提交后异步执行,需要同时使用 @TransactionalEventListener 与 @Async,此时监听器异常同样不会传播。

应用内事件与消息队列解决的不是同一层问题:

维度 应用内事件 消息队列
作用范围 单个进程内的模块解耦 跨进程、跨服务
投递可靠性 进程内方法调用,进程退出即丢失 由中间件提供持久化、重投与确认
顺序与并发 由线程模型决定 由分区与消费者组决定,可显式约束
失败处理 监听器异常需自行捕获,无重试机制 重试、死信、堆积监控
适用 同一应用内的事务后动作、领域事件通知 服务间解耦、削峰、跨系统数据同步

判定标准是“消费者是否在同一进程内”。跨进程通信借助应用内事件模拟(例如把事件写入本地表再由定时任务转发)会引入额外的可靠性与时序问题,这类需求应由消息中间件承担,消息模型与投递语义见 消息队列基础 第二章。

2.5 Spring Batch

批处理与在线请求的区别在于:处理对象是大批量数据,执行时间长,且必须能够在失败后继续而不是从头再来。Spring Batch 把批处理的共性问题(事务划分、断点、跳过、统计)做成框架能力,业务代码只实现读写与处理逻辑。依赖坐标与定位见 Spring Boot Starter 汇总。

2.5.1 作业模型

概念 职责 关键点
Job 一次批处理任务的整体定义 由若干 Step 按顺序组装,可带条件流转
Step 一个处理阶段 分块(chunk)型或任务件(tasklet)型
ItemReader 读取数据 需支持分次读取,通常带游标或分页
ItemProcessor 转换与校验 返回 null 表示过滤掉该条,可选
ItemWriter 批量写出数据 接收的是一个批次列表,而非单条
JobLauncher 启动作业 传入 JobParameters
JobRepository 记录执行元数据 需要数据库表,记录 JobInstance、JobExecution、StepExecution
JobExplorer 查询执行历史 用于运维查询与重启判断

分块模型是核心执行单元:读取 N 条(chunk size),逐条处理,然后在一个事务内一次性写出 N 条,提交事务,循环直到数据耗尽。chunk size 同时决定了事务边界与内存占用,是批处理调优的第一个参数:

取值 效果
过小 事务次数多,提交开销与网络往返占比上升,吞吐低
过大 单个事务持有的锁与 undo/redo 量增大,失败重试的代价上升,内存中缓存的数据量上升
经验区间 数百至数千条,最终取值以压测为准,并受单条数据大小影响

监听器提供了各阶段的介入点:JobExecutionListener(作业前后)、StepExecutionListener(步骤前后)、ChunkListener(分块前后与出错时)、ItemReadListener、ItemProcessListener、ItemWriteListener(单条读写的前后与出错)、SkipListener(被跳过的记录)、RetryListener(重试前后)。监听器是记录进度、统计失败数与落地失败明细的位置。

2.5.2 分片与并行

手段 机制 边界
多线程 Step 单个 Step 内用线程池并发执行分块 ItemReader 与 ItemWriter 需线程安全;Reader 的游标语义在并发下难以保证,通常不适用
本地分区 Partitioner 把数据切成多个分区,各分区作为独立 Step 并行执行 分片键的分布决定负载均衡;各分区共享同一 JobRepository,并发写入元数据表会加重其负担
远程分区 分区任务分发到多个进程执行 需要额外的调度与消息通道;网络分区与节点故障的处理逻辑需要自行设计
并行 Job 不同 Job 同时运行 需要控制并发度,避免作业之间争抢数据库资源

分片与并行提高的是吞吐,不改变“数据量决定总工作量”这一事实。当瓶颈在数据库侧的写入能力时,提高并发只会加剧锁竞争与复制延迟,此时应回到批次大小与写入语句形态上优化,大批量作业对数据库复制的影响见 MySQL 主从部署与运维实践 第 2.2 节。

2.5.3 重启与跳过

重启的前提是可识别与可定位。JobParameters 与作业名共同决定 JobInstance 的唯一性:参数完全相同视为同一个实例,重复启动会被拒绝;参数不同则创建新实例。因此需要重复执行的作业通常会在参数中加入时间戳或批次标识。重启时框架从上次失败或中断的 Step 继续,已成功完成的 Step 默认跳过——这一行为与“从断点续传”的直觉一致,但它依赖两个条件:

  1. ItemReader 可重入。基于游标或分页读取的 Reader 在重启后需要能定位到中断位置(例如按主键范围或状态标记重新筛选),否则会出现重复读取或遗漏。Spring Batch 提供的 JdbcCursorItemReader 类在重启场景下的行为需要在设计时确认(使用 saveState 时状态由框架保存,但状态与数据的一致性依赖 Reader 的实现)。
  2. ItemWriter 幂等。重启会重新处理失败块中的数据,若写入不具备幂等性(例如无条件的 INSERT),会产生重复数据。可行做法是“以业务唯一约束兜底”或“先删除后写入同一批次的数据”。

跳过策略用于处理“少量数据不符合业务规则但不希望整个作业失败”的场景:声明可跳过与可重试的异常类型及上限,超限则作业失败;被跳过的记录通过 SkipListener 写入失败明细表,由人工或后续作业处理。三条约束需要明确:

  • 跳过上限必须有具体数值,Long.MAX_VALUE 意味着问题数据不会被及时发现。
  • 跳过与重试的异常类型必须区分:格式错误类异常可跳过,数据库连接类异常应重试,业务规则类异常应让作业失败。
  • 被跳过的数据不属于“处理成功”,作业的成功状态需要结合跳过数量判断,不能只看作业是否完成。

作业仓库保存执行元数据,其表结构由框架在建表脚本中给出。运行期需关注两点:元数据表随执行次数持续增长,需要定期清理历史数据(清理前确认不再需要重启历史执行);元数据表与应用业务表通常共用数据源,作业卡死时排查连接占用不应只看业务表。

  • 高危:批量作业全量重跑会重新处理全部数据,在数据库侧对应一次全量的读加写操作,产生的 binlog 事务与锁持有时间可能使从库出现分钟级复制延迟,并使在线请求的连接池等待上升。执行前必须确认:是否有可用的增量/断点重跑方式(改变 JobParameters 之外的作业参数或指定主键范围);数据写入是否幂等(非幂等写入在全量重跑后会产生重复数据);数据库侧的复制延迟容忍度、磁盘余量与备份状态;以及在线流量的低峰窗口。执行期间需要观察复制延迟、数据库 QPS、应用连接池等待与作业处理速率。回滚方式:作业级回滚依赖执行前的数据库备份,或按批次标识反向删除本次写入的数据;若只需中止,可停止作业实例,已提交的批次按批次标识清理。重跑前必须先在测试环境验证重启路径与幂等性。

2.6 集成与适配

外部系统集成的问题不在“能否调通”,而在差异的收口位置。适配层的目标是把外部系统的协议、错误语义、超时行为与技术栈差异限制在一个模块内,使业务代码只依赖内部接口。

2.6.1 适配层的职责

职责 内容 不收口的后果
协议转换 请求报文的构造与响应报文的解析 序列化细节散落,字段变更需要全量修改
错误语义映射 外部错误码转换为内部异常体系 业务代码需要理解每个外部系统的错误码
超时与容量 连接超时、读超时、并发上限 外部系统变慢直接拖垮调用方线程池,形成级联故障
重试与幂等 重试条件、次数、退避、幂等键 重试散落各处,重复提交无法控制
观测 调用量、耗时、失败率、错误码分布 故障时无法区分是外部系统异常还是本系统问题

超时预算的设定原则是:单次外部调用的超时上界必须小于调用链上游剩余的超时额度,使失败能够在预算内收敛为降级结果,而不是把上游整体拖超时。这一点对同步链路尤其重要,链路超时预算的设定方式见 消息队列基础 第 1.1 节。

2.6.2 重试与幂等

重试的四条约束:重试位置在事务之外(事务内重试时失败的语句已标记回滚,后续重试无法提交);只对可恢复异常重试(连接超时、死锁回滚、限流拒绝),业务校验失败不重试;必须有次数上限与退避(立即重试对资源不足类故障无效);被重试的操作必须幂等。幂等的实现手段(去重表、唯一约束、状态机、幂等键)与重试策略的设计见 消息可靠性与幂等设计。

Spring 的重试能力(@Retryable 与 RetryTemplate)提供声明式的重试与退避,使用时需要确认它作用在代理上,因而同样受自调用失效的约束,且重试次数与超时预算需要与上游超时对齐,否则会在上游已经超时放弃后继续重试。

2.6.3 与消息和批处理的组合

三类机制在集成场景中承担不同角色,组合方式如下:

场景 主机制 配合机制
跨系统数据同步(实时性要求高) 消息队列投递变更 消费端幂等 + 死信队列承接失败消息
跨系统数据同步(实时性要求低、数据量大) 批处理按周期拉取与写入 用增量游标控制单次处理量
本系统写入与外部通知的一致性 事务提交后投递消息 本地消息表或事务消息保证“写入成功则必然投递”
外部系统不可用期间的补偿 批处理对账 以定时任务扫描差异并修正

最后一行体现的是“对账加补偿”这一通用思路:实时链路允许失败,由周期性的对账任务发现并修正不一致。对账任务本身必须幂等且可重入,其设计要点与消息侧的最终一致性方案属于同一谱系,见 消息一致性:事务消息与最终一致性;跨服务的写入一致性与事务方案取舍见 Java 分布式事务实践。

企业集成模式(消息通道、路由、转换、端点适配)有对应的框架实现(Spring Integration)。它的价值在于把大量适配器与路由逻辑声明化,代价是引入一套新的配置与调试模型——链路的走向由多个通道与端点组合而成,出问题时需要在框架的运行时结构里定位。判定是否引入的标准是集成链路数量与形态的稳定性:少量固定链路用代码直写更易维护,链路多且形态频繁变化时框架收益才显现。

2.7 组件取舍

框架抽象并非默认正确选项,它交换的是“样板代码量”与“运行时透明性”。

判定维度 倾向使用框架抽象 倾向自行实现
逻辑形态 与既有抽象高度一致(标准 CRUD、标准读缓存) 形态特殊,需要精确控制时序与并发
一致性要求 需要统一语义(事务边界、重试规则、执行记录) 语义简单,一次调用即可完成
调试成本 团队理解框架运行时契约 框架的隐式行为已成为排查负担
变更频率 逻辑稳定,抽象不会频繁被绕过 逻辑处于快速试错期
运维要求 需要集中观测与统一告警 无需集中记录

引入抽象带来的调试成本集中在四处,这些成本在选型时容易被低估:

隐式行为 表现 成本
代理 注解在自调用、private、final 方法上静默失效 需要理解代理边界才能定位
语句生成 实际执行的 SQL 与源码不一致(派生查询、ORM 生成) 需要打开 SQL 日志或使用代理式 SQL 日志
框架状态 持久化上下文、缓存、作业仓库、调度注册表在运行期维护状态 状态的生命周期成为排查路径的一部分
自动配置 配置缺失时的默认行为不可见 需要借助自动配置报告确认生效条件

一条实用的判定原则是:抽象的价值等于它消除的重复劳动量减去它引入的排查成本。当重复劳动量小(例如只有三处缓存)或排查成本高(例如核心链路的事务与缓存时序)时,显式代码更合适。

三、实现

3.1 数据访问实践

3.1.1 仓库的组织

仓库接口按聚合根划分,一个聚合根一个接口,避免把不同业务域的查询堆在同一接口上。派生方法与注解查询的分界线是“条件是否可枚举且简单”:

public interface UserRepository extends JpaRepository<User, Long>, UserRepositoryCustom {

    // 条件固定且简单:派生查询
    List<User> findByStatusAndCreateTimeBetween(UserStatus status, LocalDateTime from, LocalDateTime to);

    // 只有一条结果:返回 Optional 而非 null
    Optional<User> findByUserName(String userName);

    // 分页列表:用 Slice 避免 count
    Slice<User> findByStatus(UserStatus status, Pageable pageable);

    // 复杂语句:注解查询,语句显式可见
    @Query("select u from User u join fetch u.profile where u.id in :ids")
    List<User> findWithProfileByIds(@Param("ids") Collection<Long> ids);

    // 批量写入:声明为写操作
    @Modifying(clearAutomatically = true)
    @Query("update User u set u.status = :status where u.id in :ids")
    int updateStatusByIds(@Param("ids") Collection<Long> ids, @Param("status") UserStatus status);

    // 自定义实现:派生与注解都无法表达的逻辑
    long countActiveByComplexRule(UserQuery query);
}

@Modifying(clearAutomatically = true) 用于让批量更新绕过持久化上下文后清理上下文,避免上下文中的实体与数据库不一致——批量更新不经过实体状态管理,上下文中残留的旧实体是这类不一致的常见来源,机制见 Java 持久层 第 2.4.3 节。

3.1.2 分页与深分页

分页的使用约定有三条:列表类接口默认用 Slice;需要总数时显式使用 Page 并评估 count 语句代价;排序字段来自请求参数时必须经白名单校验。

深分页的代价在于偏移量的语义是“扫描并丢弃”,成本与偏移量成正比。优化方向按优先级为:改为游标/键集分页(WHERE id > :lastId ORDER BY id LIMIT :size,适用于顺序翻页);用延迟关联先在覆盖索引上定位主键再回表;限制可翻页深度并引导收窄查询条件。深分页的执行计划判读与索引设计见 MySQL 索引与执行计划。

// 键集分页:以排序键定位,避免大偏移量
@Query("select u from User u where u.createTime < :lastCreateTime order by u.createTime desc")
Slice<User> findNextPage(@Param("lastCreateTime") LocalDateTime lastCreateTime, Pageable pageable);

3.1.3 批量操作与事务大小

批量写入的性能取决于语句是否合并与提交是否分批。三条约束:单批控制在数百至数千行,批次大小以“单次网络包与数据库侧锁持有时间可接受”为准;批量整体在一个事务内可保证原子性,但事务过大会加重锁等待与复制延迟,通常按业务可容忍的部分成功划分批次;多值插入无法逐行返回自增主键,需要主键时改用逐行插入或提前生成分布式主键,生成方式与分片下的主键冲突问题见 分库分表与全局唯一 ID。

批量操作的批次与事务设计、复制延迟的成因见 Java 持久层 第 3.4 节与 MySQL 主从部署与运维实践。

  • 高危:批量更新或删除时若 WHERE 条件未按主键范围限定(例如只按状态条件更新全表),会在数据库中持有大量行锁并可能升级为表级锁,阻塞其他会话的读写,同时生成的单个大事务会造成从库回放延迟。执行前必须用相同的 WHERE 条件执行 SELECT COUNT(*) 与 EXPLAIN,确认影响行数与执行计划,选择业务低峰期执行,并按主键范围分批(每批数千行)且批次之间留出间隔。回滚方式:执行前的备份或按受影响主键列表执行反向语句;若只需中止,终止执行会话并回滚未提交部分,已提交批次按反向语句处理。

3.2 缓存实践

3.2.1 配置组织

缓存配置集中在配置类中声明,键与过期时间按业务维度分组,不在各业务类中零散设置。多缓存的过期时间差异通过 withInitialCacheConfigurations 表达,写法见 Spring Boot 企业级项目实践指导手册 第 4.3 节;Redis 连接池与超时配置项见 application.yml 核心配置 第三章。连接与超时必须显式设置,使缓存故障能在可接受时间内退化为回源:

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      # 超时小于接口整体预算,缓存故障退化为回源而不是把接口拖超时
      timeout: 500ms
      lettuce:
        pool:
          max-active: 16
          max-wait: 200ms

3.2.2 注解使用与失效策略

@Service
public class UserQueryService {

    private final UserRepository userRepository;

    // 读缓存:显式键,空值不缓存;condition 控制只对在线租户启用
    @Cacheable(cacheNames = "user:profile", key = "#tenantId + ':' + #userId",
               condition = "#tenantId != null", unless = "#result == null")
    public UserProfile getProfile(String tenantId, Long userId) {
        return userRepository.findById(userId)
                .map(UserProfile::from)
                .orElse(null);
    }

    // 写路径:更新数据库并删除缓存;删除动作在事务提交后执行
    @Transactional
    public void updateProfile(Long userId, ProfileUpdateCommand command) {
        userRepository.updateProfile(userId, command);
        // 注册事务同步回调,保证缓存删除发生在提交成功之后
        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
            @Override
            public void afterCommit() {
                cacheEvictor.evict("user:profile", command.tenantId() + ":" + userId);
            }
        });
    }
}

把删除动作绑定到提交之后的两种实现方式:在事务方法内注册 TransactionSynchronization 的 afterCommit 回调;或发布领域事件并用 @TransactionalEventListener(phase = AFTER_COMMIT) 监听。两者都能避免“事务回滚但缓存已删除”这一路径,这一路径的危害在于后续读请求会把回滚后的旧值回填,使缓存与数据库长期不一致。

@CacheEvict 的两种批量语义需要区分:allEntries = true 清除该 cacheName 下的全部键,适用于字典类小集合的整体刷新;不声明时按键精确删除。按模式批量删除不在注解表达能力之内,属于缓存侧的运维操作。

  • 高危:清空缓存(allEntries = true 的全量清除、按前缀批量删除、或在运行中执行缓存实例的 FLUSHDB)会使后续请求全部回源到数据库,瞬时压力按缓存命中率成比例放大;多实例部署下还会出现清空时刻不一致,形成部分请求读新值、部分读旧值的窗口。执行前需确认数据库侧的容量余量与限流降级策略就位,按键前缀或 cacheName 分批清理并限制速率,在业务低峰执行,清理期间观察数据库 QPS、连接池等待与缓存命中率。回滚方式:缓存内容可由数据库重建,但重建期间的容量压力无法回退,只能依赖限流与降级承接;若为误清,需按业务补偿流程重新预热热点数据。具体的批量删除风险与兜底方式见 Redis 缓存实践与常见问题 第 3.7 节。

3.2.3 穿透、击穿与雪崩

三类问题的成因与通用应对属于缓存理论,见 缓存基础与一致性 第 2.5 节至第 2.7 节;工程侧处置清单见 Redis 缓存实践与常见问题 第 2.8 节。与 Spring Cache 注解直接相关的落地要点:

问题 注解层的应对 注解表达不了的补充
穿透 返回空值时写入带短过期时间的空值标记(需开启空值缓存) 布隆过滤器与入口参数校验
击穿 sync = true 提供单实例内的互斥回源 跨实例互斥需要分布式锁或逻辑过期加异步刷新
雪崩 按 cacheName 设置不同的基础过期时间 同一个 cacheName 内的键需要加随机抖动,抖动在键或 TTL 计算中实现

一条共同前提:缓存失效不允许演化为数据库的瞬时压力,因此失效路径需要限流保护,数据库侧需要预留余量,缓存不可用时的降级方向需要提前确定(通常退化为回源,并由数据库侧的限流承接)。

3.2.4 多级缓存与本地缓存

多级缓存把读路径拆为进程内缓存、分布式缓存、数据库三层。本地缓存的收益是省去网络往返,风险集中在两处:容量必须显式设定上限并配置淘汰策略,无上限的本地缓存会随键数量增长占用堆内存并引发垃圾回收压力;多实例部署时实例间不共享,数据不一致的窗口等于本地过期时间。这两点及相关治理要求见 日志规范与常用类库 第 2.7 节中“本地缓存的容量与失效”。

失效传播方式(仅靠 TTL 兜底、消息广播、发布订阅、版本号校验)的对照与一致性取舍见 Redis 缓存实践与常见问题 第 3.6 节。本地缓存只适用于变更频率低、可容忍短暂不一致的数据,且本地过期时间必须作为上界写入设计说明。

3.2.5 缓存指标与命中率

指标 采集位置 判断价值
命中率 应用侧缓存统计或 Redis 的 keyspace_hits 与 keyspace_misses 命中率下降先于数据库压力上升出现
回源量 缓存未命中次数、回源方法的调用次数 与数据库 QPS 对照可确认缓存的实际削减效果
键数量与内存 Redis 的 INFO memory、按前缀统计键数量 无 TTL 键堆积与内存增长的趋势判断
失效次数与失败次数 缓存删除调用统计 失效链路异常的直接证据

Spring Boot 的 Actuator 指标端点提供了 JVM、线程池、HTTP 请求与连接池等运行时指标,可结合缓存统计一起采集,端点清单见 Spring Boot 主脉络 第九章。缓存命中率的判读方法与指标对照见 Redis 缓存实践与常见问题 第 3.7 节。

3.3 调度实践

3.3.1 单机任务的配置与隔离

任务类的组织约定:按业务域分包,任务方法与触发声明放在同一处便于核对;任务方法内部只做参数组装与调用服务层,业务逻辑不放任务类;任务名出现在日志与执行记录中,需可检索。

@Component
public class OrderScheduledTasks {

    // 固定延迟:上次执行结束后再等待,天然避免重叠
    @Scheduled(fixedDelayString = "${app.task.order-reconcile.delay:60000}")
    public void reconcileOrders() {
        String taskName = "order-reconcile";
        long start = System.currentTimeMillis();
        try {
            int affected = orderReconcileService.reconcile();
            log.info("task={} result=success affected={} costMs={}",
                    taskName, affected, System.currentTimeMillis() - start);
        } catch (Exception e) {
            // 异常必须在此捕获,否则只留下框架日志且无法统计
            log.error("task={} result=failure costMs={}", taskName,
                    System.currentTimeMillis() - start, e);
            taskMetrics.recordFailure(taskName);
        }
    }

    // cron:每天凌晨 2 点,Spring 的 cron 为六段格式
    @Scheduled(cron = "${app.task.daily-report.cron:0 0 2 * * ?}")
    public void dailyReport() {
        dailyReportService.generate();
    }
}

触发时间与间隔通过占位符从配置读取,使频率调整不需要改代码;同时避免把频率硬编码在注解中(注解属性必须是编译期常量或占位符,硬编码的表达式在评审时不易发现)。

需要留意的边界是:注解属性中的占位符在容器启动时解析,配置中心推送新值后,已创建的调度注册信息不会自动重建。配置中心动态刷新的作用范围与“仅重建标注了刷新作用域的 Bean”这一约束见 Spring Cloud 微服务治理 第 2.3.2 节。因此频率类配置的实际生效方式通常是重启或重建对应的调度器 Bean,发布前需确认生效路径,避免出现“配置已改但任务仍按旧频率执行”。

任务隔离有两种做法:为耗时任务配置独立的调度线程池(小型应用可共用一个按任务数与最长耗时估算的线程池);或把耗时逻辑交给业务线程池异步执行,调度线程只负责触发与记录。后者的代价是任务重叠不再被 fixedDelay 抑制,必须改为幂等的互斥执行。

3.3.2 重叠与超时处置

现象 判断方式 处置
任务连续执行、间隔被压缩 日志中任务开始时间密集且执行耗时接近间隔 改用 fixedDelay;或缩短单次处理的数据量
多个任务相互延迟 各任务的开始时间整体后移 扩大调度线程池,或拆分耗时任务
单次执行时间无界增长 日志中耗时逐次上升 为任务设置处理量上限(每次最多处理 N 条),避免单次处理随积压增长
任务长时间无日志 线程栈中查看调度线程状态 检查任务是否阻塞在外部调用或连接获取上,为外部调用设置超时

“每次最多处理 N 条,循环执行直到处理完”是比“一次处理全部”更稳妥的设计:单次执行时间有界,失败影响范围可控,进度可从处理量推断。

3.3.3 分布式调度选型与迁移

选型 触发唯一性机制 任务分片 执行记录 动态变更 适用规模
分布式锁选主 各实例抢占锁 不支持 分散在各实例日志中 需重启或配置刷新 任务数量少、失败容忍度高的场景
调度中心(XXL-JOB 类) 中心唯一触发,向实例派发 支持 集中记录,可查询与重试 支持运行期修改 任务数量多、需要统一运维
Quartz 集群 数据库行锁保证作业不重复触发 支持(通过作业组与触发器) 持久化在作业表 支持 已基于 Quartz 建设的系统
消息队列延时任务 延时消息到期后投递,消费端幂等 由分区天然分片 依赖消息中间件 需改投递逻辑 触发时间分散、无需固定日历的延迟任务
容器平台定时任务 平台按 cron 创建一次性任务实例 不支持 平台侧记录 需更新部署描述 容器化部署、任务与业务代码解耦程度高的场景

操作系统层的调度工具(cron、systemd timer)与上述方案的区别在于触发点位于进程之外,只能以命令方式调用应用,无法直接使用应用上下文与连接池,两者的层次划分与取舍见 定时任务与定时器 第 3.8 节。

从 @Scheduled 迁移到调度中心时,需要留意的几点:

  1. 过渡期双触发。注解未移除而调度中心已开始派发时,任务会被执行两次。迁移必须遵循“先关闭注解、确认无触发、再启用中心调度”的顺序,或让两个来源的执行互斥。
  2. 执行语义差异。调度中心通常提供超时中断、失败重试与阻塞策略配置,默认值与 @Scheduled 的行为不同(例如默认不重试、超时终止),需逐项确认。
  3. 参数与上下文。注解方式的参数来自配置,调度中心的参数由触发时下发,两者需要在任务方法签名上统一。
  4. 幂等要求提高。超时重试与多实例并存使重复执行的来源增多,幂等设计需要在迁移前完成。
  • 高危:调整调度频率(改密或改疏)会同步改变任务对数据库与下游系统的单位时间调用量。频率调密时,单次执行耗时尚未被观测的情况下会出现任务叠加,连接池占用与下游 QPS 按重叠层数放大;频率调疏时,数据处理的滞后时间变长,依赖该任务的下游数据会延迟可用。变更前需确认任务耗时的 P99、单次执行占用的连接数与下游调用量,并明确下游对数据滞后时间的容忍度;在业务低峰期发布并观察一轮完整周期。回滚方式:将频率改回原值并重启或触发配置刷新;已产生的数据滞后需评估是否需要人工补算。

3.4 异步与事件实践

3.4.1 线程池参数与拒绝策略

spring:
  task:
    execution:
      pool:
        # 核心与最大线程数按下游承载能力设置,不按 CPU 核数推导
        core-size: 8
        max-size: 32
        # 有界队列:队列容量决定何时开始创建额外线程与何时触发拒绝
        queue-capacity: 200
        keep-alive: 60s
        # 允许核心线程超时回收,流量波动大时可降低空闲占用
        allow-core-thread-timeout: true
      thread-name-prefix: async-
      shutdown:
        # 优雅停机:等待任务结束
        await-termination: true
        await-termination-period: 30s

拒绝策略的选择原则:需要调用方感知过载时用 AbortPolicy(默认),允许降级为同步执行时用 CallerRunsPolicy(形成背压,但会拖慢提交线程),仅对可丢任务用 DiscardPolicy 并配合丢弃计数告警。无论选择哪种,都必须通过线程名前缀定位到具体线程池。

  • 高危:调大线程池的核心线程数、最大线程数或队列容量会同时抬高异步任务对下游(数据库、缓存、外部接口)的并发压力与堆内存占用(队列中的任务对象、线程栈)。连接池未同步扩容时,异步任务会阻塞在获取连接上,形成“持有连接的事务线程等异步结果、异步线程等不到空闲连接”的相互等待。变更前需核算“事务并发数 + 异步任务并发数 ≤ 连接池上限”,确认下游接口的并发承载能力,并评估堆内存余量。回滚方式:参数改回原值并重启或触发配置刷新;若已产生积压任务,需先停止接收新任务,等待队列消费完成或按业务决定丢弃哪些任务后再调整。

3.4.2 上下文传递

异步线程不继承调用线程的 ThreadLocal,需要显式传递并在任务结束时清理:

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(8);
        executor.setMaxPoolSize(32);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("async-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        // 任务提交时复制上下文,任务结束时清理,避免线程复用导致上下文串用与内存泄漏
        executor.setTaskDecorator(runnable -> {
            String traceId = MDC.get("traceId");
            String tenantId = TenantContext.get();
            return () -> {
                try {
                    if (traceId != null) {
                        MDC.put("traceId", traceId);
                    }
                    TenantContext.set(tenantId);
                    runnable.run();
                } finally {
                    MDC.clear();
                    TenantContext.clear();
                }
            };
        });
        executor.initialize();
        return executor;
    }
}

三个必须落实的约束:上下文复制发生在任务提交时而非执行时(提交后调用线程的上下文变化不应影响该任务);清理放在 finally(线程池中的线程长期存活,未清理会导致下一个任务读到上一个任务的上下文,同时形成内存泄漏);需要传递的上下文要在设计时枚举清楚,隐式的 ThreadLocal 依赖在异步化过程中最容易遗漏。线程封闭与 ThreadLocal 的语义见 Java 并发编程 第 10.1 节,未清理时的内存泄漏判读见 JVM 内存与垃圾回收 第 3.5 节。

3.4.3 事务与异步的顺序

事务与异步的交互只有一个正确方向:先提交事务,再派发异步任务。

@Service
public class OrderService {

    @Transactional
    public void placeOrder(OrderCommand command) {
        Order order = orderRepository.save(Order.create(command));
        // 只是登记事件,事务提交后由监听器触发异步动作
        eventPublisher.publishEvent(new OrderPlacedEvent(order.getId(), command.userId()));
    }

    // 事务提交后执行;defaultPhase 即 AFTER_COMMIT
    @TransactionalEventListener
    @Async("asyncExecutor")
    public void onOrderPlaced(OrderPlacedEvent event) {
        notificationService.sendOrderConfirmation(event.orderId());
    }
}

反面的写法是在事务方法内直接调用 @Async 方法或在异步方法内读取外层未提交数据,前者会在事务回滚后仍执行副作用,后者读到的是旧值或空值。

异步任务丢失的四种来源需要逐项确认:

来源 表现 应对
队列满被拒绝且策略为 Discard 无异常、无日志,任务静默消失 改用可感知的拒绝策略,或对丢弃计数告警
进程退出 队列中未执行的任务随进程终止 优雅停机等待队列消费;关键任务不做纯内存排队
异步已派发但事务回滚 副作用已产生,业务数据不存在 改为事务提交后派发
异步方法抛异常且返回 void 异常只留在日志中,调用方无感知 统一异常捕获与指标记录;需要结果时返回 CompletableFuture

需要“一定不丢”的任务不应依赖应用内异步:进程内队列没有持久化与重投语义,应改用消息中间件或把任务落库后由调度扫描执行,消息侧的可靠性机制见 消息可靠性与幂等设计。

3.5 批处理实践

3.5.1 作业设计

@Configuration
public class SettleJobConfig {

    @Bean
    public Job settleJob(JobRepository jobRepository, Step settleStep) {
        return new JobBuilder("settleJob", jobRepository)
                .start(settleStep)
                .build();
    }

    @Bean
    public Step settleStep(JobRepository jobRepository,
                           PlatformTransactionManager transactionManager,
                           ItemReader<Order> settleReader,
                           ItemProcessor<Order, SettleRecord> settleProcessor,
                           ItemWriter<SettleRecord> settleWriter) {
        return new StepBuilder("settleStep", jobRepository)
                .<Order, SettleRecord>chunk(500, transactionManager)
                .reader(settleReader)
                .processor(settleProcessor)
                .writer(settleWriter)
                .faultTolerant()
                // 只对数据格式类异常跳过,且有明确上限
                .skip(IllegalArgumentException.class).skipLimit(100)
                // 数据库瞬时异常重试,退避由退避策略控制
                .retry(TransientDataAccessException.class).retryLimit(3)
                .listener(new SettleSkipListener())
                .build();
    }

    @Bean
    public ItemReader<Order> settleReader(DataSource dataSource, @Value("${job.settle.batchId}") String batchId) {
        JdbcCursorItemReader<Order> reader = new JdbcCursorItemReader<>();
        reader.setDataSource(dataSource);
        // 以批次标识限定数据范围,使重启时的读取有确定边界
        reader.setSql("select id, user_id, amount from t_order where batch_id = ? and status = 'PENDING' order by id");
        reader.setPreparedStatementSetter(ps -> ps.setString(1, batchId));
        reader.setRowMapper(new OrderRowMapper());
        return reader;
    }
}

设计要点有五条。以批次标识限定数据范围,使重启与重跑有确定边界;chunk size 与事务边界一致,按单条数据大小与数据库侧的锁持有时间取值;跳过与重试的异常类型分开声明并给出上限;跳过明细通过监听器落库,保留可追溯的失败数据;作业参数包含批次标识,避免同一批数据被重复处理。

3.5.2 幂等与重启

环节 幂等风险 应对
读取 重启后重复读取已处理的记录 以状态或批次标记筛选,读取时即限定未处理集
处理 处理逻辑含外部调用,重启后重复调用 外部调用带幂等键;或把外部调用移出批处理
写入 无唯一约束的插入在重启后产生重复数据 业务唯一约束兜底,或写入前按批次删除
状态更新 更新语句无状态条件,重启后覆盖已变更的数据 改为条件更新(WHERE status = 'PENDING'),以影响行数判断是否处理

重启前需要确认的两件事:上一次执行的 StepExecution 状态(是否处于失败还是未知状态——进程被强杀时元数据可能停留在“进行中”);是否存在部分已提交的批次数据。元数据状态未知时,重启前应先核对数据侧的实际处理进度。

3.5.3 大批量作业对数据库的影响

影响面 成因 观测指标
主从复制延迟 大事务在 binlog 中以整笔分发,从库回放耗时长 从库延迟时间、binlog 事务大小
锁等待 单批次写入行数多、事务持有时间长 行锁等待时间、锁等待次数
undo 与 redo 增长 大批量写入的日志量与回滚段压力 磁盘使用、刷盘延迟
连接占用 批处理与在线流量共享连接池 连接池活跃数、获取连接等待时间
缓冲池污染 大批量扫描把在线数据挤出缓存 缓冲池命中率

复制延迟的成因分类与治理方式见 MySQL 主从部署与运维实践 第 2.2 节与第 3.3 节。缓解手段按优先级为:控制 chunk size 与批次规模,把大事务拆成多个小事务;批处理使用独立的数据源或连接池,与在线流量隔离;在业务低峰期执行;对非实时性数据改用增量处理缩小单次数据量。

3.6 常见问题与排查

现象 常见成因 定位手段 处置
缓存注解未生效、命中率恒为 0 @EnableCaching 未声明;自调用绕过代理;key 未指定导致键不符合预期;condition 判断为假;序列化方式与写入方不一致导致读不到 确认配置类上是否声明 @EnableCaching;核对调用链是否为同类内部调用;打印实际生成的键;直接查询缓存实例确认键是否存在 补上启用注解;改为外部调用或自注入代理;显式声明键;统一序列化配置
命中缓存但取到旧值 写路径未删除缓存;删除动作在事务提交前执行而事务回滚;缓存与数据库的更新顺序不满足旁路缓存约定 比对缓存值与数据库值;检查删除调用所处的事务阶段;核对写路径是否覆盖全部入口 将删除绑定到事务提交后;补齐遗漏的写入口;必要时改为变更日志驱动失效
定时任务在多实例上重复执行 未做选主;选主锁失效;调度中心与注解方式并存 对照各实例日志中的任务开始时间;查询分布式锁的状态 引入调度中心或统一选主;迁移期按 3.3 节的顺序切换
定时任务不再触发 任务方法抛出的异常导致该次执行中断(后续仍会触发);调度线程被阻塞;fixedDelay 下任务未结束 查看任务日志与异常栈;用线程栈快照确认调度线程状态;核对 @EnableScheduling 是否被条件装配关闭 在任务内捕获异常并记录;为外部调用设置超时;拆分耗时任务
异步任务丢失 队列满且拒绝策略为丢弃;进程退出时队列未消费完;事务回滚但异步已派发 统计提交量与被拒绝量;核对停机方式与队列长度;比对业务数据与副作用记录 改用可感知的拒绝策略并告警;开启优雅停机;改为事务提交后派发;关键任务改用消息中间件或落库
异步任务读到的上下文为空或串用 ThreadLocal 未传递;传递后未清理导致线程复用时串用 对比提交线程与执行线程的上下文值;检查 TaskDecorator 与清理逻辑 在任务提交时复制上下文、在 finally 中清理
事件监听器未被执行 事件在事务中发布而监听器为 AFTER_COMMIT,事务最终回滚;事件类型不匹配;监听器抛异常且为异步投递,异常被吞掉 确认事务的最终状态;核对事件类型与泛型;检查监听器日志与异步线程池的拒绝计数 确认事务提交路径;修正事件类型;为异步监听器统一异常捕获与指标
批处理作业卡死 Reader 的游标长时间占用;Writer 单条写入慢;等待行锁;作业仓库所在数据源连接被占满 查看 StepExecution 的读写计数是否停止增长;数据库侧查看活动会话与锁等待;应用侧查看连接池活跃数与线程栈 定位阻塞位置(读、写、锁或连接);调整 chunk size;为批处理配置独立数据源;必要时中止作业并按批次标识重启
批处理重启后数据重复 写入不幂等;重启从更早的 Step 开始;JobParameters 相同导致实例判断异常 按业务唯一键统计重复数据;核对执行记录中的重启起点与处理范围 补齐唯一约束或改为先删后写;修正重启起点;为重跑显式指定新的批次参数
作业执行历史表膨胀 未清理元数据表 统计元数据表行数与增长斜率 定期清理历史执行记录,清理前确认不再需要重启该次执行

排查顺序的共同原则是先判断“是否执行”(执行记录、日志、指标),再判断“执行结果是否正确”(数据比对),最后才深入框架的运行时状态(代理、上下文、线程池)。四种来源的 OutOfMemoryError 与线程池相关的资源问题可借助堆转储与线程栈定位,方法见 JVM 内存与垃圾回收 第三章;应用侧的线程阻塞、慢调用与内存压力的证据判读顺序见 Java 应用诊断与部署调优。

四、总结

Spring 生态组件处理的是核心容器之外的一类问题:与业务语义无关、形态高度统一、数量随业务规模增长的横切能力。它们遵循同一套收敛结构——以接口或注解声明意图,由框架提供执行引擎与集中配置,再把执行结果落到记录或指标上。Spring Data 把增删改查与分页排序收敛为仓库接口,Spring Cache 把读写缓存与失效收敛为注解,@Scheduled 与调度中心把定时触发收敛为统一入口,Spring Batch 把读、处理、写与断点、跳过、统计收敛为作业模型。

这些抽象的收益与代价来自同一个源头:能力被移入框架后,行为也从显式变为隐式。仓库的派生查询让语句在源码中不可见,缓存与异步注解依赖代理因而在自调用时静默失效,持久化上下文与作业仓库为排查引入了新的状态维度。因此选型的判定标准不是“抽象是否优雅”,而是它消除的重复劳动量是否大于它引入的排查成本;当重复量小或排查成本集中在核心链路时,显式代码更可控。

落到工程实践,可靠性由几条边界守住:缓存失效不允许演化为数据库的瞬时压力,且删除动作绑定在事务提交之后;定时任务在多实例下必须有唯一触发机制,任何可能重复的任务都要幂等;异步必须从事务提交之后派发,上下文要显式传递并清理,可能丢失的任务不放在内存队列里;批处理以批次标识限定数据范围,chunk size 同时是事务边界,重启的前提是读取可定位且写入幂等;大批量作业的执行窗口必须与数据库的复制延迟耐受度、在线流量低谷对齐。这些边界的共同点是把隐式的时序与资源占用变为可声明、可观测、可回滚的约束,而不是等故障发生后再从框架的运行时行为里回溯。