Jackson定制化：使用Converter实现复杂对象结构的定制序列化

本文深入探讨了如何利用jackson库对来自第三方库的嵌入式对象进行定制化序列化，以满足特定的json结构需求。通过引入`converter`机制，我们将详细展示如何将一个复杂领域对象中的多个`localizedtexts`类型字段扁平化为一个统一的翻译列表，从而实现灵活且可维护的数据转换。文章将涵盖目标数据模型设计、`converter`实现细节以及如何在jackson中注册和应用这些转换器。

1. 背景与问题描述

在Java应用开发中，我们经常需要将领域模型对象序列化为JSON格式进行存储或传输。当领域对象包含来自第三方库的类型时，如果这些类型无法直接修改，并且其默认的JSON表示不符合我们的业务需求，那么就需要进行定制化序列化。

以一个Article领域类为例，它包含多个LocalizedTexts类型的字段，如designation、touchCaption、printText和productInformation。LocalizedTexts是一个继承自HashMap的类，其中Language是一个枚举类型。这些LocalizedTexts对象通常以嵌套的键值对形式（如"de": "...", "en": "..."）出现在JSON中。

原始领域类示例：

// Article.java (部分代码)
@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)
public class Article extends AbstractEntityBase {
    @NonNull
    UUID id;

    @JsonProperty("iNo")
    Integer iNo;

    boolean isValid;

    @NonNull
    LocalizedTexts designation; // 来自第三方库

    @NonNull
    ReferenceArticleGroup articleGroup;

    Integer numberOfDecimalsSalesPrice;

    LocalizedTexts touchCaption; // 来自第三方库

    LocalizedTexts printText;    // 来自第三方库

    LocalizedTexts productInformation; // 来自第三方库

    @Singular
    List codes;
    // ... 其他字段和方法
}

// LocalizedTexts.java (来自第三方库)
@Builder(builderMethodName = "internalBuilder")
public class LocalizedTexts extends HashMap implements EntityBase {
    public LocalizedTexts() {}
    public LocalizedTexts(Map map) {
        putAll(map);
    }
}

// Language.java (来自第三方库)
public enum Language {
    AA("aa"), AB("ab"), AE("ae"), AF("af"), AK("ak"),
    DE("de"), EN("en"), ES("es"); // 示例中用到的语言

    private final String langName;
    Language(String langName) {
        this.langName = langName;
    }
    public String getLangName() { // 假设有此方法
        return langName;
    }
}

Jackson默认序列化输出示例：

{
    "id": "...",
    "iNo": 3,
    "isValid": true,
    "designation": {
        "de": "designation3DE ...",
        "en": "designation3EN ..."
    },
    "articleGroup": { /* ... */ },
    "touchCaption": {
        "de": "touchCaption3DE ...",
        "en": "touchCaption3EN ..."
    },
    "printText": { /* ... */ },
    "productInformation": {
        "de": "productInformation3DE ...",
        "en": "productInformation3EN ...",
        "es": "productInformation3ES ..."
    },
    "codes": [ /* ... */ ]
}

我们的目标是将其转换为以下扁平化的JSON结构，其中所有的LocalizedTexts内容都合并到一个名为translation的数组中：

期望的JSON序列化输出：

{
    "id": "...",
    "iNo": 3,
    "isValid": true,
    "articleGroup": { /* ... */ },
    "numberOfDecimalsSalesPrice": 2,
    "codes": [ /* ... */ ],
    "translation": [
        {
            "productInformation": "productInformation3DE ...",
            "language": "de"
        },
        {
            "productInformation": "productInformation3EN ...",
            "language": "en"
        },
        {
            "productInformation": "productInformation3ES ...",
            "language": "es"
        },
        {
            "touchCaption": "touchCaption3DE ...",
            "language": "de"
        },
        // ... 其他 LocalizedTexts 字段
    ]
}

2. Jackson定制化机制选择：Converter vs. JsonSerializer

Jackson提供了多种定制化序列化的方式。对于简单的类型转换，可以使用@JsonValue或@JsonFormat。对于更复杂的场景，通常会考虑JsonSerializer或Converter。

• JsonSerializer (通过StdSerializer实现):JsonSerializer允许我们直接控制如何将一个Java对象写入JsonGenerator。它提供了对JSON输出的细粒度控制，但当需要对整个对象图进行结构性转换时，实现起来会非常繁琐，需要编写大量的低级JSON生成代码，并且不易维护。

• Converter (通过StdConverter实现):Converter机制（通过com.fasterxml.jackson.databind.util.Converter接口实现）旨在将一个Java类型转换为另一个Jackson更容易序列化（或反序列化）的类型。它的核心思想是：先将原始对象转换为一个中间对象，然后Jackson再按照默认规则序列化这个中间对象。这种方式更适合进行对象结构的重塑或数据转换，因为它将“转换逻辑”与“序列化逻辑”分离，使得代码更清晰、更易于管理。

  

  AI发型设计

  虚拟发型试穿工具和发型模拟器

  下载

鉴于我们的需求涉及将多个字段的数据抽取并重组到一个新的列表中，Converter是更优的选择，因为它允许我们将Article对象转换为一个全新的ArticleWrapper对象，该对象直接反映了我们期望的JSON结构。

3. 设计目标JSON结构及辅助类

为了实现期望的JSON结构，我们需要定义一些辅助类来表示中间状态：

3.1 ArticleWrapper：目标JSON的顶层结构

ArticleWrapper将作为Article的转换目标类型。它包含Article中不需要特殊处理的字段，以及一个用于存放所有扁平化翻译内容的translation列表。

// ArticleWrapper.java
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import lombok.Singular;
import lombok.NonNull;

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 codes;

    // 所有 LocalizedTexts 字段的数据都将汇集到这个列表中
    private List translation; 
}

3.2 LanguageAttribute：翻译列表中的单个条目

translation列表中的每个元素都是一个包含特定属性名（如productInformation）及其值，以及对应语言的JSON对象。我们可以使用Java 16的record类型来简洁地定义它。

// LanguageAttribute.java
import com.fasterxml.jackson.annotation.JsonAnyGetter;
import com.fasterxml.jackson.annotation.JsonProperty;

import java.util.Map;

public record LanguageAttribute(
    @JsonAnyGetter // 将内部 Map 的键值对直接扁平化到当前对象
    Map map,
    @JsonProperty("language")
    Language language) {}

@JsonAnyGetter 注解说明：@JsonAnyGetter 注解用于将一个Map字段的键值对直接作为当前对象的属性输出到JSON中，而不是将Map本身作为一个嵌套对象。例如，如果map字段是Map.of("productInformation", "value")，则JSON输出将是"productInformation": "value"，而不是"map": {"productInformation": "value"}。 注意： 另一个常见的注解@JsonUnwrapped在这里不适用，因为它存在一个已知问题（Jackson issue #171），在某些情况下无法正确处理动态键。

3.3 LanguageConverter：Language枚举到字符串的转换

LanguageAttribute中的language字段是一个Language枚举。为了将其序列化为小写字符串（例如"de"而不是"DE"），我们可以为其定义一个简单的Converter。

// LanguageConverter.java
import com.fasterxml.jackson.databind.util.StdConverter;

public class LanguageConverter extends StdConverter {

    @Override
    public String convert(Language language) {
        // 假设 Language 枚举有一个方法可以获取其小写名称
        return language.getLangName(); 
    }
}

注册 LanguageConverter： 在LanguageAttribute的language字段上，通过@JsonSerialize(converter = LanguageConverter.class)注解来应用这个转换器。

4. 实现 ArticleConverter

现在，我们将实现核心的ArticleConverter，它负责将Article实例转换为ArticleWrapper实例。

// ArticleConverter.java
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 字段
        List translations = getTranslations(article);

        // 2. 构建 ArticleWrapper 对象，复制非 LocalizedTexts 字段
        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 字段并转换为 LanguageAttribute 列表。
     */
    private List getTranslations(Article article) {
        return Stream.of(
                toLanguageAttribute(article.getDesignation(), "designation"),
                toLanguageAttribute(article.getTouchCaption(), "touchCaption"),
                toLanguageAttribute(article.getPrintText(), "printText"),
                toLanguageAttribute(article.getProductInformation(), "productInformation")
            )
            .flatMap(Function.identity()) // 将 Stream> 扁平化为 Stream
            .toList();
    }

    /**
     * 将单个 LocalizedTexts 对象转换为 LanguageAttribute 的 Stream。
     * 每个 LocalizedTexts 内部的键值对（语言 -> 文本）都会变成一个 LanguageAttribute。
     */
    private Stream toLanguageAttribute(LocalizedTexts texts, String attributeName) {
        if (texts == null || texts.isEmpty()) {
            return Stream.empty();
        }
        return texts.entrySet().stream()
            .map(entry -> new LanguageAttribute(
                Map.of(attributeName, entry.getValue()), // 创建一个单键 Map 作为内容
                entry.getKey()) // 对应的语言
            );
    }
}

5. 注册并应用 ArticleConverter

最后一步是将ArticleConverter应用到Article类上。这通过在Article类定义上使用@JsonSerialize(converter = ArticleConverter.class)注解完成。

// Article.java (更新后的部分代码)
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(converter = ArticleConverter.class) // 应用 ArticleConverter
public class Article extends AbstractEntityBase {
    // ... 字段和方法保持不变
}

6. 完整示例与测试

为了演示上述转换过程，我们可以创建一个简单的测试类：

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import lombok.*;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.databind.util.StdConverter;

import java.util.*;
import java.util.function.Function;
import java.util.stream.Stream;

// 假设存在 AbstractEntityBase 和 ReferenceArticleGroup
class AbstractEntityBase {}
class ReferenceArticleGroup {
    public UUID id = UUID.randomUUID();
    public String type = "ArticleGroup";
    // toString, equals, hashCode for demo purposes
    @Override public String toString() { return "ReferenceArticleGroup(id=" + id + ", type=" + type + ")"; }
    @Override public boolean equals(Object o) { if (this == o) return true; if (o == null || getClass() != o.getClass()) return false; ReferenceArticleGroup that = (ReferenceArticleGroup) o; return Objects.equals(id, that.id) && Objects.equals(type, that.type); }
    @Override public int hashCode() { return Objects.hash(id, type); }
}

// Language.java (来自第三方库)
enum Language {
    AA("aa"), AB("ab"), AE("ae"), AF("af"), AK("ak"),
    DE("de"), EN("en"), ES("es"); // 示例中用到的语言

    private final String langName;
    Language(String langName) {
        this.langName = langName;
    }
    public String getLangName() {
        return langName;
    }
}

// LocalizedTexts.java (来自第三方库)
interface EntityBase {} // 假设 LocalizedTexts 实现了 EntityBase
@Builder(builderMethodName = "internalBuilder")
class LocalizedTexts extends HashMap implements EntityBase {
    public LocalizedTexts() {}
    public LocalizedTexts(Map map) {
        putAll(map);
    }
}

// Article.java (更新后)
@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(converter = ArticleConverter.class) // 应用 ArticleConverter
class Article extends AbstractEntityBase {
    @NonNull
    UUID id;

    @JsonProperty("iNo")
    Integer iNo;

    boolean isValid;

    @NonNull
    LocalizedTexts designation;

    @NonNull
    ReferenceArticleGroup articleGroup;

    Integer numberOfDecimalsSalesPrice;

    LocalizedTexts touchCaption;

    LocalizedTexts printText;

    LocalizedTexts productInformation;

    @Singular
    List codes;

    // 假设的 ArticleBuilderImpl，实际可能更复杂
    public static class ArticleBuilderImpl extends ArticleBuilder {
        @Override
        public Article build() {
            return new Article(id, iNo, isValid, designation, articleGroup, numberOfDecimalsSalesPrice, touchCaption, printText, productInformation, codes);
        }
    }
}

// ArticleWrapper.java
@Builder
@Getter
@Setter
class ArticleWrapper {
    @NonNull
    private UUID id;
    @JsonProperty("iNo")
    private Integer iNo;
    private boolean isValid;
    @NonNull
    private ReferenceArticleGroup articleGroup;
    private Integer numberOfDecimalsSalesPrice;
    @Singular
    private List codes;

    private List translation; 
}

// LanguageAttribute.java
record LanguageAttribute(
    @JsonAnyGetter
    Map map,
    @JsonProperty("language")
    @JsonSerialize(converter = LanguageConverter.class) // 应用 LanguageConverter
    Language language) {}

// LanguageConverter.java
class LanguageConverter extends StdConverter {
    @Override
    public String convert(Language language) {
        return language.getLangName(); 
    }
}

// ArticleConverter.java
class ArticleConverter extends StdConverter {
    public ArticleConverter() {}

    @Override
    public ArticleWrapper convert(Article article) {
        List translations = getTranslations(article);

        return ArticleWrapper.builder()
            .id(article.getId())
            .iNo(article.getINo())
            .isValid(article.isValid())
            .articleGroup(article.getArticleGroup())
            .numberOfDecimalsSalesPrice(article.getNumberOfDecimalsSalesPrice())
            .codes(article.getCodes())
            .translation(translations)
            .build();
    }

    private List getTranslations(Article article) {
        return Stream.of(
                toLanguageAttribute(article.getDesignation(), "designation"),
                toLanguageAttribute(article.getTouchCaption(), "touchCaption"),
                toLanguageAttribute(article.getPrintText(), "printText"),
                toLanguageAttribute(article.getProductInformation(), "productInformation")
            )
            .flatMap(Function.identity())
            .toList();
    }

    private Stream toLanguageAttribute(LocalizedTexts texts, String attributeName) {
        if (texts == null || texts.isEmpty()) {
            return Stream.empty();
        }
        return texts.entrySet().stream()
            .map(entry -> new LanguageAttribute(
                Map.of(attributeName, entry.getValue()), 
                entry.getKey())
            );
    }
}

public class JacksonCustomSerializationDemo {
    public static void main(String[] args) throws JsonProcessingException {
        // 构造 LocalizedTexts 实例
        LocalizedTexts designation = new LocalizedTexts(Map.of(
            Language.DE, "designation3DE localized designation3 designation",
            Language.EN, "designation3EN localized designation3 designation"
        ));
        LocalizedTexts touchCaption = new LocalizedTexts(Map.of(
            Language.DE, "touchCaption3DE localized touchCaption