Jackson处理嵌套对象与列表扁平化方法

哈喽！大家好，很高兴又见面了，我是golang学习网的一名作者，今天由我给大家带来一篇《Jackson处理嵌套对象并扁平化列表》，本文主要会讲到等等知识点，希望大家一起学习进步，也欢迎大家关注、点赞、收藏、转发! 下面就一起来看看吧！

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

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

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

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

本文将以一个具体案例深入探讨如何解决这类问题。我们的目标是将一个包含多个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<Language, String> 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
@Setter
public 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<String> codes;

    // 所有 LocalizedTexts 的内容将扁平化存储在这里
    private List<LanguageAttribute> 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<String, String> map, 

    // 使用 LanguageConverter 将 Language 枚举序列化为字符串
    @JsonProperty
    @JsonSerialize(converter = LanguageConverter.class) 
    Language language) {}

关于 @JsonAnyGetter 的说明：

@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<Language, String> {

    @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<Article, ArticleWrapper> {

    // 构造函数可以为空，如果不需要特殊初始化
    public ArticleConverter() {}

    @Override
    public ArticleWrapper convert(Article article) {
        // 1. 提取所有 LocalizedTexts 字段并转换为 LanguageAttribute 列表
        List<LanguageAttribute> 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<LanguageAttribute> 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<LanguageAttribute>> 扁平化为 Stream<LanguageAttribute>
            .flatMap(Function.identity())
            .toList();
    }

    /**
     * 将单个 LocalizedTexts 对象转换为 LanguageAttribute 对象的 Stream。
     * 每个 LocalizedTexts 内部的 Map.Entry 对应一个 LanguageAttribute。
     */
    private Stream<LanguageAttribute> 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<String> codes;
    // ... 其他字段
}

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

注意事项与总结

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

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

本篇关于《Jackson处理嵌套对象与列表扁平化方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！