Spring Batch入门实战：从CSV导入到数据库的完整批处理项目

做后端开发的，多少都碰过这类批量处理的脏活：凌晨对账，把几十万行 CSV 导入数据库，月底生成统计报表。一开始我也图省事，for 循环一把梭，直到内存溢出、任务中断、半夜爬起来重跑，才老老实实回头研究 Spring Batch。这篇内容就手把手带你把这个框架的第一个项目搭起来，跑通从读取、清洗到落库的完整链路。文章用的是 Java 17 + Spring Boot 3.2 + Spring Batch 5.1，适合刚接触批处理、想在项目里正式引入 Spring Batch 的开发者，跟着一路敲下来就能出活。

1. 先搞清楚——什么样的项目才真正需要 Spring Batch

1.1 批处理任务长什么样，怎么判断适不适合

写第一行代码之前，先别急着复制依赖。很多人把 Spring Batch 当成一个“优雅的循环”，其实它解决的问题远不止循环。我习惯用几个特征去判断一个需求是不是真的需要批处理框架：

• 数据量明显超出普通接口能承载的范围，十万起步，百万常见。
• 执行过程不需要用户实时等待结果，一般是定时任务或者离线跑批。
• 处理逻辑是线性的：读一批数据，算一算，写出去，再读下一批。
• 允许任务跑几分钟甚至几小时，但不允许跑到一半失败后，前面所有成果全部作废。

拿最常见的订单对账来举例。晚上十点系统要拉取外部渠道的对账单，跟本地订单逐笔比对，差异项写入异常表，最后生成一份汇总。整个过程要对几十万条记录，如果每比对一条就查一次数据库，几十万次查询足够让数据库直接喘不过气。更麻烦的是，中间一旦出现网络超时或者数据格式错误，异常一抛，前面几个小时的处理全部白做。这种需求就是典型的、应该在第一时间想到 Spring Batch 的场景。

1.2 为什么别用 for 循环把轮子造到一半

有朋友问过：我直接用 JDBC 加 PreparedStatement，开个事务循环插入，不行吗？行，数据量小的时候怎么都能跑。但规模一旦上来，你就会发现几个硬伤：

所有数据驻留在内存里，GC 压力巨大，处理到一半内存溢出的情况我见过太多次。第 5 万条数据出错，事务一回滚，前面 4 万多条全部作废，你想“保留成功的、跳过失败的”，对不起，没这个机制。任务执行过程没有任何系统化的日志记录，下次想排查跑到哪一步失败，只能靠肉眼翻日志。更别提并行处理、分页读取、跳过坏数据、失败重试这些需求，每加一个都是在重复造轮子。

Spring Batch 把这些“轮子”全部内置好了。它有专门的状态存储，知道任务跑到哪一步；它有 chunk 事务概念，一批一批提交，失败也只回滚当前这批；它支持跳过规则、重试机制、监听器、多线程执行。与其在自己的业务代码里重复实现一套批处理基础设施，不如把注意力放回业务流程本身。

1.3 框架最值钱的三件事

把 Spring Batch 的核心价值浓缩成三点，能帮你理解后面所有代码设计的动机。

第一，状态可追踪。框架利用数据库里的元数据表记录每个 job 和 step 的执行情况，哪个任务成功、哪个失败、失败原因是什么，查表就能分析，不需要你写一堆业务日志然后去日志文件里大海捞针。

第二，失败可续跑。执行中断时，框架记住了当前 batch 的完成位置，下次启动同一个 job 可以从断点继续。这个能力在几百万行数据的任务里，价值怎么强调都不过分。

第三，处理可插拔。读、处理、写三个环节完全解耦，每一块都可以替换实现。今天读 CSV，明天改读数据库，换一个 Reader 就行；今天写 MySQL，明天换 PostgreSQL，换一个 Writer 就行，业务逻辑基本不用动。

把这三点想透，再看后面的代码就不会迷路。

2. 开工前准备：环境、依赖和目录怎么一次配好

2.1 版本选型：Spring Boot 3.2 + Spring Batch 5.1

先交代环境。我现在用的组合是 Java 17 + Spring Boot 3.2 + Spring Batch 5.1。如果是新项目，建议直接照这套来，因为 Spring Batch 5 相对 4 有不容忽视的破坏性变化：javax.* 全部换成 jakarta.*，JobBuilderFactory、StepBuilderFactory 这些工厂类被废弃，改成直接 new JobBuilder、new StepBuilder，包路径也有调整。

网上大量老教程还在用 JobBuilderFactory，照着敲大概率编译不过。你看到的如果是jobBuilderFactory.get("xxx")这种写法，基本可以判断那是 Spring Batch 4 甚至更早的版本。

还有一个关于配置类的提醒：在老教程里经常看到@EnableBatchProcessing，在 Spring Boot 项目里这其实不是必需的，因为 spring-boot-starter-batch 的自动配置已经帮你装配好了 JobRepository、JobLauncher 这些核心组件。加了反而可能干扰自动配置，所以新项目尽量不加，保持配置简洁。

2.2 Maven 依赖清单

Spring Boot 3 的依赖管理已经内置了批量处理的 starter，不需要手动指定版本号。我建议至少引入这两个依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-batch</artifactId> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>

如果后面想通过 HTTP 接口手动触发 job，再补一个spring-boot-starter-web。数据库先用 H2 内存库，零配置，启动就能跑，最适合第一步练手。等你确认整个流程跑通，把 H2 换成 MySQL 或者 PostgreSQL 也很简单：加驱动、改连接串、初始化脚本多一步。

2.3 工程目录这样规划

目录结构我习惯按功能分包，不搞花哨。一个典型工程大致是这样：

src/main/java ├── com.example.demo │ ├── DemoApplication.java │ ├── batch │ │ ├── OrderJobConfig.java │ │ ├── OrderDataProcessor.java │ │ └── OrderFieldSetMapper.java │ ├── entity │ │ └── OrderData.java │ └── controller │ └── BatchController.java src/main/resources ├── data │ └── orders.csv └── application.properties

有人喜欢把所有配置塞在一个类里，几百行代码堆在一起，项目一多就分不清谁是谁。我建议至少把 Reader、Processor、Writer 在配置类里拆成独立的 @Bean 方法，别都堆在 main 方法里，后面维护会省心很多。

2.4 数据库元数据表：最容易漏掉的一步

这是初学者最容易踩坑的地方。Spring Batch 运行需要一批元数据表：BATCH_JOB_INSTANCE、BATCH_JOB_EXECUTION、BATCH_STEP_EXECUTION、BATCH_JOB_EXECUTION_CONTEXT、BATCH_STEP_EXECUTION_CONTEXT，名字都是 BATCH_ 开头。这些表记录任务实例、执行状态、上下文参数，是前面说的状态追踪和断点续跑的基础，千万别动它们的数据结构。

如果用 H2，Spring Boot 在启动时默认会按嵌入式数据源自动执行框架的 schema 脚本建表，你不用管。换成 MySQL 就得注意：框架依赖包里自带 schema-mysql.sql，在 org/springframework/batch/core 目录下能找到。开发环境设置spring.batch.jdbc.initialize-schema=always，应用启动时自动建表；生产环境建议设成 none，由 DBA 在发布流程中统一把表建好，避免应用账号权限过大。

为了接收订单数据，我还在src/main/resources下放了一个schema.sql，用来创建业务表 t_order。Spring Boot 默认会在内嵌数据库下执行这个文件，所以 H2 环境不需要额外配置：

CREATE TABLE IF NOT EXISTS t_order ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_id VARCHAR(32), user_name VARCHAR(64), amount DECIMAL(10, 2), status_desc VARCHAR(32) );

3. 拆解核心套路：读、处理、写 和 Chunk 模型

3.1 Job、Step、Chunk 到底是什么

Spring Batch 的模型其实不复杂。Job 是整个批处理作业，一个 Job 里可以有多个 Step，Step 是单个阶段；每个 Step 又由一个个 Chunk 组成，Chunk 就是“一小批”数据。用生活化的比喻：Job 是一张生产工单，Step 是工单里的一道道工序，Chunk 是每次推到工作台上的一小摞半成品。

默认情况下 Step 顺序执行，前一个成功，后面的才继续。整个任务被切成一个个“可管理的最小单元”，每个小单元独立提交，出问题时不需要放弃整个任务。

3.2 读、处理、写三件套各自管什么

在一个典型的 chunk 模型里，三个组件各管一段：

• ItemReader：负责拿出原始数据。文件、数据库查询、消息队列、API 响应都行，只要实现了 ItemReader 接口。它只负责读，不做业务处理。
• ItemProcessor：负责处理数据。清洗、转换、校验、过滤都放在这里，让“读”和“写”之间有一层干净的业务逻辑带。
• ItemWriter：负责写数据。批量落库、写文件、发消息都可以。注意 Writer 接收的不是单条数据，而是整个 chunk 的 List。

三个组件通过 Spring 的 Bean 组装在一起，互不认识，替换实现非常方便。这就是前面说的“可插拔”。

3.3 chunk size 与事务边界的权衡

chunk 就是事务边界。chunk(100)意味着每处理完 100 条，提交一次事务。第 101 条失败时，前 100 条已经提交了，框架只需要回滚当前这批未提交的数据，而不是整个任务。这个机制是 Spring Batch 在高数据量下保持稳定的关键。

那 chunk 设多少合适？没有绝对标准。我的经验是：本地教学项目 10 到 500 都行，生产环境大表写入在 500 到 1000 之间观察数据库压力再调整。设太大，单批事务时间变长，数据库行锁冲突概率上升，失败回滚代价也高；设太小，每批提交频繁，写入效率下降，还会产生大量小事务。你完全可以把它当成一个压测参数来看。

提示：chunk size 不是一个拍脑袋的配置，它会直接影响数据库锁竞争、事务回滚粒度和内存占用。项目里没有绝对正确的值，只有当前环境下最合适的值。

4. 手写第一个任务：CSV 订单数据导入数据库

4.1 场景与数据样例

进入正题。先定义场景：有一份外部系统导出的订单 CSV 文件，需要导入到 t_order 表。原始文件可能有脏数据，比如金额异常、状态用数字编码、用户名带多余空格，我们要在导入过程中做清洗。

orders.csv 放在src/main/resources/data下，内容如下：

orderId,userName,amount,status 1001,用户A,99.90,2 1002,用户B,50.00,1 1003,用户C,-20.00,3 1004,用户D,0,NULL 1005,用户E,300.50,2

注意 1003 金额是负数，1004 金额为 0 且状态是 NULL，这些就是 Processor 要处理的脏数据。

4.2 实体类先定义好

实体类字段与 CSV 列尽量一一对应，后面再补一个状态描述字段：

public class OrderData { private Long orderId; private String userName; private BigDecimal amount; private String status; private String statusDesc; // getter / setter 省略，实际代码里必须有 }

CSV 里的 status 列先按 String 读进来，因为原始值可能是 "1"、"2" 这样数字编码，也可能是 "NULL" 这样字符串，用 String 接收最稳妥。

4.3 Reader：读取 CSV 文件

读取 CSV 用 FlatFileItemReader，它内部通过 LineMapper 把一行文本切分成字段，再映射成对象。我建议用自定义 FieldSetMapper，而不是默认的 BeanWrapperFieldSetMapper，因为文件里的 "NULL" 字符串字段需要自己控制转换，自带 Mapper 处理起来不够灵活。

@Bean public FlatFileItemReader<OrderData> orderItemReader() { return new FlatFileItemReaderBuilder<OrderData>() .name("orderItemReader") .resource(new ClassPathResource("data/orders.csv")) .delimited() .names("orderId", "userName", "amount", "status") .linesToSkip(1) .fieldSetMapper(new OrderFieldSetMapper()) .build(); }

.linesToSkip(1)用来跳过 CSV 的第一行表头，这一步很容易漏。漏了的话，框架会把表头当成数据去解析，FieldSetMapper 转 orderId 时立刻报错。

OrderFieldSetMapper 实现 FieldSetMapper 接口：

public class OrderFieldSetMapper implements FieldSetMapper<OrderData> { @Override public OrderData mapFieldSet(FieldSet fs) { OrderData data = new OrderData(); data.setOrderId(fs.readLong("orderId")); data.setUserName(fs.readString("userName")); data.setAmount(fs.readBigDecimal("amount")); data.setStatus(fs.readString("status")); return data; } }

4.4 Processor：清洗、过滤、补全

处理逻辑集中在 ItemProcessor 里。我演示三个最常用的动作：过滤脏数据、清洗字符串、补全业务字段。

public class OrderDataProcessor implements ItemProcessor<OrderData, OrderData> { @Override public OrderData process(OrderData item) { // 1. 金额缺失或小于等于 0，直接过滤掉这条记录 if (item.getAmount() == null || item.getAmount().compareTo(BigDecimal.ZERO) <= 0) { return null; } // 2. 用户名去除首尾空格 item.setUserName(item.getUserName().trim()); // 3. 状态数字编码转中文描述 String statusDesc = switch (item.getStatus()) { case "1" -> "待支付"; case "2" -> "已支付"; case "3" -> "已退款"; default -> "未知状态"; }; item.setStatusDesc(statusDesc); return item; } }

第 4 行的 return null 是关键语义。它的意思不是“返回了一个空对象”，而是告诉框架“这一条我不想再往下游传，请忽略”。被过滤的记录既不会到 Writer，也不会影响 job 状态，这就是批量任务里最常见的脏数据剔除方式。

注意：ItemProcessor 返回 null 是过滤行为，不是异常。如果你想跳过少量坏数据但又不希望任务整体失败，应该优先考虑这种方式，而不是抛异常。

4.5 Writer：批量落库

写库是批处理链路里最容易出现性能瓶颈的一环。Spring Batch 提供了 JdbcBatchItemWriter，它内部会把一个 chunk 里所有 Item 累积起来，用 PreparedStatement.addBatch/executeBatch 一次性发给数据库，比一条一条 INSERT 性能强一个数量级。更重要的是它跟框架的事务边界是打通的：只有 executeBatch 成功返回，当前 chunk 的事务才提交；一旦失败，整批回滚。

@Bean public JdbcBatchItemWriter<OrderData> orderItemWriter(DataSource dataSource) { String sql = "INSERT INTO t_order(order_id, user_name, amount, status_desc) " + "VALUES (:orderId, :userName, :amount, :statusDesc)"; return new JdbcBatchItemWriterBuilder<OrderData>() .dataSource(dataSource) .sql(sql) .beanMapped() .build(); }

.beanMapped()表示按实体属性名来绑定命名参数，:orderId自动对应getOrderId()。这样写代码最直观，字段多了也不会像拼接字符串那样容易出错。

4.6 组装 Job 并跑通

最后把各组件装进 Step，再把 Step 装进 Job。注意这里用的是 Spring Batch 5 的新 API，不再依赖已经废弃的工厂类：

@Configuration public class OrderJobConfig { @Bean public Job orderJob(JobRepository jobRepository, Step importOrderStep) { return new JobBuilder("orderJob", jobRepository) .start(importOrderStep) .build(); } @Bean public Step importOrderStep(JobRepository jobRepository, PlatformTransactionManager transactionManager, ItemReader<OrderData> orderItemReader, ItemProcessor<OrderData, OrderData> orderItemProcessor, ItemWriter<OrderData> orderItemWriter) { return new StepBuilder("importOrderStep", jobRepository) .<OrderData, OrderData>chunk(10, transactionManager) .reader(orderItemReader) .processor(orderItemProcessor) .writer(orderItemWriter) .build(); } }

这段代码的核心就一句话：Step 以 10 条为一块，先读、再处理、最后写。JobRepository 和 PlatformTransactionManager 由 Spring Boot 自动配置，你直接注入即可。

在 application.properties 里加上：

spring.batch.job.enabled=true

默认情况下 Spring Boot 启动时会自动发现容器里的 Job，并交给 JobLauncherApplicationRunner 执行。直接运行 main 方法，看到控制台输出类似内容，就说明跑通了：

Starting Step: importOrderStep Step importOrderStep completed successfully Job: [SimpleJob: [name=orderJob]] completed with the following parameters: [{}]

如果你想验证数据，可以打开 H2 控制台查 t_order 表。Spring Boot 3 里在 application.properties 配spring.h2.console.enabled=true，访问/h2-console就能看到：用户A、用户B、用户E 三条正常入库；用户C 因为金额为负被过滤；用户D 因为金额为 0 被过滤。同时 status_desc 已经变成“已支付”“待支付”这些中文描述，而不是原始数字编码。

到这里，你的第一个 Spring Batch 项目已经完整跑通了。

5. 让任务“活”起来：参数、手动触发与自动运行冲突

5.1 JobParameters 里到底有什么讲究

上面的任务跑通之后，你会遇到一个新问题：job 没法重复跑。Spring Batch 判断一个任务实例的依据是 jobName 加上参数组合。同一个 job 用完全相同的参数，第二次启动会直接报错 “A job instance already exists”。要跑第二次，参数必须变化。这就是 JobParameters 存在的核心意义之一，它是区分 JobInstance 的钥匙。

实际业务里，参数还负责传递业务信息：要处理哪个文件、对账周期是哪几天、跑批时间是几点。读取组件可以通过 late-binding 动态使用这些参数，技术上讲非常灵活。

5.2 控制台传参和编程式传参怎么选

传递参数有两条路径。

一条是控制台传参。命令行启动 jar 时用--key=value，Spring Boot 会自动把这些属性转换成 JobParameters。比如：

java -jar demo.jar --fileName=/tmp/orders.csv --triggerTime=20250101120000

另一条是编程式传参。这在代码里更自由，你想在什么时机、用什么值构造参数，都由自己决定，然后调用 JobLauncher 的 run 方法。

5.3 HTTP 接口触发任务

如果你希望手动触发而不是每次重启应用，那么你得先关掉 Spring Boot 启动时自动执行 job 的行为。注意，spring.batch.job.enabled=true是默认行为，很多人配置完发现任务动不动就自动跑，还以为是自己代码问题，其实这是框架刻意为之的。如果希望任务时机完全由自己控制，就配成 false：

spring.batch.job.enabled=false

然后写一个最普通的 Controller：

@RestController @RequestMapping("/batch") public class BatchController { private final JobLauncher jobLauncher; private final Job orderJob; public BatchController(JobLauncher jobLauncher, Job orderJob) { this.jobLauncher = jobLauncher; this.orderJob = orderJob; } @PostMapping("/run") public String run(@RequestParam("fileName") String fileName) throws Exception { JobParameters params = new JobParametersBuilder() .addString("fileName", fileName) .addLong("triggerTime", System.currentTimeMillis()) .toJobParameters(); JobExecution execution = jobLauncher.run(orderJob, params); return "status: " + execution.getStatus(); } }

这里的 triggerTime 每次请求都不一样，就是为了保证连续两次请求同一个 fileName 时，job 参数不同，能够创建新的执行实例。

5.4 让 Reader 按参数动态读文件

既然参数里带了 fileName，读取器也应该按参数去读文件，而不是写死 classpath。调整一下 Reader，把它加上 @StepScope，然后用 @Value 引用 jobParameters 里的值：

@Bean @StepScope public FlatFileItemReader<OrderData> orderItemReader( @Value("#{jobParameters['fileName']}") String fileName) { return new FlatFileItemReaderBuilder<OrderData>() .name("orderItemReader") .resource(new FileSystemResource(fileName)) .delimited() .names("orderId", "userName", "amount", "status") .linesToSkip(1) .fieldSetMapper(new OrderFieldSetMapper()) .build(); }

@StepScope 是关键。它告诉容器这个 Bean 在 step 执行阶段才创建，这样才能拿到当前 job 的执行参数。如果去掉 @StepScope，bean 在启动阶段就创建了，@Value 引用 jobParameters 会解析失败，常见的报错是模板解析异常。

提示：@StepScope 是 late-binding 的核心。凡是需要引用 jobParameters 或 jobExecutionContext 的组件，都要记得加 @StepScope，这是一个非常容易忽略的细节。

6. 实战踩坑实录：六个高频问题一次说清

6.1 启动报找不到 Batch 元数据表

现象：应用启动时就报错，提示 BATCH_JOB_INSTANCE 之类的表不存在，或者干脆抛 SQLSyntaxErrorException。原因几乎都是：数据库不是 H2，且没有执行框架自带的 schema 脚本。

解决办法分两步。开发环境把spring.batch.jdbc.initialize-schema设为 always，启动时让框架自动建表；生产环境把框架提供的 schema-mysql.sql 或 schema-postgresql.sql 交给 DBA 手动执行，然后把配置改成 never。我的习惯是开发环境 always，生产环境 never，防止应用账号持有过大的 DDL 权限。

6.2 第二次运行报 job instance already exists

现象：同一个 job 执行成功后，再次启动报 JobInstanceAlreadyCompleteException 或者提示 “A job instance already exists”。

这不是 bug，是 Spring Batch 的规则在保护你：相同参数的 job 已经成功执行过，不允许再执行。要重跑有几种思路：

我推荐第一种，因为参数本身如果包含业务含义，以后排查起来信息量也大。

6.3 CSV 中文乱码

现象：落库的 userName 变成一堆乱码，或者日志里打印的字段已经是乱码。

原因基本是文件编码和读取器编码不一致。FlatFileItemReader 默认按 UTF-8 读取，如果 CSV 文件是 GBK 编码，就会乱。在 Reader builder 上补一行.encoding("GBK")即可。更规范的做法是：文件的编码是什么，配置就写什么，不要依赖系统默认，所有文件处理类最好都用显式编码。

6.4 chunk 太大，数据库锁等待超时

之前在处理线上任务的时候踩过一次实坑。导入五十万行数据，最开始 chunk 设了 5000，跑到一半数据库抛锁等待超时，整个 job 失败。原因是一次事务插 5000 条，行锁持有时间太长。后来把 chunk 调到 500，单次事务时间锐减，任务稳定跑完。

这个教训说明 chunk size 不是越大越快，它是在吞吐量和事务风险之间找平衡。如果发现锁竞争，优先调小 chunk，而不是盲目加数据库连接池。

6.5 过滤和失败要分清：Processor 返回 null 的语义

很多新手以为 processor 里抛异常就能过滤掉坏数据。不是不行，但语义完全不同。返回 null 是主动过滤，任务正常继续；抛异常会让当前 chunk 进入回滚，除非配置 skip 策略，否则 job 最终会失败。

在真实对账场景里，单条坏数据不应该让全盘重跑，这时用到 skip 更合适：

return new StepBuilder("importOrderStep", jobRepository) .<OrderData, OrderData>chunk(10, transactionManager) .reader(orderItemReader) .processor(orderItemProcessor) .writer(orderItemWriter) .faultTolerant() .skip(DataIntegrityViolationException.class) .skipLimit(100) .build();

这段代码的含义是：跳过由于数据完整性约束导致的单条失败，最多跳过 100 条，超过限制则 job 整体失败。这是批处理里非常实用的兜底策略。

6.6 CSV 表头、names、实体字段对不上

现象：数据能跑，但落库的字段全是 null。

原因基本是 CSV 表头、FlatFileItemReader 的 names 参数、实体字段名三者不一致。names 配置的是 FieldSet 的字段名，FieldSetMapper 按这些名字读取值，所以它既对应 CSV 表头，也对应你读出来的实体属性。为了省事，三处保持一致是最稳妥的办法。常见问题是 CSV 表头用下划线风格 order_id，实体属性用驼峰 orderId，结果映射路径对不上。

写在最后

我个人在实际操作中的体会是，Spring Batch 的上手门槛没有想象中那么高，真正难的是理解它设计上的那些“约束”。比如 job instance 不能拿相同参数重复跑、chunk 就是事务边界、ItemProcessor 返回 null 意味着过滤，这些规则乍看有点别扭，但都是为了确保批量任务在海量数据下可恢复、可追踪。等你在线上环境经历过一次凌晨任务失败、又靠着断点续跑功能轻松接上之后，就会明白框架帮你省下的事情远比表面看到的更多。

跑通这个项目之后，可以试着把 orders.csv 换成自己业务里的真实文件，把 Processor 里的规则改成实际校验逻辑，慢慢你会发现扩展点其实很清晰：想加个失败告警，就去实现 ExecutionListener；想定时触发，就配合 Spring 的调度注解；数据量再大，还可以研究多线程 Step 和分区 Step。基础搭稳了，后面都是水到渠成的事。