Net项目中JSON解析异常问题分析与解决方案

在Kotlin多平台开发中，JSON序列化/反序列化是网络请求中最常见的操作之一。本文将以Net项目中的实际案例为切入点，深入分析JSON解析过程中遇到的类型转换异常问题，并提供完整的解决方案。

问题现象

开发者在Net项目中使用kotlinx.serialization进行JSON解析时遇到以下异常：

kotlinx.serialization.json.internal.JsonDecodingException: 
Unexpected JSON token at offset 1012: Unexpected symbol 'a' in numeric literal at path: $.code

异常表明解析器在尝试将字符串"aa"转换为数值类型时失败。核心矛盾点在于：

• 数据类中定义的code字段为Int类型
• 实际JSON响应中code字段值为字符串"aa"

根本原因分析

1. 类型声明不匹配 数据类定义：

@Serializable
class BaseResponseBean<T> {
    var code: Int = -1  // 声明为Int类型
    var data: T? = null
    var msg: String? = null
}

实际JSON响应：

{
    "code": "aa",  // 实际为String类型
    "data": {...},
    "msg": "成功"
}

2. kotlinx.serialization的严格类型检查 该库默认要求JSON数据类型必须与Kotlin类定义完全匹配，不支持自动类型转换。

3. 错误处理机制不足 当类型不匹配时，库直接抛出异常而非提供友好的错误提示。

解决方案

方案一：统一服务端与客户端类型定义（推荐）

修改服务端API，确保code字段始终返回数值类型：

{
    "code": 200,  // 改为数值
    "data": {...},
    "msg": "成功"
}

方案二：灵活的数据类定义

如果无法修改服务端，可以调整数据类定义：

@Serializable
class BaseResponseBean<T> {
    // 使用String接收，使用时再转换
    var code: String = "-1"  
    
    // 计算属性提供Int类型的访问
    val codeInt: Int get() = code.toIntOrNull() ?: -1
    
    var data: T? = null
    var msg: String? = null
    
    val isOk: Boolean get() = code == "200" // 修改比较逻辑
}

方案三：自定义序列化逻辑

对于复杂场景，可以实现KSerializer进行定制化处理：

object FlexibleIntSerializer : KSerializer<Int> {
    override val descriptor = PrimitiveSerialDescriptor("FlexibleInt", PrimitiveKind.INT)
    
    override fun serialize(encoder: Encoder, value: Int) {
        encoder.encodeInt(value)
    }
    
    override fun deserialize(decoder: Decoder): Int {
        return when(val element = decoder.decodeSerializableValue(JsonElement.serializer())) {
            is JsonPrimitive -> {
                if (element.isString) element.content.toIntOrNull() ?: -1
                else element.int
            }
            else -> -1
        }
    }
}

// 使用方式
@Serializable
class BaseResponseBean<T> {
    @Serializable(with = FlexibleIntSerializer::class)
    var code: Int = -1
    // ...
}

最佳实践建议

1. 前后端契约优先 在项目初期明确接口规范，特别是数据类型定义

2. 防御性编程

• 对可能为null的字段使用可空类型(?)
• 对可能类型不一的字段使用更宽泛的类型接收

3. 完善的错误处理

val result = runCatching {
    Net.get<UserDataBean>("...").await()
}.getOrElse {
    when(it) {
        is JsonDecodingException -> // 处理JSON解析错误
        else -> // 处理其他错误
    }
    return@getOrElse null
}

4. 日志记录 在网络拦截器中记录原始响应数据，便于问题排查

总结

JSON解析异常是移动端开发中的常见问题，通过本案例我们可以认识到：

1. 类型系统的严格性有助于提前发现问题
2. 前后端类型定义一致性的重要性
3. kotlinx.serialization提供了灵活的扩展机制
4. 防御性编程能有效提升应用健壮性

在实际项目中，建议结合具体场景选择最适合的解决方案，既要保证类型安全，又要兼顾开发效率。