跳到主要内容
版本：6.0.2

FlatFileItemReader

DeepSeek V3 中英对照 FlatFileItemReader FlatFileItemReader

平面文件是指任何最多包含二维（表格）数据的文件。在 Spring Batch 框架中，读取平面文件的功能由名为 FlatFileItemReader 的类提供，该类为读取和解析平面文件提供了基本功能。FlatFileItemReader 两个最重要的必需依赖项是 Resource 和 LineMapper。LineMapper 接口将在后续章节中详细探讨。resource 属性代表 Spring Core 的 Resource。关于如何创建此类 bean 的说明文档可在 Spring Framework, Chapter 5. Resources 中找到。因此，本指南不深入探讨创建 Resource 对象的细节，仅展示以下简单示例：

Resource resource = new FileSystemResource("resources/trades.csv");

在复杂的批处理环境中，目录结构通常由企业应用集成（EAI）基础设施管理，其中会为外部接口建立投放区，用于将文件从FTP位置移动到批处理位置，反之亦然。文件移动工具不在 Spring Batch 架构的范围内，但在批处理作业流中包含文件移动工具作为步骤并不罕见。批处理架构只需要知道如何定位要处理的文件。Spring Batch 从这个起点开始将数据输入管道的过程。然而，Spring Integration 提供了许多此类服务。

FlatFileItemReader 中的其他属性可进一步指定数据的解析方式，如下表所示：

表 1. FlatFileItemReader 属性

属性类型描述
commentsString[]指定表示注释行的行前缀。
encodingString指定要使用的文本编码。默认值为 UTF-8。
lineMapperLineMapper将 String 转换为表示项目的 Object。
linesToSkipint忽略文件顶部的行数。
recordSeparatorPolicyRecordSeparatorPolicy用于确定行结束符的位置，并执行诸如在引号字符串内时跨行继续等操作。
resourceResource要读取的资源。
skippedLinesCallbackLineCallbackHandler传递要跳过的文件中原始行内容的接口。如果 linesToSkip 设置为 2，则此接口被调用两次。
strictboolean在严格模式下，如果输入资源不存在，读取器会在 ExecutionContext 上抛出异常。否则，它会记录问题并继续执行。

LineMapper​

与 RowMapper 类似，它接收像 ResultSet 这样的底层结构并返回一个 Object，平面文件处理也需要相同的结构来将 String 行转换为 Object，如下面的接口定义所示：

public interface LineMapper<T> {

    T mapLine(String line, int lineNumber) throws Exception;

}

基本契约是，给定当前行及其关联的行号，映射器应返回一个结果领域对象。这与 RowMapper 类似，因为每一行都与其行号相关联，就像 ResultSet 中的每一行都与其行号绑定一样。这使得行号可以与结果领域对象关联起来，用于身份比较或提供更丰富的日志信息。然而，与 RowMapper 不同的是，LineMapper 接收的是一个原始行，如上所述，这仅完成了一半的工作。该行必须被标记化为 FieldSet，然后才能映射到一个对象，如本文档后面所述。

LineTokenizer​

将一行输入转换为 FieldSet 的抽象是必要的，因为平面文件数据可能具有多种格式，需要转换为 FieldSet。在 Spring Batch 中，这个接口就是 LineTokenizer：

public interface LineTokenizer {

    FieldSet tokenize(String line);

}

LineTokenizer 的契约规定，给定一行输入（理论上 String 可能包含多行），它将返回一个代表该行的 FieldSet。然后，这个 FieldSet 可以传递给 FieldSetMapper。Spring Batch 包含以下 LineTokenizer 实现：

  • DelimitedLineTokenizer：用于记录中字段由分隔符分隔的文件。最常见的分隔符是逗号，但也常使用管道符或分号。

  • FixedLengthTokenizer：用于记录中每个字段均为"固定宽度"的文件。必须为每种记录类型定义每个字段的宽度。

  • PatternMatchingCompositeLineTokenizer：通过模式匹配检查，确定在特定行上应使用列表中的哪个 LineTokenizer。

FieldSetMapper​

FieldSetMapper 接口定义了单一方法 mapFieldSet，该方法接收一个 FieldSet 对象并将其内容映射到一个对象。该对象可以是自定义 DTO、领域对象或数组，具体取决于作业需求。FieldSetMapper 与 LineTokenizer 结合使用，将资源中的一行数据转换为所需类型的对象，如下方接口定义所示：

public interface FieldSetMapper<T> {

    T mapFieldSet(FieldSet fieldSet) throws BindException;

}

所使用的模式与 JdbcTemplate 使用的 RowMapper 相同。

DefaultLineMapper​

既然读取平面文件的基本接口已经定义完毕，现在可以明确需要三个基本步骤：

  1. 从文件中读取一行数据。

  2. 将 String 类型的行数据传入 LineTokenizer#tokenize() 方法，获取一个 FieldSet。

  3. 将分词后返回的 FieldSet 传递给 FieldSetMapper，最终返回 ItemReader#read() 方法的结果。

上述两个接口分别代表了两个独立的任务：将一行数据转换为 FieldSet，以及将 FieldSet 映射为领域对象。由于 LineTokenizer 的输入与 LineMapper 的输入（一行数据）相匹配，且 FieldSetMapper 的输出与 LineMapper 的输出相匹配，因此提供了一个默认实现，该实现同时使用了 LineTokenizer 和 FieldSetMapper。如下类定义所示的 DefaultLineMapper 代表了大多数用户所需的行为：

public class DefaultLineMapper<T> implements LineMapper<>, InitializingBean {

    private LineTokenizer tokenizer;

    private FieldSetMapper<T> fieldSetMapper;

    public T mapLine(String line, int lineNumber) throws Exception {
        return fieldSetMapper.mapFieldSet(tokenizer.tokenize(line));
    }

    public void setLineTokenizer(LineTokenizer tokenizer) {
        this.tokenizer = tokenizer;
    }

    public void setFieldSetMapper(FieldSetMapper<T> fieldSetMapper) {
        this.fieldSetMapper = fieldSetMapper;
    }
}

上述功能通过默认实现提供，而非直接内置于读取器本身（如框架先前版本的做法），以便用户在控制解析过程时获得更大灵活性，特别在需要访问原始行数据的情况下。

简单分隔文件读取示例​

以下示例展示了如何在实际领域场景中读取平面文件。这个特定的批处理作业从以下文件中读取足球运动员数据：

ID,lastName,firstName,position,birthYear,debutYear
"AbduKa00,Abdul-Jabbar,Karim,rb,1974,1996",
"AbduRa00,Abdullah,Rabih,rb,1975,1999",
"AberWa00,Abercrombie,Walter,rb,1959,1982",
"AbraDa00,Abramowicz,Danny,wr,1945,1967",
"AdamBo00,Adams,Bob,te,1946,1969",
"AdamCh00,Adams,Charlie,wr,1979,2003"

此文件的内容映射到以下 Player 域对象：

public class Player implements Serializable {

    private String ID;
    private String lastName;
    private String firstName;
    private String position;
    private int birthYear;
    private int debutYear;

    public String toString() {
        return "PLAYER:ID=" + ID + ",Last Name=" + lastName +
            ",First Name=" + firstName + ",Position=" + position +
            ",Birth Year=" + birthYear + ",DebutYear=" +
            debutYear;
    }

    // setters and getters...
}

要将 FieldSet 映射为 Player 对象，需要定义一个返回玩家的 FieldSetMapper，如下例所示：

protected static class PlayerFieldSetMapper implements FieldSetMapper<Player> {
    public Player mapFieldSet(FieldSet fieldSet) {
        Player player = new Player();

        player.setID(fieldSet.readString(0));
        player.setLastName(fieldSet.readString(1));
        player.setFirstName(fieldSet.readString(2));
        player.setPosition(fieldSet.readString(3));
        player.setBirthYear(fieldSet.readInt(4));
        player.setDebutYear(fieldSet.readInt(5));

        return player;
    }
}

然后，可以通过正确构造 FlatFileItemReader 并调用 read 方法来读取文件，如下例所示：

FlatFileItemReader<Player> itemReader = new FlatFileItemReader<>();
itemReader.setResource(new FileSystemResource("resources/players.csv"));
DefaultLineMapper<Player> lineMapper = new DefaultLineMapper<>();
//DelimitedLineTokenizer defaults to comma as its delimiter
lineMapper.setLineTokenizer(new DelimitedLineTokenizer());
lineMapper.setFieldSetMapper(new PlayerFieldSetMapper());
itemReader.setLineMapper(lineMapper);
itemReader.open(new ExecutionContext());
Player player = itemReader.read();

每次调用 read 都会从文件的每一行返回一个新的 Player 对象。当到达文件末尾时，返回 null。

按名称映射字段​

DelimitedLineTokenizer 和 FixedLengthTokenizer 都支持一项额外的功能，其作用类似于 JDBC 的 ResultSet。字段名称可以被注入到这两个 LineTokenizer 实现中，以增强映射函数的可读性。首先，将平面文件中所有字段的列名注入到分词器中，如下例所示：

tokenizer.setNames(new String[] {"ID", "lastName", "firstName", "position", "birthYear", "debutYear"});

FieldSetMapper 可以按如下方式使用此信息：

public class PlayerMapper implements FieldSetMapper<Player> {
    public Player mapFieldSet(FieldSet fs) {

       if (fs == null) {
           return null;
       }

       Player player = new Player();
       player.setID(fs.readString("ID"));
       player.setLastName(fs.readString("lastName"));
       player.setFirstName(fs.readString("firstName"));
       player.setPosition(fs.readString("position"));
       player.setDebutYear(fs.readInt("debutYear"));
       player.setBirthYear(fs.readInt("birthYear"));

       return player;
   }
}

将字段集自动映射到领域对象​

对许多人来说，编写特定的 FieldSetMapper 与为 JdbcTemplate 编写特定的 RowMapper 一样繁琐。Spring Batch 通过提供一个 FieldSetMapper 来简化这一过程，该映射器使用 JavaBean 规范，通过将字段名与对象上的 setter 方法匹配来自动映射字段。

再次以足球示例为例，BeanWrapperFieldSetMapper 在 Java 中的配置如下所示：

@Bean
public FieldSetMapper fieldSetMapper() {
	BeanWrapperFieldSetMapper fieldSetMapper = new BeanWrapperFieldSetMapper();

	fieldSetMapper.setPrototypeBeanName("player");

	return fieldSetMapper;
}

@Bean
@Scope("prototype")
public Player player() {
	return new Player();
}

对于FieldSet中的每个条目，映射器会以与Spring容器查找匹配属性名的setter方法相同的方式，在Player对象的新实例上寻找对应的setter方法（因此需要原型作用域）。FieldSet中每个可用的字段都会被映射，最终返回生成的Player对象，整个过程无需编写任何代码。

固定长度文件格式​

到目前为止，我们主要详细讨论了分隔符文件。然而，它们仅代表了文件读取场景的一半。许多使用平面文件的组织会采用固定长度格式。以下是一个固定长度文件的示例：

UK21341EAH4121131.11customer1
UK21341EAH4221232.11customer2
UK21341EAH4321333.11customer3
UK21341EAH4421434.11customer4
UK21341EAH4521535.11customer5

虽然这看起来像是一个大字段，但实际上它代表了4个不同的字段：

  1. ISIN：订单商品的唯一标识符 - 长度为12个字符。

  2. 数量：订单商品的数量 - 长度为3个字符。

  3. 价格：商品的价格 - 长度为5个字符。

  4. 客户：订购商品的客户ID - 长度为9个字符。

在配置 FixedLengthLineTokenizer 时，必须以范围的形式提供每个长度。

以下示例展示了如何在 Java 中为 FixedLengthLineTokenizer 定义范围：

@Bean
public FixedLengthTokenizer fixedLengthTokenizer() {
	FixedLengthTokenizer tokenizer = new FixedLengthTokenizer();

	tokenizer.setNames("ISIN", "Quantity", "Price", "Customer");
	tokenizer.setColumns(new Range(1, 12),
						new Range(13, 15),
						new Range(16, 20),
						new Range(21, 29));

	return tokenizer;
}

由于 FixedLengthLineTokenizer 使用了与上文讨论的相同的 LineTokenizer 接口，因此它返回的 FieldSet 与使用分隔符时相同。这使得处理其输出时可以采用相同的方法，例如使用 BeanWrapperFieldSetMapper。

单文件内的多种记录类型​

到目前为止，所有文件读取示例都为了简化而做了一个关键假设：文件中的所有记录都具有相同的格式。然而，实际情况并非总是如此。一个文件中可能包含具有不同格式的记录，这些记录需要以不同的方式进行标记化并映射到不同的对象，这种情况非常常见。以下文件摘录说明了这一点：

USER;Smith;Peter;;T;20014539;F
LINEA;1044391041ABC037.49G201XX1383.12H
LINEB;2134776319DEF422.99M005LI

在这个文件中，我们有三种类型的记录："USER"、"LINEA"和"LINEB"。一个 "USER" 行对应一个 User 对象。"LINEA" 和 "LINEB" 都对应 Line 对象，不过 "LINEA" 比 "LINEB" 包含更多信息。

ItemReader 会逐行读取数据，但我们必须指定不同的 LineTokenizer 和 FieldSetMapper 对象，以确保 ItemWriter 接收到正确的条目。PatternMatchingCompositeLineMapper 通过允许配置模式到 LineTokenizer 的映射以及模式到 FieldSetMapper 的映射，使这一过程变得简单。

@Bean
public PatternMatchingCompositeLineMapper orderFileLineMapper() {
	PatternMatchingCompositeLineMapper lineMapper =
		new PatternMatchingCompositeLineMapper();

	Map<String, LineTokenizer> tokenizers = new HashMap<>(3);
	tokenizers.put("USER*", userTokenizer());
	tokenizers.put("LINEA*", lineATokenizer());
	tokenizers.put("LINEB*", lineBTokenizer());

	lineMapper.setTokenizers(tokenizers);

	Map<String, FieldSetMapper> mappers = new HashMap<>(2);
	mappers.put("USER*", userFieldSetMapper());
	mappers.put("LINE*", lineFieldSetMapper());

	lineMapper.setFieldSetMappers(mappers);

	return lineMapper;
}

在这个例子中，"LINEA" 和 "LINEB" 拥有独立的 LineTokenizer 实例，但它们都使用同一个 FieldSetMapper。

PatternMatchingCompositeLineMapper 使用 PatternMatcher#match 方法来为每一行选择正确的委托映射器。PatternMatcher 允许使用两个具有特殊含义的通配符：问号 ("?") 精确匹配一个字符，而星号 ("*") 匹配零个或多个字符。请注意，在上述配置中，所有模式都以星号结尾，这使得它们实际上成为行的前缀。PatternMatcher 总是匹配最具体的模式，与配置中的顺序无关。因此，如果 "LINE*" 和 "LINEA*" 都被列为模式，那么 "LINEA" 将匹配模式 "LINEA*"，而 "LINEB" 将匹配模式 "LINE*"。此外，单个星号 ("*") 可以作为默认模式，匹配任何未被其他模式匹配的行。

以下示例展示了如何在 Java 中匹配未被任何其他模式匹配的行：

...
tokenizers.put("*", defaultLineTokenizer());
...

此外，还有一个 PatternMatchingCompositeLineTokenizer 可以单独用于分词。

此外，平面文件中包含跨越多行的记录也很常见。为了处理这种情况，需要采用更复杂的策略。这种常见模式的演示可以在 multiLineRecords 示例中找到。

平面文件中的异常处理​

在许多场景下，对行进行分词时可能会引发异常。许多平面文件并不完美，包含格式错误的记录。许多用户选择在记录问题、原始行和行号的同时跳过这些错误行。这些日志稍后可以手动检查或由另一个批处理作业检查。因此，Spring Batch 提供了一组异常层次结构来处理解析异常：FlatFileParseException 和 FlatFileFormatException。当 FlatFileItemReader 在尝试读取文件时遇到任何错误时，会抛出 FlatFileParseException。而 LineTokenizer 接口的实现会抛出 FlatFileFormatException，表示在分词过程中遇到了更具体的错误。

IncorrectTokenCountException​

DelimitedLineTokenizer 和 FixedLengthLineTokenizer 都具备指定列名的能力，这些列名可用于创建 FieldSet。然而，如果在标记化一行时，列名的数量与找到的列数不匹配，则无法创建 FieldSet，并会抛出 IncorrectTokenCountException 异常。该异常包含实际遇到的标记数量和预期数量，如下例所示：

tokenizer.setNames(new String[] {"A", "B", "C", "D"});

try {
    tokenizer.tokenize("a,b,c");
}
catch (IncorrectTokenCountException e) {
    assertEquals(4, e.getExpectedCount());
    assertEquals(3, e.getActualCount());
}

由于分词器配置了4个列名，但在文件中仅找到3个标记，因此抛出了 IncorrectTokenCountException 异常。

IncorrectLineLengthException​

固定长度格式的文件在解析时有额外要求，因为与分隔符格式不同，每个列必须严格遵循其预定义的宽度。如果总行长度不等于该列的最大宽度值，则会抛出异常，如下例所示：

tokenizer.setColumns(new Range[] { new Range(1, 5),
                                   new Range(6, 10),
                                   new Range(11, 15) });
try {
    tokenizer.tokenize("12345");
    fail("Expected IncorrectLineLengthException");
}
catch (IncorrectLineLengthException ex) {
    assertEquals(15, ex.getExpectedLength());
    assertEquals(5, ex.getActualLength());
}

上述分词器配置的范围是：1-5、6-10 和 11-15。因此，该行的总长度为 15。然而，在前面的示例中，传入的行长度为 5，导致抛出了 IncorrectLineLengthException。在此处抛出异常，而不是仅映射第一列，可以让行的处理更早失败，并且比在 FieldSetMapper 中尝试读取第 2 列时失败包含更多信息。但是，在某些情况下，行的长度并不总是固定的。因此，可以通过 'strict' 属性关闭行长度的验证，如下例所示：

tokenizer.setColumns(new Range[] { new Range(1, 5), new Range(6, 10) });
tokenizer.setStrict(false);
FieldSet tokens = tokenizer.tokenize("12345");
assertEquals("12345", tokens.readString(0));
assertEquals("", tokens.readString(1));

前面的例子与之前的例子几乎相同，只是调用了 tokenizer.setStrict(false)。这个设置告诉分词器在分词行时不强制执行行长度的限制。现在，一个 FieldSet 被正确创建并返回。然而，它只包含剩余值的空标记。