本文详解如何使用 jackson 的 @jsonalias 和自定义序列化器/反序列化器，实现字段在反序列化时接受多个别名（如 "abrechnungsmonat"），而在序列化时统一输出标准名称（如 "abrechnungsmonat"），彻底规避“conflicting/ambiguous property name definitions”异常。
本文详解如何使用 jackson 的 @jsonalias 和自定义序列化器/反序列化器，实现字段在反序列化时接受多个别名（如 "abrechnungsmonat"），而在序列化时统一输出标准名称（如 "abrechnungsmonat"），彻底规避“conflicting/ambiguous property name definitions”异常。
在基于 Jackson 的 Java REST 服务中，常需兼容历史 JSON 接口的命名风格（如驼峰 abrechnungsMonat）与当前领域模型的规范命名（如全小写 abrechnungsmonat）。若错误地混合使用 @JsonSetter("abrechnungsMonat") 与 @JsonGetter("abrechnungsmonat")，Jackson 会因字段存在隐式属性名（即字段名 abrechnungsmonat）、显式 setter 名（abrechnungsMonat）和显式 getter 名（abrechnungsmonat）而判定命名冲突，抛出 IllegalStateException: Conflicting/ambiguous property name definitions —— 这正是问题的根本原因。
Lombok 的 @Data 会自动生成标准 getter/setter，而手动添加 @JsonGetter/@JsonSetter 会与 Lombok 生成的方法及字段隐式名产生三重映射，导致 Jackson 无法唯一确定该属性的序列化/反序列化标识符。
✅ 正确解法是：放弃 @JsonGetter/@JsonSetter，改用语义更清晰、职责更单一的注解组合：
- @JsonAlias("abrechnungsMonat")：声明反序列化时可接受的额外别名（不影响序列化）；
- @JsonSerialize(using = YearMonthSerializer.class)：显式指定序列化行为，确保输出为标准字段名 abrechnungsmonat；
- @JsonDeserialize(using = YearMonthDeserializer.class)：复用原有反序列化逻辑；
- @JsonFormat(pattern = "yyyy-MM")：保留日期格式控制。
以下是修复后的字段定义示例：
@JsonFormat(pattern = "yyyy-MM")
@JsonAlias("abrechnungsMonat") // ✅ 反序列化支持旧字段名
@JsonDeserialize(using = YearMonthDeserializer.class)
@JsonSerialize(using = YearMonthSerializer.class) // ✅ 序列化强制输出标准名
private YearMonth abrechnungsmonat;? 补充说明：@JsonAlias 是 Jackson 2.9+ 引入的关键特性，专为解决“一字段多输入名”场景设计；它不会参与序列化，仅作用于反序列化阶段，因此与 @JsonSerialize 完美解耦，避免命名歧义。
同时，请移除所有手动编写的 @JsonGetter / @JsonSetter 方法（包括 getAbrechnungsmonat() 等），让 Lombok 的 @Data 统一管理标准访问器。若需定制 getter 逻辑（如空值处理），应使用 @Getter + @Setter 细粒度控制，并配合 @JsonIgnore 避免 Jackson 重复发现。
? 总结最佳实践：
- ✅ 优先使用 @JsonAlias 处理反序列化别名；
- ✅ 使用 @JsonSerialize / @JsonDeserialize 控制序列化/反序列化行为；
- ❌ 避免混用 @JsonGetter + @JsonSetter + 字段名不一致的组合；
- ✅ 确保 Lombok 注解与 Jackson 注解职责分明，不重叠覆盖。
该方案简洁、健壮，且完全兼容 Lombok，已在 Spring Boot 2.7+ / Jackson 2.15+ 生产环境稳定运行。
