如何使用 Jackson 序列化和反序列化枚举

1. 概述

在本快速教程中，我们将学习如何控制 Java 枚举在使用 Jackson 2 时进行序列化和反序列化的方式。

要深入了解并学习 Jackson 2 的其他很酷的功能，请访问 主要的 Jackson 教程。

2. 控制枚举的表示形式

让我们定义以下枚举

public enum Distance {
    KILOMETER("km", 1000), 
    MILE("miles", 1609.34),
    METER("meters", 1), 
    INCH("inches", 0.0254),
    CENTIMETER("cm", 0.01), 
    MILLIMETER("mm", 0.001);

    private String unit;
    private final double meters;

    private Distance(String unit, double meters) {
        this.unit = unit;
        this.meters = meters;
    }

    // standard getters and setters
}

3. 将枚举序列化为 JSON

3.1. 默认枚举表示形式

默认情况下，Jackson 会将 Java 枚举表示为简单的字符串。例如

new ObjectMapper().writeValueAsString(Distance.MILE);

将会得到

"MILE"

但是，在将此 枚举编组到 JSON 对象时，我们希望得到类似以下的内容

{"unit":"miles","meters":1609.34}

3.2. 枚举作为 JSON 对象

从 Jackson 2.1.2 开始，现在有一个配置选项可以处理这种表示形式。这可以通过在类级别使用 @JsonFormat 注释来完成

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Distance { ... }

这将导致在序列化此 枚举的 Distance.MILE 时得到期望的结果

{"unit":"miles","meters":1609.34}

3.3. 枚举和 @JsonValue

控制枚举编组输出的另一种简单方法是在 getter 上使用 @JsonValue 注释

public enum Distance { 
    ...
 
    @JsonValue
    public String getMeters() {
        return meters;
    }
}

我们表达的是 getMeters() 是此枚举的实际表示形式。因此，序列化结果将是

1609.34

3.4. 枚举的自定义序列化器

如果我们使用的是 Jackson 2.1.2 之前的版本，或者需要对枚举进行更多自定义，我们可以使用一个 自定义 Jackson 序列化器。 首先，我们需要定义它

public class DistanceSerializer extends StdSerializer {
    
    public DistanceSerializer() {
        super(Distance.class);
    }

    public DistanceSerializer(Class t) {
        super(t);
    }

    public void serialize(
      Distance distance, JsonGenerator generator, SerializerProvider provider) 
      throws IOException, JsonProcessingException {
        generator.writeStartObject();
        generator.writeFieldName("name");
        generator.writeString(distance.name());
        generator.writeFieldName("unit");
        generator.writeString(distance.getUnit());
        generator.writeFieldName("meters");
        generator.writeNumber(distance.getMeters());
        generator.writeEndObject();
    }
}

然后我们可以将序列化器应用于将被序列化的类

@JsonSerialize(using = DistanceSerializer.class)
public enum TypeEnum { ... }

结果如下

{"name":"MILE","unit":"miles","meters":1609.34}

4. 将 JSON 反序列化为枚举

首先，让我们定义一个具有 Distance 成员的City 类

public class City {
    
    private Distance distance;
    ...    
}

然后我们将讨论将 JSON 字符串反序列化为枚举的不同方法。

4.1. 默认行为

默认情况下，Jackson 将使用枚举名称从 JSON 反序列化.

例如，它将反序列化 JSON

{"distance":"KILOMETER"}

为Distance.KILOMETER 对象

City city = new ObjectMapper().readValue(json, City.class);
assertEquals(Distance.KILOMETER, city.getDistance());

如果希望 Jackson 通过枚举名称以不区分大小写的方式从 JSON 反序列化，我们需要 自定义 ObjectMapper 以启用 ACCEPT_CASE_INSENSITIVE_ENUMS 功能。

假设我们有另一个 JSON

{"distance":"KiLoMeTeR"}

现在，让我们进行不区分大小写的反序列化

ObjectMapper objectMapper = JsonMapper.builder()
  .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS)
  .build();
City city = objectMapper.readValue(json, City.class);
                                                     
assertEquals(Distance.KILOMETER, city.getDistance());

如上述测试所示，我们使用 JsonMapper 构建器启用了 ACCEPT_CASE_INSENSITIVE_ENUMS 功能。

4.2. 使用 @JsonValue

我们学习了如何使用 @JsonValue 序列化枚举。我们也可以将相同的注释用于反序列化。这是可能的，因为枚举值是常量。

首先，让我们使用 @JsonValue 和其中一个 getter 方法 getMeters()

public enum Distance {
    ...

    @JsonValue
    public double getMeters() {
        return meters;
    }
}

getMeters() 方法的返回值表示枚举对象。因此，在反序列化示例 JSON

{"distance":"0.0254"}

Jackson 将查找getMeters() 返回值为 0.0254 的枚举对象。在这种情况下，该对象是 Distance.INCH

assertEquals(Distance.INCH, city.getDistance());

4.3. 使用 @JsonProperty

@JsonProperty 注释用于枚举实例

public enum Distance {
    @JsonProperty("distance-in-km")
    KILOMETER("km", 1000), 
    @JsonProperty("distance-in-miles")
    MILE("miles", 1609.34);
 
    ...
}

通过使用此注释，我们只是告诉 Jackson 将 @JsonProperty 的值映射到用此值注释的对象。

由于上述声明，示例 JSON 字符串

{"distance": "distance-in-km"}

将被映射到Distance.KILOMETER 对象

assertEquals(Distance.KILOMETER, city.getDistance());

4.4. 使用 @JsonCreator

Jackson 调用带有 @JsonCreator 注解的方法来获取包含类的实例。

考虑以下 JSON 表现形式

{
    "distance": {
        "unit":"miles", 
        "meters":1609.34
    }
}

然后我们将定义带有 @JsonCreator 注解的 forValues() 工厂方法

public enum Distance {
   
    @JsonCreator
    public static Distance forValues(@JsonProperty("unit") String unit,
      @JsonProperty("meters") double meters) {
        for (Distance distance : Distance.values()) {
            if (
              distance.unit.equals(unit) && Double.compare(distance.meters, meters) == 0) {
                return distance;
            }
        }

        return null;
    }

    ...
}

请注意 @JsonProperty 注解的使用，它将 JSON 字段与方法参数绑定。

然后，当我们反序列化 JSON 示例时，我们将得到结果

assertEquals(Distance.MILE, city.getDistance());

4.5. 使用自定义 反序列化器

如果上述技术都不可用，我们可以使用自定义反序列化器。例如，我们可能无法访问 Enum 的源代码，或者我们可能 正在 使用较旧的 Jackson 版本，该版本不支持到目前为止涵盖的一个或多个注解。

根据 我们的自定义反序列化文章，为了反序列化上一节提供的 JSON，我们将首先创建反序列化类

public class CustomEnumDeserializer extends StdDeserializer<Distance> {

    @Override
    public Distance deserialize(JsonParser jsonParser, DeserializationContext ctxt)
      throws IOException, JsonProcessingException {
        JsonNode node = jsonParser.getCodec().readTree(jsonParser);

        String unit = node.get("unit").asText();
        double meters = node.get("meters").asDouble();

        for (Distance distance : Distance.values()) {
           
            if (distance.getUnit().equals(unit) && Double.compare(
              distance.getMeters(), meters) == 0) {
                return distance;
            }
        }

        return null;
    }
}

然后我们将使用 @JsonDeserialize 注解在 Enum 上指定我们自定义的反序列化器

@JsonDeserialize(using = CustomEnumDeserializer.class)
public enum Distance {
   ...
}

我们的结果是

assertEquals(Distance.MILE, city.getDistance());

5. 结论

本文说明了如何更好地控制 Java Enum 的序列化和反序列化过程和格式。