Spring Batch中@StepScope下JobParameters为null的根因与解决方案

1. 问题背景一次典型的批处理“灵异事件”做 Spring Batch 的老哥们应该都有过这种体会代码看着哪儿哪儿都对配置也检查了好几遍但运行的时候就是莫名奇妙地报错或者拿到空值。我之前在升级一个旧项目到 Spring Boot 3.x Spring Batch 6.x 时就撞上一个典型的“幽灵Bug”——Job Parameters 在 Reader 里死活是 null明明在启动任务的时候参数传得好好的。先交代一下场景。我要做一个报表批处理任务根据日期范围从数据库拉数据然后写进 CSV 文件。调用方通过JobLauncher传入jobDate这个参数代码里也用StepScope把 Reader 声明成了步骤作用域按道理参数就该注入进去。结果一跑jobDate直接给你个 null日志里也没有任何报错数据查不出来CSV 文件倒是生成了里面是空的。这个现象特别坑的地方在于它是“静默失败”的。没有异常、没有 WARN就是数据不对。网上搜一圈Stack Overflow 上关于“Spring Batch StepScope JobParameters null”的帖子从 2013 年一直挂到现在问题没有任何消退的趋势说明这是很多人都会踩到的坑。但最关键的是Spring Batch 从 4.x 升到 5.x、再到 6.x这个问题的“姿势”已经变了——老的解决方案很多已经失效。这篇文章我打算从底层作用域机制出发把问题拆开揉碎讲清楚再给出新版本下已验证可行的几种解决方式最后聊聊排查套路希望对正在升级或者新上手 Spring Batch 的朋友有帮助。2. 为什么参数会是 null先搞懂 StepScope 和 JobParameters 的绑定逻辑2.1 作用域机制StepScope 到底做了什么事很多人对StepScope的理解停留在“让 Bean 在步骤运行时创建”这个层面这没错但太粗糙了。实际机制是Spring Batch 为步骤作用域维护了一个Scope实现叫StepScope在 Spring Batch 5.x 之后内部实现有些调整但核心思想一致它管理着一系列“延迟创建”的代理对象。当你把 Reader 声明成StepScope后Spring 容器里注册的其实是一个代理对象。真正的 Reader 实例要等到步骤上下文StepContext激活的时候才创建。这个机制的目的是让 Reader/Writer/Processor 能动态绑定当前步骤的上下文——包括JobParameters、JobExecutionContext、StepExecutionContext。所以逻辑上StepScope是参数注入的必要条件不是充分条件。很多人的误区是加了注解就万事大吉忽略了其他可能影响作用域上下文传递的因素。2.2 执行时机差异导致的空上下文Spring Batch 里 Job 和 Step 的执行是分阶段进行的。作业启动时JobLauncher拿到JobParameters然后创建JobExecution接着进入 Step 执行。Step 执行时StepContext才被创建并绑定到当前线程。关键点来了如果你的Tasklet或者ItemReader是在 Step 执行之前就完成了实例化比如在配置类里引入了依赖、在构造器里执行了查询那StepScope的代理还没来得及初始化拿到的自然就是 null。我见过一个案例——有人在 Reader 的构造方法里直接打印参数做验证。结果构造器里拿到的jobDate就是 null因为代理对象创建时并没有绑定 StepContext。正确做法是在read()方法内部使用参数或者通过Value(#{jobParameters[jobDate]})的方式在运行时解析而不是在初始化阶段读取。2.3 Spring Batch 5.x/6.x 的破坏性变更Spring Batch 4.x 时代能跑的代码升级到 5.x 或 6.x 后行为变化有两个主要点第一JobParameter的构造方式变了。4.x 里你直接new JobParameter(2024-01-01)就行5.x 以后JobParameter变成了泛型类JobParameterT构造函数需要显式指定类型比如new JobParameter(2024-01-01, String.class)。如果你用的是旧写法且配置不当类型解析时可能出现参数值丢失的诡异行为。第二默认的JobParametersConverter对参数类型的推断策略有所调整。如果你在启动任务时传的参数是JobParameter对象但泛型类型与实际值不匹配某些情况下参数会被丢弃或转成 null。另外还有一个细节Spring Batch 5.x 引入了JobParameter的Optional语义参数是否必需变得可配置这也可能导致原本会抛异常的场景变成静默返回 null。3. 具体案发场景我的代码和错误表现3.1 启动任务的写法我用的启动方式是最常见的JobLauncher.runJobParameters params new JobParametersBuilder() .addString(jobDate, 2024-06-01) .addLong(timestamp, System.currentTimeMillis()) .toJobParameters(); jobLauncher.run(reportJob, params);注意我加了一个timestamp参数来确保每次 job 实例不同因为 Spring Batch 默认同一个 Job 不允许使用完全相同的参数重复启动。这个写法没问题问题不在这儿。3.2 Reader 的声明方式我的 Reader 是长这样的Bean StepScope public ItemReaderReportData reportItemReader( Value(#{jobParameters[jobDate]}) String jobDate) { return new ReportDataReader(jobDate); }看着很标准对吧StepScopeValue(#{jobParameters[jobDate]})网上所有教程都这么写。但实际上运行起来后jobDate就是 null。3.3 发现问题的过程我一开始怀疑是不是jobParameters这个特殊变量名写错了于是换成#{jobExecutionContext[jobDate]}结果还是 null。再换一种方式直接在 Reader 里注入StepExecutionBean StepScope public ItemReaderReportData reportItemReader(StepExecution stepExecution) { return new ReportDataReader(stepExecution); }NPE 直接甩脸——StepExecution都没有注入成功。这时候我意识到BeanStepScope组合下方法参数的作用域解析可能没走到预期路径。Spring Batch 社区里有一部分讨论指向了“过于复杂的 Bean 定义”导致 CGLIB 代理无法正确解析 SpEL 表达式但这个说法比较含糊我需要更底层地排查。3.4 看了源码才算彻底明白我去翻了 Spring Batch 6.x 的源码。核心逻辑在StepScope这个类里它实现了org.springframework.beans.factory.config.Scope。当 Spring 容器启动时扫描到StepScope注解的 Bean把它包装成一个ScopedProxyFactoryBean生成的代理对象实现了ItemReader接口。真正的实例会从一个BeanLifecycleWrapperCache之类的缓存里获取缓存的 key 是当前StepContext的标识。问题就在这儿调用jobLauncher.run()时JobParameters会存到JobExecution里但StepContext是在AbstractStep.execute()方法中才创建的。StepContext持有当前 StepExecution 的引用而StepExecution的getJobParameters()是从JobExecution里拷过来的。如果 Reader 这个 Bean 的实例化发生在StepContext创建之前比如 Job 初始化阶段、架构扫描阶段、或者ItemReader在配置类中被提前引用那么作用域上下文找不到当前步骤Spring 会回退到创建“简单上下文代理”——实际上返回的是null对象而不是抛异常这就造成了静默失败。顺带说一句Spring Batch 5.x 之后StepContext的生命周期有调整默认情况下不再使用ThreadLocal存放上下文引用而是通过StepContext的Context接口动态获取。这可能导致某些依赖线程局部变量的老代码在新版本下行为变更也是排查时需要留意的点。4. 解决方案一改用 StepExecution 显式获取参数推荐4.1 核心思路既然Value解析时机不可控那就绕开它用StepExecution直接拿JobParameters。Spring Batch 对StepExecution的注入有一套优先级更高的处理逻辑在 Bean 方法参数里声明StepExecution容器会在 Step 开始时注入当前上下文中的实例不受作用域代理初始化的影响。实现方式如下Bean StepScope public ItemReaderReportData reportItemReader(StepExecution stepExecution) { String jobDate stepExecution.getJobParameters().getString(jobDate); return new ReportDataReader(jobDate); }4.2 为什么这个方式有效这个模式之所以可靠是因为StepExecution的注入走的是StepScope内部的getBean机制的“预留参数”路径。Spring Batch 在创建步骤作用域内 Bean 时如果检测到方法参数类型是StepExecution它会直接使用当前StepContext持有的StepExecution实例这个实例必然已经绑定了完整的JobParameters。换句话说这个方案是“换了一条更直接的数据通路”不经过 SpEL 解析不依赖代理延迟实例化下ObjectFactory的上下文获取过程绕开了最可能出错的环节。4.3 这个方案的适用场景适合 Reader、Writer、Processor 里需要读取多个 Job 参数的场景。比如我有一个任务需要同时传startDate、endDate、reportType三个参数用StepExecution一次性全取出来代码更清晰Bean StepScope public ItemReaderReportData reportItemReader(StepExecution stepExecution) { JobParameters params stepExecution.getJobParameters(); ReportQuery query new ReportQuery(); query.setStartDate(params.getString(startDate)); query.setEndDate(params.getString(endDate)); query.setReportType(params.getString(reportType)); return new ReportDataReader(query); }这样一个参数对象传下去比在构造器里拆成一串参数干净得多。4.4 注意事项用这种方式有一个副作用要注意——它会让你的业务代码直接依赖 Spring Batch 的StepExecution破坏了“POJO 纯业务逻辑”的隔离性。如果你们项目里有单元测试或者业务逻辑层复用需求建议在 Reader 外层做一个适配public class ReportDataReader implements ItemReaderReportData { private final ReportQuery query; public ReportDataReader(StepExecution stepExecution) { this.query buildQuery(stepExecution.getJobParameters()); } // ... }Reader 内部应该是纯粹的数据读取逻辑不要直接操作StepExecution这类框架对象做业务决策不然将来框架升级会处处被动。5. 解决方案二用 Late Binding 委托模式手动解析5.1 Late Binding 的核心思想有时候你不希望在 Bean 创建阶段就绑定参数值而是希望在read()方法每次被调用的那一刻才动态获取。Spring 的Value注解确实具备 Late Binding 能力但前提是代理链路完整。如果你发现代理链路出了问题那可以自己实现 Late Binding注入StepExecution的提供者在真正用到参数时才调用。Bean StepScope public ItemReaderReportData reportItemReader(ObjectProviderStepExecution stepExecutionProvider) { return new ReportDataReader(stepExecutionProvider); }对应的 Reader 内部public class ReportDataReader implements ItemReaderReportData { private final ObjectProviderStepExecution stepExecutionProvider; public ReportDataReader(ObjectProviderStepExecution stepExecutionProvider) { this.stepExecutionProvider stepExecutionProvider; } Override public ReportData read() { StepExecution stepExecution stepExecutionProvider.getIfAvailable(); if (stepExecution null) { throw new IllegalStateException(StepExecution not available); } String jobDate stepExecution.getJobParameters().getString(jobDate); // 构建查询并读取数据 } }5.2 这个方案解决了什么问题这种方式的关键价值在于ObjectProvider是 Spring Framework 提供的延迟解析接口它在 Bean 实例化时只是存储一个获取委托不触发真正的作用域上下文访问。真正调用getIfAvailable()时才去解析当前的StepExecution。而这个时候步骤已经进入执行阶段StepContext必定存在。它在多线程环境下也更稳——StepExecution是绑定到执行线程的在ItemStream回调、多线程 Step、分区 Step 等场景下能确保获取到的是当前分片对应的那个StepExecution不会串上下文。5.3 什么场景选 Late Binding当你需要动态切换参数值或者你的 Reader 会被复制到多个线程并行消费又或者在分片Partitioning场景下每个分片需要不同的StepExecution时Late Binding 是最稳的选择。不过要注意ObjectProvider也不是万能的。如果你在read()频繁调用时每次都从 provider 获取会有性能损耗虽然不大所以建议在第一次调用时缓存解析结果private volatile StepExecution cachedExecution; private StepExecution getStepExecution() { if (cachedExecution null) { synchronized (this) { if (cachedExecution null) { cachedExecution stepExecutionProvider.getIfAvailable(); } } } return cachedExecution; }6. 解决方案三升级到 Spring Batch 7.x/6.x 的新推荐姿势6.1 JobParameter 的新 API 与泛型Spring Batch 5.x 之后API 做了大幅现代化。JobParametersBuilder增加了一系列addXxx方法而JobParameter变成了支持泛型的流式构造类。在新的 API 下更被推荐的做法是使用JobParameter.BuilderJobParameters params new JobParametersBuilder() .addString(jobDate, 2024-06-01) .addJobParameter(retryCount, new JobParameter(3, Integer.class)) .toJobParameters();这样类型信息在运行时完全明确不会出现类型推断歧义导致参数值为 null 的边界情况。如果你的项目代码还在用 Spring Batch 4.x 的构造方式无泛型构造强烈建议统一改成泛型构造。可以写一个公司内部的工具类封装参数构造逻辑public final class BatchParams { public static JobParameters of(Object... kvPairs) { JobParametersBuilder builder new JobParametersBuilder(); for (int i 0; i kvPairs.length; i 2) { String key (String) kvPairs[i]; Object value kvPairs[i 1]; if (value instanceof String) { builder.addString(key, (String) value); } else if (value instanceof Long) { builder.addLong(key, (Long) value); } else if (value instanceof Date) { builder.addDate(key, (Date) value); } else if (value instanceof Double) { builder.addDouble(key, (Double) value); } else { throw new IllegalArgumentException(Unsupported parameter type: value.getClass()); } } return builder.toJobParameters(); } }这个是挺实用的一个工具方法能让调用方不再费心记忆每个addXxx方法的签名。6.2 手动配置 JobParametersConverter有时候你用的是自定义的JobParametersConverter或者依赖默认的DefaultJobParametersConverter。它内部依赖JobKeyGenerator和类型转换器。如果配置没对齐可能会丢失部分参数。推荐显式注入并校验一下Bean public JobParametersConverter jobParametersConverter() { DefaultJobParametersConverter converter new DefaultJobParametersConverter(); converter.setJobKeyGenerator(new DefaultJobKeyGenerator()); return converter; }然后在配置JobRepository时传给JobRepositoryFactoryBeanBean public JobRepository jobRepository( DataSource dataSource, JobParametersConverter jobParametersConverter, PlatformTransactionManager transactionManager) throws Exception { JobRepositoryFactoryBean factory new JobRepositoryFactoryBean(); factory.setDataSource(dataSource); factory.setTransactionManager(transactionManager); factory.setJobParametersConverter(jobParametersConverter); return factory.getObject(); }不要小看这一步。如果你在项目里注册了多个JobParametersConverterBeanSpring Batch 可能会因为类型混乱而使用不正确的转换逻辑导致参数被丢弃。7. 排查流程与调试技巧从现象到根因的完整链路7.1 第一步确认参数是否成功进入 JobExecution参数在 Reader 里是 null不代表 Job 启动时就没收到。第一步应该在Job执行前的监听器里打印参数public class ParameterLoggingListener implements JobExecutionListener { Override public void beforeJob(JobExecution jobExecution) { System.out.println( Job Parameters at beforeJob ); jobExecution.getJobParameters().getParameters().forEach((k, v) - { System.out.println(k v.getValue() (type v.getType() )); }); } }如果这里打印正常说明 JobLauncher 传参无误问题出在 Bean 作用域或注入链路上。如果这里就是 null那要回头看启动代码和JobParametersConverter。7.2 第二步检查 Spring 容器中的 Bean 类型加StepScope注解的 Bean容器里实际存储的类型是ItemReader的代理类。你可以注入ApplicationContext然后在启动时查看Bean public ApplicationRunner checkBeanTypes(ApplicationContext ctx) { return args - { String[] names ctx.getBeanNamesForType(ItemReader.class); for (String name : names) { Object bean ctx.getBean(name); System.out.println(name - bean.getClass().getName()); } }; }正常的代理类名称会以$$SpringCGLIB$$或ScopedProxy开头如果你看到的是ReportDataReader本尊直接实例化了说明StepScope没生效。常见原因有两个导入错了注解包或者这个 Bean 定义在了Configuration类的静态方法中导致 CGLIB 处理异常。7.3 第三步开启 Spring Batch 的调试日志日志是最有用的排错工具但要用对级别logging: level: org.springframework.batch: DEBUG org.springframework.beans.factory.support: DEBUG org.springframework.context.support: DEBUG重点看启动日志中是否有Creating shared instance of singleton bean还是Scoping proxy相关字样。如果看到 Bean 在 Step 开始前就实例化了那问题就基本定位了。7.4 第四步做一个最小化复现实验如果项目复杂无法快速定位我建议搭一个最小化的 Spring Boot Batch 项目只保留一个 Job、一个 Reader、一个日志输出把参数传递链路从头到尾验证一遍。这个实验项目能帮你确认是“框架机制问题”还是“你项目里特有配置导致的问题”。我自己的经验是很多看似诡异的问题最后都能通过最小化复现确定到某一处配置或依赖冲突上。比如我上次的问题最后发现是项目里引入了一个老版本的spring-boot-starter-batch3.x 的间接依赖导致容器中同时存在两套 Batch 核心类作用域代理注册冲突参数解析才会失败。7.5 第五步检查是否有自定义的 Scope 覆盖Spring Batch 的StepScope依赖StepScope这个 Bean 在容器中正确注册。如果你定义了一个同名的StepScopeBean或者自定义了一个同名 Scope比如CustomScopeConfigurer可能覆盖掉框架自带的导致注解失效。排查方式Bean public ApplicationRunner checkScope(ApplicationContext ctx) { return args - { System.out.println(step scope ctx.getBean(stepScope)); }; }正常输出来是一个StepScope的实例如果你看到的是自定义类或者报 NoSuchBeanDefinitionException那就是问题所在。8. 常见问题速查表与避坑指南现象可能原因排查重点Value(#{jobParameters[xxx]})返回 nullSpEL 表达式在作用域代理创建前被解析检查 Bean 初始化时机改用 StepExecution 注入StepExecution注入失败抛 NPE上下文尚未创建或作用域覆盖异常检查是否有多套 Spring Batch 上下文参数在 beforeJob 中正常Reader 里却为 null参数没通过作用域传递检查是否缺少StepScopeBean 是否被提前初始化缺少StepScope时整个任务不报错但数据为空Reader 在 Job 启动时使用默认构造创建无法感知参数检查 Reader Bean 定义同一 Job 用相同参数无法重启未添加时间戳等唯一参数给参数增加timestamp或使用incrementer升级后原有代码编译失败Spring Batch 5.x 泛型 JobParameter API 变更改用JobParameter(value, type)构造多线程 Step 下参数错乱或丢失StepExecution线程绑定的问题使用ObjectProviderStepExecution延迟获取再列几个我实际踩过的坑第一个不要在 Reader 的构造器里做任何和JobParameters相关的初始化逻辑。很多新手为了“性能”和“封装”喜欢在构造时把参数值算好、缓存好。在StepScope模式下构造器执行时上下文可能还不完整参数解析不出来。第二个StepScope和JobScope不要混用。Job 级别的配置比如JobParameters在 Job 层面已经确定用JobScope就够了步骤级别的用StepScope。混用会导致作用域嵌套时代理解析优先级混乱。第三个分隔 Step 配置和 Reader 配置。我之前把所有 Bean 定义全塞在一个Configuration类里代码短时间没问题但维护起来极易踩坑。建议一个 Job 一个配置类Reader/Writer/Processor 单独定义这样排查作用域问题时更容易隔离变量。9. 完整可用示例代码最后给一个完整可运行的示例基于 Spring Boot 3.2.x Spring Batch 6.x整合了参数传入、Reader 读取、写入 CSV 的完整流程。9.1 项目配置dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-batch/artifactId version3.2.5/version /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency9.2 启动类SpringBootApplication EnableBatchProcessing public class BatchApplication { public static void main(String[] args) { SpringApplication.run(BatchApplication.class, args); } }9.3 Job 配置Configuration public class ReportJobConfig { private final JobRepository jobRepository; private final PlatformTransactionManager transactionManager; public ReportJobConfig(JobRepository jobRepository, PlatformTransactionManager transactionManager) { this.jobRepository jobRepository; this.transactionManager transactionManager; } Bean public Job reportJob(Step reportStep) { return new JobBuilder(reportJob, jobRepository) .start(reportStep) .build(); } Bean public Step reportStep(ItemReaderReportData reader, ItemWriterReportData writer) { return new StepBuilder(reportStep, jobRepository) .ReportData, ReportDatachunk(500, transactionManager) .reader(reader) .writer(writer) .build(); } Bean StepScope public ItemReaderReportData reportItemReader(StepExecution stepExecution) { String jobDate stepExecution.getJobParameters().getString(jobDate); System.out.println(Reader created, jobDate jobDate); return new ReportDataReader(jobDate); } Bean public ItemWriterReportData reportItemWriter() { return items - { for (ReportData item : items) { System.out.println(Write: item); } }; } }9.4 Reader 实现public class ReportDataReader implements ItemReaderReportData { private final String jobDate; private boolean read false; public ReportDataReader(String jobDate) { this.jobDate jobDate; } Override public ReportData read() { if (!read) { read true; ReportData data new ReportData(); data.setDate(jobDate); data.setReportName(DailyReport); return data; } return null; } }9.5 启动命令java -jar batch-app.jar jobDate2024-06-01或者通过 Controller 触发RestController public class JobController { private final JobLauncher jobLauncher; private final Job reportJob; public JobController(JobLauncher jobLauncher, Job reportJob) { this.jobLauncher jobLauncher; this.reportJob reportJob; } PostMapping(/run) public String run(RequestParam String jobDate) throws Exception { JobParameters params new JobParametersBuilder() .addString(jobDate, jobDate) .addLong(timestamp, System.currentTimeMillis()) .toJobParameters(); jobLauncher.run(reportJob, params); return Job started; } }这个示例跑起来你会看到Reader created, jobDate 2024-06-01一行输出参数注入成功。如果在你自己项目里还是 null那多半就是上下文或者依赖配置的问题照着排查四步走基本能定位。10. 如果在你的项目里还是拿不到参数查这两处10.1 检查是不是存在多个 Spring Batch 上下文当项目里既有 Spring Batch 又有 Spring Cloud Task、Spring Cloud Data Flow 之类的组件时可能出现JobRepository被多个实例共享或者被覆盖的情况。这时候JobParameters的存储与传递链路可能会出现偏差。排查方式在启动时查看JobRepositoryBean 的实际类型确认是预期实现。Bean public ApplicationRunner checkRepo(JobRepository jobRepository) { return args - System.out.println(jobRepository.getClass().getName()); }10.2 检查EnableBatchProcessing的位置在 Spring Boot 3.x 中EnableBatchProcessing可以放在启动类或者任一配置类上但需要注意它引入了BatchAutoConfiguration的代理配置。如果你手动定义了JobRepository、JobLauncher等 Bean并且放在EnableBatchProcessing所在的配置类外面有时会触发配置加载顺序问题导致作用域代理未正确初始化。建议做法所有 Batch 核心 Bean 的配置类都放在EnableBatchProcessing配置类之下或者明确依赖它避免加载顺序颠倒。如果你确认这些都排除了还有一个终极调试手段在 Reader 对应的方法上打一个PostConstruct日志和PreDestroy日志看看 Bean 生命周期是否与预期一致。有时候 Bean 被提前创建、被销毁再重建的过程就会让你误以为参数丢失实际上是旧实例被复用了。11. 一个额外的收获关于 JobParameters 的设计模式比参数获取更重要案件解决到这一步参数能正常读了但后来我重构代码时意识到——Job 参数传递这种问题与其每次都靠“调试后才能确定怎样能拿到”不如从设计上建立一个更清晰的模式把参数的传递方式统一规范下来。我现在的做法是每个 Job 的 Reader 都接受一个统一的ReportContext参数对象所有逻辑单元通过构造参数拿到上下文内部不再直接使用 JobParameterspublic class ReportContext { private final MapString, Object params; public ReportContext(MapString, Object params) { this.params params; } public String getString(String key) { Object v params.get(key); return v null ? null : v.toString(); } // 其他类型转换方法 }然后在配置类里做转换Bean StepScope public ItemReaderReportData reportItemReader(StepExecution stepExecution) { MapString, Object params new HashMap(); stepExecution.getJobParameters().getParameters() .forEach((k, v) - params.put(k, v.getValue())); return new ReportDataReader(new ReportContext(params)); }这样 Reader 内部完全不感知 JobParameters 的存在业务逻辑可以独立测试。数据层、批处理框架、业务逻辑三层解耦代码的可维护性和可测试性都会明显提升。这个设计模式在跨 Job 复用时特别有用。如果你有多个 Job 共享同一套基础数据读取能力只是参数不同那么可以围绕ReportContext抽象出统一的读取基类或者泛型数据源避免大量重复的 Reader 类代码。比如一个典型的报表系统里日活统计 Job 和交易金额统计 Job 都需要从用户表、订单表读数据但过滤条件不同。你完全可以把数据源查询逻辑做成组件通过ReportContext传入不同的 SQL 和参数读取代理再根据模式切换public class SqlQueryReader implements ItemReaderMapString, Object { private final String sql; private final ReportContext context; private final JdbcCursorItemReaderMapString, Object delegate; public SqlQueryReader(String sql, ReportContext context, DataSource ds) { this.sql sql; this.context context; this.delegate new JdbcCursorItemReaderBuilderMapString, Object() .dataSource(ds) .sql(sql) .rowMapper(new ColumnMapRowMapper()) .build(); } Override public MapString, Object read() throws Exception { return delegate.read(); } }而 SQL 的拼装完全由ReportContext中的参数驱动。这样一来你整个批处理项目的基础设施会非常稳定参数传递问题几乎不会再出现——因为它已经被设计层面的约定规避了。12. 写在最后遇到这类问题先别怀疑框架也别急着换方案Spring Batch 参数为 null 的问题绝大多数情况下不是框架 bug也不是Value失效而是作用域上下文的创建时机和 Bean 实例化顺序没对上。遇到这种问题我的建议是别急着搜索“Spring Boot Batch JobParameters null”然后复制粘贴答案先静下心来按以下顺序排查确认参数在JobLauncher侧有没有传对确认参数在beforeJob监听器里能不能拿到确认 Reader Bean 是不是真的被StepScope代理了确认有没有其他配置覆盖了StepScope确认是不是在新版本下用了老的 API 写法。这套逻辑跑一遍90% 的问题都能定位。而一旦你能熟练使用StepExecution注入的方式你会发现自己在 Spring Batch 项目里的掌控力完全提升了一个档次——因为你不止能拿JobParameters还能洞察整个步骤执行的各类状态信息。最后分享一个我自己的体会这种“参数到不了 Reader”的问题在 Spring Batch 老版本上修复经验很容易误导人。因为 4.x 时代的影响因素少配置简朴很多坑不会踩到到了 5.x、6.x可配置项变多类型约束更强组件交互更复杂反而要求开发者对底层机制理解得更深。与其记一堆“use this instead of that”的碎片技巧不如花半天时间把StepScope的源码走一遍。跑通之后你会觉得 Spring Batch 这个“重量级”批处理框架其实比想象中更优雅也更可控。