Jackson自定义序列化：处理外部库嵌套对象并扁平化为列表

本文详细探讨了如何利用jackson库实现对来自第三方库的嵌套对象进行自定义序列化。面对无法修改的localizedtexts类型，我们通过引入converter机制，将多个localizedtexts字段扁平化为一个统一的translation列表，每个元素包含动态键值对和语言信息。这种方法提供了灵活且可维护的解决方案，避免了低级serializer的复杂性。

引言：自定义JSON序列化的挑战

在现代Java应用开发中，将领域模型对象转换为JSON格式存储到文档数据库或通过API传输是常见操作。Jackson作为流行的JSON处理库，提供了强大的默认序列化能力。然而，当遇到以下场景时，默认行为可能无法满足需求：

处理第三方库对象： 领域模型中包含来自无法修改的第三方库的类型。复杂结构转换： 需要将对象中多个嵌套的特定类型字段扁平化或重构为另一种结构。

本文将以一个具体案例深入探讨如何解决这类问题。我们的目标是将一个包含多个LocalizedTexts类型字段的Article对象，序列化为JSON时，把这些LocalizedTexts的内容统一收集到一个名为translation的扁平化列表中。LocalizedTexts是一个扩展了HashMap的类，且Language和LocalizedTexts都来自外部库，无法直接修改。

原始Article类结构（部分）：

public class Article extends AbstractEntityBase {    // ... 其他字段    @NonNull    LocalizedTexts designation; // 需要转换    LocalizedTexts touchCaption; // 需要转换    LocalizedTexts printText; // 需要转换    LocalizedTexts productInformation; // 需要转换    // ... 其他字段}// 来自第三方库，无法修改public class LocalizedTexts extends HashMap implements EntityBase {    // ...}// 来自第三方库，无法修改public enum Language {    AA("aa"), AB("ab"), AE("ae"), AF("af"), AK("ak"),    // ...    DE("german"), EN("english"), ES("spanish"); // 假设有对应的语言名    private final String langName;    Language(String langName) { this.langName = langName; }    public String getLangName() { return langName; } // 假设有此方法}

期望的JSON输出格式：

{    "id": "...",    "iNo": 3,    "isValid": true,    "articleGroup": { /* ... */ },    "numberOfDecimalsSalesPrice": 2,    "codes": [ /* ... */ ],    "translation": [ // 扁平化后的列表        { "productInformation": "...", "language": "spanish" },        { "touchCaption": "...", "language": "english" },        { "designation": "...", "language": "german" }        // ... 所有 LocalizedTexts 字段的内容    ]}

Jackson Converter 的优势：复杂对象转换的首选

当需要对一个对象的整体结构进行显著改变，而不仅仅是修改某个字段的序列化方式时，Jackson的Converter机制是比StdSerializer更优的选择。

StdSerializer： 继承自StdSerializer并实现serialize()方法，允许你直接通过JsonGenerator写入JSON。这对于简单的数据类型转换、添加或移除少量字段非常有效。然而，当需要将一个复杂的对象图转换为完全不同的结构时，直接操作JsonGenerator会变得非常繁琐且难以维护。Converter： Converter（通过com.fasterxml.jackson.databind.util.Converter接口实现）的目的是将一种Java类型转换为另一种Java类型，然后Jackson再对转换后的类型进行序列化。这意味着你可以在序列化过程开始之前，将原始对象转换成一个更适合序列化或符合特定输出结构的新对象。这种“中间转换”的策略使得处理复杂结构转换变得更加清晰和可维护。

正如Jackson文档所述，Converter用于“将类型转换为Jackson知道如何序列化的东西；要么是因为基本类型不容易序列化，要么只是为了改变序列化方式。”

定义目标数据结构

为了实现所需的JSON结构，我们需要定义两个新的Java类：一个用于表示整个Article转换后的结构，另一个用于表示translation列表中的每个元素。

1. ArticleWrapper：序列化中间表示

ArticleWrapper将作为Article在序列化前的中间表示。它包含了Article中所有非LocalizedTexts字段，并用一个List来替代原有的所有LocalizedTexts字段。

import com.fasterxml.jackson.annotation.JsonProperty;import lombok.Builder;import lombok.Getter;import lombok.Setter;import lombok.NonNull;import lombok.Singular;import java.util.List;import java.util.UUID;@Builder@Getter@Setterpublic class ArticleWrapper {    @NonNull    private UUID id;    @JsonProperty("iNo")    private Integer iNo;    private boolean isValid;    @NonNull    private ReferenceArticleGroup articleGroup; // 假设 ArticleGroup 正常序列化    private Integer numberOfDecimalsSalesPrice;    @Singular    private List codes;    // 所有 LocalizedTexts 的内容将扁平化存储在这里    private List translation; }

2. LanguageAttribute：扁平化语言属性单元

LanguageAttribute用于表示translation列表中的每个对象，例如{“productInformation”: “…”, “language”: “english”}。它的关键在于如何处理动态的键（如productInformation、designation）。

import com.fasterxml.jackson.annotation.JsonAnyGetter;import com.fasterxml.jackson.annotation.JsonProperty;import com.fasterxml.jackson.databind.annotation.JsonSerialize;import java.util.Map;// Java 16+ 可以使用 record，如果使用旧版本Java，请将其实现为普通类public record LanguageAttribute(    // @JsonAnyGetter 将 Map 的内容直接作为顶层属性序列化，而不是作为嵌套的 "map" 属性    @JsonAnyGetter    Map map,     // 使用 LanguageConverter 将 Language 枚举序列化为字符串    @JsonProperty    @JsonSerialize(converter = LanguageConverter.class)     Language language) {}

关于 @JsonAnyGetter 的说明：

Anyword

AI文案写作助手和文本生成器，具有可预测结果的文案 AI

153 查看详情

@JsonAnyGetter 注解允许我们将一个 Map 的键值对直接作为当前对象的属性进行序列化，而不是将 Map 本身作为一个嵌套对象。例如，如果 map 包含 {“productInformation”: “value”}，那么序列化结果将是 {“productInformation”: “value”, …}，而不是 {“map”: {“productInformation”: “value”}, …}。

为什么不使用 @JsonUnwrapped？

@JsonUnwrapped 也可以将嵌套对象的属性提升到父级。然而，在当前场景下，@JsonUnwrapped 不适用于 Map 字段，并且存在一个Jackson的已知问题（GitHub issue #171），导致它无法正确处理这种动态键的扁平化需求。因此，@JsonAnyGetter 是更合适的选择。

实现自定义转换器

接下来，我们将实现核心的转换逻辑。

1. LanguageConverter：语言枚举到字符串的转换

这个简单的Converter负责将Language枚举转换为其对应的字符串名称（例如，DE转换为”german”）。

import com.fasterxml.jackson.databind.util.StdConverter;public class LanguageConverter extends StdConverter {    @Override    public String convert(Language language) {        // 假设 Language 枚举有一个 getLangName() 方法来获取小写语言名称        return language.getLangName();     }}

2. ArticleConverter：核心业务逻辑转换

ArticleConverter是实现Article到ArticleWrapper转换的关键。它将遍历Article中的所有LocalizedTexts字段，并将其内容提取、转换并收集到ArticleWrapper的translation列表中。

import com.fasterxml.jackson.core.JsonProcessingException;import com.fasterxml.jackson.databind.util.StdConverter;import java.util.List;import java.util.Map;import java.util.function.Function;import java.util.stream.Stream;public class ArticleConverter extends StdConverter
 {    // 构造函数可以为空，如果不需要特殊初始化    public ArticleConverter() {}    @Override    public ArticleWrapper convert(Article article) {        // 1. 提取所有 LocalizedTexts 字段并转换为 LanguageAttribute 列表        List translations = getTranslations(article);        // 2. 构建 ArticleWrapper 对象，填充非 LocalizedTexts 字段和 translations 列表        return ArticleWrapper.builder()            .id(article.getId())            .iNo(article.getINo())            .isValid(article.isValid())            .articleGroup(article.getArticleGroup())            .numberOfDecimalsSalesPrice(article.getNumberOfDecimalsSalesPrice())            .codes(article.getCodes()) // 假设 codes 字段也需要复制            .translation(translations) // 填充转换后的列表            .build();    }    /**     * 收集 Article 中所有 LocalizedTexts 字段的翻译内容。     */    private List getTranslations(Article article) {        // 使用 Stream.of 收集所有 LocalizedTexts 字段，并指定它们对应的 JSON 属性名        return Stream.of(                toLanguageAttribute(article.getDesignation(), "designation"),                toLanguageAttribute(article.getTouchCaption(), "touchCaption"),                toLanguageAttribute(article.getPrintText(), "printText"),                toLanguageAttribute(article.getProductInformation(), "productInformation")            )            // 将 Stream<Stream> 扁平化为 Stream            .flatMap(Function.identity())            .toList();    }    /**     * 将单个 LocalizedTexts 对象转换为 LanguageAttribute 对象的 Stream。     * 每个 LocalizedTexts 内部的 Map.Entry 对应一个 LanguageAttribute。     */    private Stream toLanguageAttribute(LocalizedTexts texts, String attribute) {        // 检查 LocalizedTexts 是否为空，避免空指针        if (texts == null || texts.isEmpty()) {            return Stream.empty();        }        return texts.entrySet().stream()            .map(entry -> new LanguageAttribute(                // 使用 Map.of 创建一个单例 Map，键为属性名，值为翻译文本                Map.of(attribute, entry.getValue()),                 entry.getKey()) // 语言枚举            );    }}

应用自定义转换器

最后一步是将ArticleConverter应用到Article类上，告知Jackson在序列化Article对象时使用这个转换器。

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;import com.fasterxml.jackson.databind.annotation.JsonSerialize;// ... 其他导入@Value@NoArgsConstructor(force = true, access = AccessLevel.PRIVATE)@AllArgsConstructor(access = AccessLevel.PRIVATE)@SuperBuilder(toBuilder = true)@JsonDeserialize(builder = Article.ArticleBuilderImpl.class) // 假设存在反序列化构建器@ToString(callSuper = true)@EqualsAndHashCode(callSuper = true)// 核心：通过 @JsonSerialize 注解应用 ArticleConverter@JsonSerialize(converter = ArticleConverter.class) public class Article extends AbstractEntityBase {    @NonNull    UUID id;    @JsonProperty("iNo")    Integer iNo;    boolean isValid;    @NonNull    LocalizedTexts designation; // 将通过 Converter 处理    @NonNull    ReferenceArticleGroup articleGroup;    Integer numberOfDecimalsSalesPrice;    LocalizedTexts touchCaption; // 将通过 Converter 处理    LocalizedTexts printText; // 将通过 Converter 处理    LocalizedTexts productInformation; // 将通过 Converter 处理    @Singular    List codes;    // ... 其他字段}

通过在Article类上添加@JsonSerialize(converter = ArticleConverter.class)注解，Jackson在尝试序列化Article实例时，会首先调用ArticleConverter将其转换为ArticleWrapper实例，然后对ArticleWrapper进行标准的JSON序列化，从而生成我们期望的扁平化结构。

注意事项与总结

反序列化： 本教程主要关注序列化过程。如果需要将上述JSON结构反序列化回原始的Article对象，则需要实现一个对应的ArticleDeConverter（继承自StdConverter）并将其应用于Article类上的@JsonDeserialize(converter = ArticleDeConverter.class)注解。反序列化逻辑将是序列化的逆过程，需要将translation列表中的数据重新填充到Article的各个LocalizedTexts字段中。性能考量： 使用Converter会在序列化前增加一个转换步骤，这会带来一定的性能开销。对于大规模数据或对性能极度敏感的场景，需要进行性能测试和评估。然而，对于大多数业务场景，这种开销通常是可接受的，并且其带来的代码可维护性收益远大于此。可维护性： Converter机制将复杂的对象结构转换逻辑封装在一个独立的类中，使得业务逻辑与Jackson的序列化机制分离，提高了代码的可读性和可维护性。当JSON输出结构或Article类结构发生变化时，只需修改ArticleConverter即可。Jackson版本兼容性： 示例代码基于Jackson 2.x系列。请确保您使用的Jackson版本支持文中所述的注解和API。错误处理： 在实际应用中，ArticleConverter中的getTranslations和toLanguageAttribute方法可能需要更健壮的空值检查和错误处理逻辑，以应对不完整或异常的数据。

通过利用Jackson的Converter机制，我们能够优雅地解决与第三方库对象相关的复杂序列化挑战，实现灵活且高度定制化的JSON输出格式，而无需修改原始的领域模型或第三方库代码。

以上就是Jackson自定义序列化：处理外部库嵌套对象并扁平化为列表的详细内容，更多请关注创想鸟其它相关文章！