Kotlinx.serialization中枚举类型的数值序列化方案解析

枚举序列化的默认行为分析

在Kotlinx.serialization库中处理枚举类型时，默认会将枚举值序列化为字符串形式。例如当定义一个带有整型值的枚举类时：

@Serializable
enum class TestEnum(val value: Int) {
    @SerialName("1") V1(1),
    @SerialName("2") V2(2)
}

调用序列化后会输出为JSON字符串数组：["1","2"]，而非预期的数值数组[1,2]。这是由于框架默认采用枚举的name或SerialName作为序列化依据，且始终输出为字符串类型。

数值序列化的实现方案

方案一：自定义序列化器

最直接的解决方案是实现自定义的KSerializer：

object TestEnumAsIntSerializer : KSerializer<TestEnum> {
    override val descriptor = PrimitiveSerialDescriptor("TestEnum", PrimitiveKind.INT)
    
    override fun serialize(encoder: Encoder, value: TestEnum) {
        encoder.encodeInt(value.value)
    }
    
    override fun deserialize(decoder: Decoder): TestEnum {
        val intValue = decoder.decodeInt()
        return TestEnum.values().first { it.value == intValue }
    }
}

使用时通过@Serializable(with = TestEnumAsIntSerializer::class)注解指定。这种方案的优势是精确控制序列化行为，但需要为每个枚举类单独实现。

方案二：基于序数的通用方案

可以创建通用化的序数序列化器（注意这会使用ordinal而非自定义值）：

inline fun <reified T : Enum<T>> enumAsOrdinalSerializer(): KSerializer<T> = 
    object : KSerializer<T> {
        override val descriptor = PrimitiveSerialDescriptor(
            "EnumOrdinal", 
            PrimitiveKind.INT
        )
        
        override fun serialize(encoder: Encoder, value: T) {
            encoder.encodeInt(value.ordinal)
        }
        
        override fun deserialize(decoder: Decoder): T {
            return enumValues<T>()[decoder.decodeInt()]
        }
    }

方案三：注解驱动改进建议

当前框架缺乏直接通过注解配置数值序列化的能力。理想情况下可以扩展注解系统，例如：

@Serializable
@SerialFormat(EnumSerialization.NUMBER) // 假想的注解
enum class TestEnum(val num: Int) {
    V1(1), V2(2)
}

这需要框架层面的支持，目前可通过KSP等编译器插件技术实现近似效果。

生产环境注意事项

1. 数值稳定性：使用自定义数值时需确保值唯一且不变，否则会导致历史数据反序列化失败
2. 性能考量：反序列化时的values().first{}操作有优化空间，可预先构建数值映射表
3. 多平台兼容：自定义序列化器需在所有目标平台测试
4. 文档维护：应在类文档中明确说明序列化格式

总结

Kotlinx.serialization对枚举的默认字符串序列化行为符合JSON规范，但在需要数值序列化的场景下，开发者需要通过自定义序列化器实现。对于需要保持类型安全又需要数值传输的场景（如协议通信），建议采用方案一；若只需简单序数表示，方案二更为通用。未来框架可能会提供更便捷的注解配置方式，但目前自定义实现是最可靠的解决方案。