在批处理任务中，XML是常见的数据交换格式，比如银行的对账文件、系统之间的数据同步报文等。Spring Batch针对XML文件的读写提供了专门的组件：读取使用StaxEventItemReader，写出使用StaxEventItemWriter。这两个组件底层基于StAX（Streaming API for XML）实现，采用流式解析方式处理XML，相比DOM一次性加载整个文档的方式，内存占用更小，非常适合处理大体积文件。本文将从原理、配置和完整示例三个层面，详细讲解如何在Windows环境下用Spring Batch完成XML文件的读写。
一、StaxEventItemReader的工作原理
要理解StaxEventItemReader的行为，首先要明白它采用的分片（Fragment）机制。它并不会把整个XML文档解析成一棵完整的DOM树，而是把XML按照指定的根节点名称切分成一个个片段，每解析到一个匹配的片段就交由反序列化器转换成一个Java对象，这个对象就是ItemReader返回的一条记录。
比如有下面这样的订单XML文件，存放在C:\batch\data\orders.xml：
<orders>
<order>
<orderId>1001</orderId>
<customer>张三</customer>
<amount>258.50</amount>
</order>
<order>
<orderId>1002</orderId>
<customer>李四</customer>
<amount>99.00</amount>
</order>
</orders>如果把fragmentRootElementName设置为order，那么读取器会把每一个<order>节点当作独立片段处理，解析出两个Order对象返回。需要注意的是，fragmentRootElementName必须与XML中实际的节点名称完全一致，包括大小写，否则读取器会因为找不到匹配片段而提前结束读取，这是初学者最常踩的坑之一。
片段到对象的转换由Object-XML Mapper（OXMapper）完成，Spring Batch官方推荐使用Spring OXM模块中的Jaxb2Marshaller，也就是基于JAXB注解完成绑定。整个过程是串行的流式处理，读一条、处理一条、写一条，因此即使文件有几十万个片段，内存中同一时刻也只会保留少量对象。
二、读取配置详解
先准备实体类，用JAXB注解标记节点与属性的映射关系：
@XmlRootElement(name = "order")
@XmlAccessorType(XmlAccessType.FIELD)
public class Order {
@XmlElement(name = "orderId")
private Long orderId;
@XmlElement(name = "customer")
private String customer;
@XmlElement(name = "amount")
private BigDecimal amount;
// 省略getter和setter
}接着配置StaxEventItemReader。下面这段配置指定了输入文件路径C:\batch\data\orders.xml，片段根节点为order，并注册了JAXB反序列化器：
@Bean
public Jaxb2Marshaller orderMarshaller() {
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
marshaller.setClassesToBeBound(Order.class);
return marshaller;
}
@Bean
public StaxEventItemReader<Order> xmlItemReader() {
return new StaxEventItemReaderBuilder<Order>()
.name("xmlItemReader")
.resource(new FileSystemResource("C:\\batch\\data\\orders.xml"))
.addFragmentRootElements("order")
.unmarshaller(orderMarshaller())
.build();
}这里有几点值得注意。第一，resource除了FileSystemResource外，也可以用ClassPathResource从类路径加载，Spring Batch会自动处理常见的压缩流场景。第二，Jaxb2Marshaller绑定的实体类一定要与片段结构对应，如果片段根节点名称是order，那么实体上的@XmlRootElement也必须是order。第三，如果XML文件带有命名空间，需要在unmarshaller层面处理命名空间前缀，否则JAXB解析时会报unexpected element异常。
另外提醒一点，在Windows下写路径时反斜杠在Java字符串里要转义，例如写成C:\\batch\\data\\orders.xml，也可以直接使用file:C:/batch/data/orders.xml形式的资源字符串，效果等价。
三、写出配置与完整Job示例
写出端使用StaxEventItemWriter，它同样基于OXMapper把Java对象序列化成XML片段并写出。下面的示例把处理后的订单写到C:\batch\output\result.xml，根节点设为processedOrders：
@Bean
public StaxEventItemWriter<Order> xmlItemWriter() {
return new StaxEventItemWriterBuilder<Order>()
.name("xmlItemWriter")
.resource(new FileSystemResource("C:\\batch\\output\\result.xml"))
.rootTagName("processedOrders")
.marshaller(orderMarshaller())
.build();
}rootTagName指定的是输出文档最外层的根标签，每个Item会被序列化为它的子节点。写出目录必须提前存在，否则会在打开文件时抛出FileNotFoundException，建议在Job启动前用Files.createDirectories确保C:\batch\output目录已创建。
最后把读写组件组装成一个完整的Step和Job，中间加一个简单的处理器演示加工逻辑：
@Bean
public Job xmlProcessJob(JobRepository jobRepository,
Step xmlProcessStep) {
return new JobBuilder("xmlProcessJob", jobRepository)
.start(xmlProcessStep)
.build();
}
@Bean
public Step xmlProcessStep(JobRepository jobRepository,
PlatformTransactionManager transactionManager) {
return new StepBuilder("xmlProcessStep", jobRepository)
.<Order, Order>chunk(100, transactionManager)
.reader(xmlItemReader())
.processor(order -> {
// 简单演示：金额打九折
order.setAmount(order.getAmount().multiply(
new BigDecimal("0.9")));
return order;
})
.writer(xmlItemWriter())
.faultTolerant()
.retryLimit(3)
.retry(java.io.FileNotFoundException.class)
.build();
}chunk大小设为100表示每读满100条提交一次事务。对于XML写入，事务回滚时文件内容不会自动还原，因此在容错场景下建议先把结果写到临时文件，Job成功后再通过监听器重命名到目标路径，这样能避免半截残缺的XML文件被下游系统误读。
四、常见问题与调试技巧
实际开发中遇到最多的问题有三类。第一类是读取数为零，多半是fragmentRootElementName与XML节点名不一致，可以用文本编辑器打开XML仔细核对。第二类是JAXB报ClassCastException，原因是marshaller绑定的类与Reader的泛型不匹配，确保两者指向同一个实体类即可。第三类是写出文件末尾缺少闭合标签，通常是Step异常中断导致写出器没有正常关闭，在Step级别配置StepExecutionListener的afterStep回调中做清理或日志记录，能帮助快速定位。
调试大文件时，可以把日志级别调到DEBUG观察StAX游标的移动过程，也可以先用小样本文件验证映射关系，确认无误后再切换到生产文件。只要掌握了分片读取、OXMapper绑定和事务边界这三个核心点，Spring Batch处理XML文件就会变得非常顺畅。
Spring BatchStaxEventItemReaderXML文件读写修改时间：2026-09-03 19:52:57