Spring Batch Excel Reader动态设置GCS文件路径时Workbook空指针问题

问题背景 #

在Spring Batch中读取从GCS下载后的Excel文件，文件路径已存入静态变量Constants.absolutePath且文件保存正常。但给PoiItemReader添加@StepScope注解后出现NullPointerException，调试发现workbook字段为空；若硬编码文件路径且不使用@StepScope则运行正常，需要解决批量处理中动态设置资源的问题。

依赖配置 #

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.batch.extensions</groupId>
    <artifactId>spring-batch-excel</artifactId>
    <version>0.1.1</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
</dependency>

出错的Reader代码 #

@Bean
@StepScope
public ItemReader<HashMap<String, String>> excelReader() {
    PoiItemReader poiItemReader = new PoiItemReader();
    poiItemReader.setResource(new FileSystemResource(Constants.absolutePath));
    poiItemReader.setLinesToSkip(1);
    poiItemReader.setRowMapper(excelRowMapper());
    return  poiItemReader;
}

错误栈信息 #

java.lang.NullPointerException: null
    at org.springframework.batch.extensions.excel.poi.PoiItemReader.getNumberOfSheets(PoiItemReader.java:56) ~[spring-batch-excel-0.1.1.jar:na]
    at org.springframework.batch.extensions.excel.AbstractExcelItemReader.nextSheet(AbstractExcelItemReader.java:178) ~[spring-batch-excel-0.1.1.jar:na]

解决方案 #

1. 手动触发初始化方法 #

PoiItemReader的afterPropertiesSet()方法负责加载workbook，在@StepScope下Spring可能不会自动调用该方法，导致workbook为空。手动调用即可解决：

@Bean
@StepScope
public ItemReader<HashMap<String, String>> excelReader() {
    PoiItemReader poiItemReader = new PoiItemReader();
    poiItemReader.setResource(new FileSystemResource(Constants.absolutePath));
    poiItemReader.setLinesToSkip(1);
    poiItemReader.setRowMapper(excelRowMapper());
    // 手动初始化workbook
    try {
        poiItemReader.afterPropertiesSet();
    } catch (Exception e) {
        throw new RuntimeException("初始化Excel读取器失败", e);
    }
    return poiItemReader;
}

2. 使用JobParameters传递动态路径（推荐） #

避免依赖静态变量，改用Spring Batch标准的参数传递方式，通过JobParameters传入文件路径，更符合批量处理的设计规范：

@Bean
@StepScope
public ItemReader<HashMap<String, String>> excelReader(@Value("#{jobParameters['excelFilePath']}") String filePath) {
    PoiItemReader poiItemReader = new PoiItemReader();
    poiItemReader.setResource(new FileSystemResource(filePath));
    poiItemReader.setLinesToSkip(1);
    poiItemReader.setRowMapper(excelRowMapper());
    try {
        poiItemReader.afterPropertiesSet();
    } catch (Exception e) {
        throw new RuntimeException("初始化Excel读取器失败", e);
    }
    return poiItemReader;
}

启动Job时传入参数：

JobParameters jobParameters = new JobParametersBuilder()
        .addString("excelFilePath", Constants.absolutePath)
        .toJobParameters();
jobLauncher.run(excelJob, jobParameters);

3. 升级Spring Batch Excel扩展版本 #

当前使用的spring-batch-excel:0.1.1版本较旧，可能存在@StepScope兼容性问题。升级到最新稳定版本：

<dependency>
    <groupId>org.springframework.batch.extensions</groupId>
    <artifactId>spring-batch-excel</artifactId>
    <version>1.0.2</version>
</dependency>

新版本对Spring的生命周期管理更完善，可能无需手动调用初始化方法即可正常加载workbook。

内容的提问来源于stack exchange，提问作者jithset