Jackson CSV 解析失败：字段名大小写不匹配导致数据错位的解决方案

jackson 的 csvmapper 默认按 java 字段名（而非 json 属性名）匹配 csv 表头，当 `@jsonpropertyorder` 中指定的名称与实际字段名大小写不一致时，会导致表头与值错位映射。

在使用 Jackson 的 CsvMapper 读取 CSV 文件时，一个常见却容易被忽视的问题是：CSV 表头与 Java 对象字段的映射并非基于 @JsonProperty 或 @JsonPropertyOrder 的字符串值，而是默认依赖于 Java 字段本身的名称（即 number、name、type），且严格区分大小写。

回顾你的原始代码：

@JsonPropertyOrder({ "NUMBER", "NAME", "TYPE" })public class Pet { public String number; public String name; public String type;}

虽然你用 @JsonPropertyOrder({“NUMBER”, “NAME”, “TYPE”}) 明确声明了顺序，但该注解仅控制序列化（Java → CSV/JSON）时的字段输出顺序，并不影响反序列化（CSV → Java）时的列绑定逻辑。而 CsvMapper 在反序列化时，默认采用 “字段名直连”（field-name matching） 策略——即尝试将 CSV 表头 “NUMBER” 直接匹配到名为 NUMBER 的字段（而非 number）。由于你的字段实际名为小写的 number，Jackson 找不到对应字段，于是退而采用按位置顺序（positional fallback） 绑定：第一列 “NUMBER” → 第一个字段 number，第二列 “NAME” → 第二个字段 name，依此类推。这就解释了为何 pet.name 输出的是 “1”、”2″、”3″ —— 因为 “NAME” 列的数据（”Jack” 等）实际被错误地赋给了 name 字段的前一列值（即 “NUMBER” 列），而 name 字段本身接收的是 “NAME” 列内容，但由于位置偏移，最终 System.out.println(pet.name) 打印出的是 NUMBER 列的值（”1″、”2″、”3″）——这正是你观察到的现象。

✅ 正确做法是：确保 @JsonPropertyOrder 中的名称与 Java 字段名完全一致（包括大小写），或更推荐的方式——显式使用 @JsonProperty 注解绑定 CSV 表头，以实现清晰、健壮的映射：

public class Pet { @JsonProperty("NUMBER") public String number; @JsonProperty("NAME") public String name; @JsonProperty("TYPE") public String type;}

此时无需 @JsonPropertyOrder（除非你有特定序列化顺序需求）。CsvMapper 会准确将 CSV 中 “NUMBER” 列的值注入 number 字段，”NAME” → name，”TYPE” → type。

? 补充说明与最佳实践：

不要依赖 @JsonPropertyOrder 控制反序列化映射：它仅影响输出顺序，对输入解析无作用；

启用严格模式可提前暴露问题：

CsvMapper csvMapper = new CsvMapper();csvMapper.enable(CsvParser.Feature.STRICT_CHECKING); // 遇到未映射列或字段时报错

推荐完整初始化示例（含类型安全与异常处理）：

public static List<Pet> readFile(Path csvFile) throws IOException { CsvMapper mapper = new CsvMapper(); // 启用表头识别（必须！） CsvSchema schema = CsvSchema.emptySchema().withHeader(); ObjectReader reader = mapper.readerFor(Pet.class).with(schema); try (MappingIterator<Pet> it = reader.readValues(csvFile.toFile())) { return it.readAll(); }}

注意：readerWithTypedSchemaFor() 已过时，应改用 readerFor(…).with(schema) 方式构建 ObjectReader，并显式传入带表头的 CsvSchema。

总结：Jackson CSV 模块的字段绑定本质是“名称驱动”，而非“注解字符串驱动”。务必让 @JsonProperty(“XXX”) 中的 “XXX” 与 CSV 表头逐字符一致（包括大小写、空格、特殊符号），这是避免数据错位的根本保障。