Jackson高级序列化：使用Converter扁平化嵌入式第三方对象

本文将深入探讨如何使用jackson库对来自第三方库的嵌入式对象进行自定义序列化。针对将`localizedtexts`类型对象从其原始的键值对结构转换为一个扁平化的`translation`列表的需求，我们将详细介绍如何通过实现jackson `converter`机制，结合辅助数据结构和注解，实现复杂的json结构转换，从而在不修改第三方库代码的前提下，满足特定的序列化输出格式要求。

需求背景与挑战

在处理领域模型（如Article类）时，我们经常会遇到需要将对象持久化到文档数据库（如MongoDB）的需求，通常是通过将其转换为JSON格式。一个常见的场景是，领域模型中包含来自第三方库的嵌入式对象，例如本例中的LocalizedTexts。LocalizedTexts是一个HashMap<Language, String>类型，用于存储不同语言的文本。Language也是一个第三方库提供的枚举类型。

默认情况下，Jackson会将LocalizedTexts序列化为一个嵌套的JSON对象，例如：

"designation": {
    "de": "designation3DE ...",
    "en": "designation3EN ..."
}

然而，实际需求可能是将所有LocalizedTexts类型的字段扁平化，并统一收集到一个名为translation的JSON数组中，每个数组元素包含原始字段名、翻译文本和对应的语言，例如：

"translation": [
    {
        "designation": "designation3DE ...",
        "language": "german"
    },
    {
        "designation": "designation3EN ...",
        "language": "english"
    }
]

由于LocalizedTexts和Language类来自第三方库，我们无法直接修改其源码以添加Jackson注解。因此，我们需要一种非侵入式的自定义序列化方案。

Jackson自定义序列化策略：Converter vs. JsonSerializer

Jackson提供了多种自定义序列化机制，其中最常见的包括JsonSerializer和Converter。

• JsonSerializer: 适用于直接控制JSON生成过程的场景。通过继承StdSerializer并实现其serialize()方法，开发者可以利用JsonGenerator API精确地控制JSON输出的每一个细节。当需要对简单对象或特定字段进行细粒度控制时，JsonSerializer非常有效。然而，对于涉及复杂对象图转换和大量结构性变更的场景，编写JsonSerializer可能会导致低级别代码过多，且不易维护。
• Converter: 更适合于在序列化前将一个对象类型转换为另一个“更易于序列化”的类型。Converter的目的是将基础类型转换为Jackson能够更流畅地序列化的中间类型，或者仅仅是为了改变序列化行为。当原始对象结构复杂，或需要进行大幅度结构转换时，Converter提供了一种更优雅、更易维护的解决方案。它将转换逻辑与实际的JSON生成解耦，使得代码更清晰。

对于本例中将多个嵌入式对象扁平化为一个列表的需求，Converter是更合适的选择，因为它允许我们将Article对象转换为一个全新的中间表示（一个包装类），该表示直接对应目标JSON结构，从而简化了序列化过程。

核心概念：Jackson Converter

要实现自定义的Converter，我们需要继承抽象类com.fasterxml.jackson.databind.util.StdConverter<SOURCE, TARGET>，并实现其convert()方法。该方法接收一个SOURCE类型的实例，并返回一个TARGET类型的实例。

LobeHub

LobeChat brings you the best user experience of ChatGPT, OLLaMA, Gemini, Claude

201

查看详情

我们的策略是：

1. 定义一个ArticleWrapper类，其结构与我们期望的JSON输出完全一致。
2. 实现一个ArticleConverter，负责将原始的Article对象转换为ArticleWrapper对象。
3. 在Article类上使用@JsonSerialize(converter = ArticleConverter.class)注解，指示Jackson在序列化时使用我们的自定义转换器。

步骤一：定义目标数据结构 ArticleWrapper

为了将Article对象序列化为目标JSON格式，我们首先需要定义一个与目标JSON结构相匹配的Java类。我们将此称为ArticleWrapper。这个包装类将包含Article中的所有非LocalizedTexts字段，并引入一个新的translation字段来承载扁平化的翻译数据。

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Builder;
import lombok.Getter;
import lombok.NonNull;
import lombok.Setter;
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; // 假设 ReferenceArticleGroup 已定义
    private Integer numberOfDecimalsSalesPrice;
    @Singular
    private List<String> codes;

    // 所有的 LocalizedTexts 数据将被扁平化存储在此列表中
    private List<LanguageAttribute> translation;
}

步骤二：构建扁平化翻译条目 LanguageAttribute

ArticleWrapper中的translation列表的每个元素都需要表示一个特定的翻译条目，例如 {"productInformation": "...", "language": "english"}。为此，我们定义一个辅助类LanguageAttribute。为了简洁和不可变性，这里使用Java 16的record类型。如果项目不使用Java 16或更高版本，可以将其实现为一个普通的POJO类。

import com.fasterxml.jackson.annotation.JsonAnyGetter;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;

import java.util.Map;

// 假设 Language 是一个来自第三方库的枚举类型，例如：
// public enum Language { AA("aa"), AB("ab"), ...; public String getLangName() { ... } }
public record LanguageAttribute(
    @JsonAnyGetter // 将Map的内容直接扁平化到父对象中，而不是作为一个嵌套的"map"字段
    Map<String, String> map,
    @JsonProperty("language")
    @JsonSerialize(converter = LanguageConverter.class) // 对 Language 枚举进行自定义序列化
    Language language) {}

@JsonAnyGetter 注解说明：此注解用于将map字段的键值对直接作为当前对象的属性输出到JSON中，而不是将map本身作为一个嵌套对象。例如，如果map包含{"productInformation": "..."}，则JSON输出将直接是"productInformation": "..."，而不是"map": {"productInformation": "..."}。这正是我们实现扁平化结构的关键。

@JsonUnwrapped 的局限性：虽然@JsonUnwrapped也可以用于类似目的，但在某些复杂场景下（如与@JsonAnyGetter或其他复杂结构结合时），它存在已知的Jackson issue #171，可能无法按预期工作。因此，@JsonAnyGetter在这里是更稳健的选择。

步骤三：自定义语言枚举序列化 LanguageConverter

LanguageAttribute中的language字段是一个Language枚举类型。为了将其序列化为小写字符串形式（例如"german"而非"GERMAN"），我们需要一个简单的Converter。

import com.fasterxml.jackson.databind.util.StdConverter;

// 假设 Language 枚举有一个 getLangName() 方法返回其小写名称，例如：
// public enum Language {
//     DE("german"), EN("english"), ES("spanish");
//     private final

以上就是Jackson高级序列化：使用Converter扁平化嵌入式第三方对象的详细内容，更多请关注php中文网其它相关文章！