Java枚举序列化后JSON字段如何保持原值？

Question

在使用Jackson进行JSON序列化时，Java枚举默认会序列化为枚举的名称（即`name()`值），但实际业务中常需保留枚举的自定义属性值（如code或value字段）。例如，枚举 `Status { ACTIVE(1), INACTIVE(0); }` 希望序列化后输出 `"status": 1` 而非 `"status": "ACTIVE"`。如何通过Jackson配置或注解（如@JsonValue、@JsonCreator）实现枚举字段的自定义序列化与反序列化，确保JSON输出保持原值且可正确解析？这是开发中常见的痛点问题。

Answer 1

1. 问题背景与常见场景

在Java后端开发中，使用Jackson进行JSON序列化是Spring Boot等框架的标配。然而，开发者常遇到一个痛点：Java枚举默认通过name()方法序列化为字符串名称，而非业务所需的自定义字段（如code或value）。例如：

public enum Status {
    ACTIVE(1), INACTIVE(0);

    private final int code;

    Status(int code) {
        this.code = code;
    }

    public int getCode() {
        return code;
    }
}

当该枚举作为对象字段被Jackson序列化时，默认输出为：

{"status": "ACTIVE"}

而我们期望的是数值形式：

{"status": 1}

这一需求广泛存在于支付状态、订单类型、用户角色等业务系统中，因此实现枚举的**自定义序列化与反序列化**成为高阶开发者的必备技能。

2. Jackson核心机制解析

Jackson对枚举的处理基于以下两个关键注解和机制：

• @JsonValue：标记某个方法或字段，表示该值应作为JSON序列化的输出。
• @JsonCreator：用于反序列化时构造枚举实例，通常配合静态工厂方法使用。

此外，Jackson还支持通过SimpleModule注册自定义的JsonSerializer和JsonDeserializer，适用于更复杂的场景。

3. 方案一：使用 @JsonValue 实现简单自定义序列化

最轻量级的方式是在返回目标值的方法上添加@JsonValue：

public enum Status {
    ACTIVE(1), INACTIVE(0);

    private final int code;

    Status(int code) {
        this.code = code;
    }

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

此时序列化结果变为：

{"status": 1}

但注意：此方式仅控制**序列化行为**，反序列化仍需支持从1映射回ACTIVE。

4. 方案二：结合 @JsonCreator 实现双向兼容

为了支持反向解析，需引入@JsonCreator注解：

public enum Status {
    ACTIVE(1), INACTIVE(0);

    private final int code;

    Status(int code) {
        this.code = code;
    }

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

    @JsonCreator
    public static Status fromCode(int code) {
        for (Status status : Status.values()) {
            if (status.code == code) {
                return status;
            }
        }
        throw new IllegalArgumentException("Unknown code: " + code);
    }
}

现在，无论是序列化还是反序列化都能正确工作：

操作	输入	输出
序列化	Status.ACTIVE	{"status": 1}
反序列化	{"status": 1}	Status.ACTIVE
反序列化	{"status": "ACTIVE"}	失败（可选增强）

5. 方案三：注册全局自定义序列化器（高级用法）

对于多个类似枚举或需要统一策略的项目，可通过SimpleModule注册通用处理器：

SimpleModule module = new SimpleModule();
module.addSerializer(Status.class, new JsonSerializer<Status>() {
    @Override
    public void serialize(Status value, JsonGenerator gen, SerializerProvider serializers) 
        throws IOException {
        gen.writeNumber(value.getCode());
    }
});

module.addDeserializer(Status.class, new JsonDeserializer<Status>() {
    @Override
    public Status deserialize(JsonParser p, DeserializationContext ctxt) 
        throws IOException {
        int code = p.getValueAsInt();
        return Status.fromCode(code);
    }
});

objectMapper.registerModule(module);

这种方式适合微服务架构中统一枚举处理规范，避免重复代码。

6. 枚举设计最佳实践建议

结合实际工程经验，推荐如下设计模式：

1. 枚举应包含唯一标识字段（如code），并保证不可变。
2. 提供fromCode方法，并加入缓存优化性能（如Map<Integer, Status>）。
3. 考虑兼容旧系统，允许反序列化同时接受字符串名和数字码。
4. 使用@JsonProperty("code")辅助文档生成工具识别字段含义。
5. 在Swagger/OpenAPI中通过@Schema说明枚举值语义。
6. 单元测试覆盖正向与异常路径（如非法code传入）。
7. 日志记录时避免直接打印枚举引用，防止意外调用toString()。
8. 跨服务传输建议使用code而非name，提升稳定性。
9. 若前端依赖枚举文本展示，可通过DTO转换层做映射。
10. 谨慎使用ordinal()，因其易受代码顺序影响。

7. 常见陷阱与调试技巧

以下是开发者容易忽略的问题：

• 缓存未更新：修改枚举顺序可能导致ordinal()变化，影响数据库存储逻辑。
• 反序列化冲突：若同时存在@JsonCreator和默认构造器，Jackson可能选择错误路径。
• 泛型擦除问题：在集合中使用枚举时，需确保类型信息完整传递。
• 性能瓶颈：频繁遍历values()查找枚举，建议构建静态Map索引。

可通过启用Jackson调试日志观察序列化过程：

logging.level.com.fasterxml.jackson=DEBUG

8. 扩展思考：多字段枚举的序列化策略

有些业务场景下，枚举携带多个属性（如code, label, color），此时是否仍应只输出code？

这取决于上下文：

graph TD A[客户端需要全部信息?] -->|是| B(序列化为对象: {code:1,label:"激活"}) A -->|否| C(仅输出code: 1) B --> D[使用@JsonUnwrapped或自定义Serializer] C --> E[保持轻量传输]

权衡点在于网络开销与前端渲染效率之间的平衡。