Fastjson2 枚举反序列化问题解析与解决方案

问题背景

在 Fastjson2 2.0.53 版本中，开发者在使用枚举类型反序列化时遇到了一个典型问题。当枚举类使用 @JsonValue 标注的字段为 Integer 类型时，无法正确反序列化来自字符串类型的值（如 "1" 或 "2"），导致返回结果为 null。

技术细节分析

枚举定义示例

enum class UserStatus(@JsonValue val value: Int, val label: String) {
    NORMAL(1, "正常"),
    LOCKED(2, "锁定"),
}

问题复现

当开启 Jackson 注解支持后，尝试将字符串 "2" 反序列化为 UserStatus 类型时：

JSONFactory.setUseJacksonAnnotation(true)
val value = "\"2\""
val status = JSON.parseObject(value, UserStatus::class.java) // 结果为 null

根本原因

1. 类型不匹配：虽然 @JsonValue 标注的字段是 Int 类型，但输入的是字符串形式的数字
2. 类型转换缺失：Fastjson2 在处理这种跨类型转换时，没有自动进行字符串到整型的转换
3. 注解处理逻辑：当启用 Jackson 注解支持时，反序列化逻辑会严格匹配字段类型

解决方案

方案一：升级 Fastjson2 版本

在 Fastjson2 的后续版本中（2.0.54+），已经修复了这个问题。升级后可以正确处理字符串到整型的自动转换。

方案二：自定义反序列化逻辑

如果无法立即升级，可以实现自定义的反序列化器：

class UserStatusDeserializer : ObjectDeserializer {
    override fun deserialze(parser: JSONParser, type: Type, fieldName: Any?): Any? {
        val value = parser.parse()
        return when (value) {
            is Int -> UserStatus.values().firstOrNull { it.value == value }
            is String -> UserStatus.values().firstOrNull { it.value == value.toInt() }
            else -> null
        }
    }
}

// 注册自定义反序列化器
JSON.register(UserStatus::class.java, UserStatusDeserializer())

方案三：使用中间类型转换

在接收参数时先使用 String 类型接收，然后手动转换为枚举：

val statusStr = params["status"] as String
val status = UserStatus.values().firstOrNull { it.value == statusStr.toInt() }

最佳实践建议

1. 统一数据类型：前后端约定好枚举值的传输类型，要么统一用字符串，要么统一用数字
2. 防御性编程：在枚举反序列化时添加 null 检查，避免 NPE
3. 版本管理：及时关注 Fastjson2 的更新，修复已知问题
4. 测试覆盖：为枚举类型的序列化和反序列化添加单元测试

总结

Fastjson2 作为高性能的 JSON 处理库，在枚举处理上提供了灵活的支持。开发者在使用时需要注意类型系统的严格性，特别是在开启 Jackson 注解支持后。通过理解底层原理和掌握解决方案，可以避免类似问题的发生，构建更健壮的系统。