别再用 toString() 了！Spring Boot + Jackson 处理枚举的七种方式

原创于 2025-10-30 13:40:26 发布 · 772 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java

在系统开发中，JSON 作为轻量级数据交换格式被广泛应用，而枚举（Enum）作为 Java 等语言中表示固定常量集合的类型，其与 JSON 的交互处理至关重要。

环境：SpringBoot3.4.2

1. 简介

在系统开发中，JSON 作为轻量级数据交换格式被广泛应用，而枚举（Enum）作为 Java 等语言中表示固定常量集合的类型，其与 JSON 的交互处理至关重要。传统场景下，枚举序列化可能直接输出其名称（如 "MALE"），但实际业务中常需更灵活的映射，例如输出数字代码（1）或国际化描述（"男"）。同时，反序列化时需根据 JSON 值（如数字或字符串）精准匹配枚举实例。

本篇文章将详细介绍枚举值在序列化和反序列化过程中的核心处理机制、常见应用场景及最佳实践方案。

2.实战案例

2.1 准备环境

定义性别枚举类

public enum Gender {
  UNKNOWN(0, "未知的性别"), MALE(1, "男"), FEMALE(2, "女"), UNSTATED(9, "未说明的性别");
  private final int code;
  private final String name;
  Gender(int code, String name) {
    this.code = code;
    this.name = name;
  }
  public int getCode() {
    return code ;
  }
  public String getName() {
    return name ;
  }
}

定义User实体对象包括上面的枚举字段

public record User(String name, int age, Gender gender) {
}

2.2 默认输出枚举值

@RestController
@RequestMapping("/users")
public class UserController {
  @GetMapping
  public ResponseEntity<User> query() {
    return ResponseEntity.ok(new User("Pack_xg", 33, Gender.MALE)) ;
  }
}

输出结果

2.3 将枚举序列化为JSON对象

当我们希望将枚举值序列化为如下格式：

{"code": 1, "name": "男"}

要输出此格式，我们可以通过如下注解进行标注枚举类：

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

输出结果

2.4 枚举与@JsonValue结合

控制枚举序列化输出的另一种简单方法是在 getter 方法上使用 @JsonValue 注解。该注解用于指示被注解的访问器（字段或“getter”方法[非void返回类型、无参数的方法]）的值应作为该实例的单一值进行序列化，而非采用常规的收集属性值的方式。

修改枚举类如下：

public enum Gender {
  // ...
  @JsonValue
  public String getName() {
    return name;
  }
}

在我们希望输出的字段上使用@JsonValue注解。

输出结果

当我们将@JsonValue使用到类中的toString时，如下：

public record User(String name, int age, Gender gender) {
  @JsonValue
  public String toString() {
    return "【name = " + this.name + ", age = " + this.age + ", gender = " + this.gender + "】";
  }
}

输出结果

2.5 自定义枚举序列化

我们可以通过继承 StdSerializer 的方式，实现自定义的序列化方式，如下示例：

public class GenderSerializer extends StdSerializer<Gender> {
  public GenderSerializer() {
    super(Gender.class);
  }
  public GenderSerializer(Class<Gender> t) {
    super(t);
  }
  public void serialize(Gender value, JsonGenerator generator, SerializerProvider provider)
      throws IOException, JsonProcessingException {
    generator.writeStartObject() ;
    generator.writeFieldName("label") ;
    generator.writeString(value.name()) ;
    generator.writeFieldName("value") ;
    generator.writeNumber(value.getCode()) ;
    generator.writeEndObject();
  }
}

接着修改Gender枚举类

@JsonSerialize(using = GenderSerializer.class)
public enum Gender {}

输出结果

2.6 反序列化枚举

@PostMapping
public ResponseEntity<User> save(@RequestBody User user) {
  return ResponseEntity.ok(user) ;
}

默认情况

我们修改gender值为数字也同样可以，如下：

使用@JsonValue

public enum Gender {
  @JsonValue
  public int getCode() {
    return code;
  }
}

输出结果

这时候你再换成枚举的字面量值将会报错，如下：

使用@JsonProperty

通过使用此注解，我们只是告诉Jackson将@JsonProperty的值映射到标注此值的对象。如下示例：

修改枚举类

public enum Gender {
  @JsonProperty("unknow")
  UNKNOWN(0, "未知的性别"),
  @JsonProperty("male")
  MALE(1, "男"), 
  @JsonProperty("female")
  FEMALE(2, "女"), 
  @JsonProperty("unknow_gender")
  UNSTATED(9, "未说明的性别");
}

输出结果

使用@JsonCreator

该注解用于将构造函数或工厂方法定义为用于实例化关联类新实例的指定方法。

修改枚举类如下：

public enum Gender {
  // ...
  @JsonCreator
  public Gender fromCode(@JsonProperty("gender") int code) {
    for (Gender gender : Gender.values()) {
      if (gender.code == code) {
        return gender;
      }
    }
    throw new IllegalArgumentException("无效的性别代码: " + code);
  }
}

输出结果

自定义反序列化

定义反序列化类

public class GenderDeserializer extends StdDeserializer<Gender> {
  public GenderDeserializer() {
    super(Gender.class) ;
  }
  @Override
  public Gender deserialize(JsonParser jsonParser, DeserializationContext ctxt)
      throws IOException, JsonProcessingException {
    int gender = jsonParser.getValueAsInt() ;
    for (Gender g : Gender.values()) {
      if (g.getCode() == gender) {
        return g ;
      }
    }
    return null;
  }
}

修改枚举类

@JsonDeserialize(using = GenderDeserializer.class)
public enum Gender {}

输出结果

AI大模型学习福利

作为一名热心肠的互联网老兵，我决定把宝贵的AI知识分享给大家。至于能学习到多少就看你的学习毅力和能力了。我已将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

一、全套AGI大模型学习路线

AI大模型时代的学习之旅：从基础到前沿，掌握人工智能的核心技能！

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

二、640套AI大模型报告合集

这套包含640份报告的合集，涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师，还是对AI大模型感兴趣的爱好者，这套报告合集都将为您提供宝贵的信息和启示。

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获

三、AI大模型经典PDF籍

随着人工智能技术的飞速发展，AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型，如GPT-3、BERT、XLNet等，以其强大的语言理解和生成能力，正在改变我们对人工智能的认识。那以下这些PDF籍就是非常不错的学习资源。

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获

四、AI大模型商业化落地方案

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获

作为普通人，入局大模型时代需要持续学习和实践，不断提高自己的技能和认知水平，同时也需要有责任感和伦理意识，为人工智能的健康发展贡献力量