1. Kotlin Serialization 基础配置1.1 项目依赖配置在Kotlin项目中使用Serialization处理JSON首先需要在Gradle配置中添加必要的依赖。对于使用Kotlin DSL的build.gradle.kts文件配置如下// 项目级build.gradle.kts plugins { kotlin(jvm) version 1.9.0 kotlin(plugin.serialization) version 1.9.0 // 必须应用序列化插件 } // 模块级build.gradle.kts dependencies { implementation(org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0) }这里有几个关键点需要注意插件版本应与Kotlin编译器版本保持一致避免兼容性问题序列化插件必须在所有使用它的模块中应用JSON实现库版本建议使用最新稳定版提示如果项目使用Groovy DSL的build.gradle文件配置方式略有不同需要将kotlin()调用改为字符串形式。1.2 基础数据类定义定义可序列化的数据类非常简单只需要添加Serializable注解import kotlinx.serialization.Serializable Serializable data class User( val name: String, val age: Int 18, // 带默认值的属性 SerialName(email_address) val email: String? // 自定义JSON字段名 )这个简单的数据类已经包含了几个重要特性默认值当JSON中缺少age字段时会自动使用默认值18空安全email被声明为可空类型可以正确处理JSON中的null值字段映射使用SerialName注解将email属性映射到JSON中的email_address字段2. 核心序列化操作2.1 基本序列化与反序列化创建Json实例并进行基本操作import kotlinx.serialization.encodeToString import kotlinx.serialization.decodeFromString import kotlinx.serialization.json.Json val json Json { ignoreUnknownKeys true // 忽略JSON中的未知字段 coerceInputValues true // 对缺失字段使用默认值 explicitNulls false // 不序列化null值 } // 序列化示例 val user User(Alice, email aliceexample.com) val jsonString json.encodeToString(user) println(jsonString) // 输出: {name:Alice,email_address:aliceexample.com} // 反序列化示例 val jsonInput {name:Bob,email_address:null} val decodedUser json.decodeFromStringUser(jsonInput) println(decodedUser) // 输出: User(nameBob, age18, emailnull)2.2 Json配置详解Json构建器支持多种配置选项以下是常用配置及其作用配置选项类型默认值作用描述ignoreUnknownKeysBooleanfalse是否忽略JSON中的未知字段coerceInputValuesBooleanfalse是否对无效值使用默认值explicitNullsBooleantrue是否序列化null值encodeDefaultsBooleanfalse是否序列化默认值isLenientBooleanfalse是否允许非标准JSON格式allowStructuredMapKeysBooleanfalse是否允许复杂类型作为Map键实际项目中通常会根据API规范选择合适的配置组合。例如与第三方API交互时建议启用ignoreUnknownKeys以避免因API新增字段导致解析失败。3. 高级序列化场景3.1 自定义序列化器对于标准库不直接支持的类型如Date需要实现自定义序列化器import kotlinx.serialization.* import java.text.SimpleDateFormat import java.util.Date object DateSerializer : KSerializerDate { private val format SimpleDateFormat(yyyy-MM-dd) override val descriptor: SerialDescriptor PrimitiveSerialDescriptor(Date, PrimitiveKind.STRING) override fun serialize(encoder: Encoder, value: Date) { encoder.encodeString(format.format(value)) } override fun deserialize(decoder: Decoder): Date { return format.parse(decoder.decodeString()) ?: throw SerializationException(Invalid date format) } } Serializable data class Event( val name: String, Serializable(with DateSerializer::class) val date: Date )3.2 多态类型处理处理继承体系的多态序列化需要使用Polymorphic注解Serializable abstract class Response Serializable SerialName(success) data class SuccessResponse(val data: String) : Response() Serializable SerialName(error) data class ErrorResponse(val message: String) : Response() // 使用配置 val json Json { classDiscriminator type // 指定类型标识字段名 polymorphicDefault Response.serializer() // 设置默认反序列化器 } // 序列化时会自动添加type字段 val response: Response SuccessResponse(data) val jsonString json.encodeToString(response) // 输出: {type:success,data:data}4. 实战技巧与问题排查4.1 性能优化建议重用Json实例Json对象的创建有一定开销建议在应用程序中共享单个实例预编译序列化器对于频繁使用的类型可以预先获取其序列化器private val userSerializer User.serializer() json.encodeToString(userSerializer, user)使用流式处理对于大文件使用Json.decodeFromStream/encodeToStream4.2 常见问题解决问题1MissingFieldException异常现象反序列化时抛出Field xxx is required but missing异常解决方案为属性添加默认值将属性声明为可空类型配置coerceInputValues true问题2混淆后序列化失败解决方案在ProGuard规则中添加-keep class com.example.model.** { *; } -keepclasseswithmembers class * { kotlinx.serialization.Serializable fields; }问题3日期格式不一致解决方案统一使用自定义序列化器或ISO8601格式字符串4.3 与其他库的对比特性Kotlin SerializationGsonMoshiJackson无反射✓✗✓✗Kotlin原生支持✓✗✓部分编译时安全✓✗✓✗多平台支持✓✗✗✗学习曲线中等简单中等较陡选择建议纯Kotlin项目优先考虑Kotlin Serialization或MoshiJava/Kotlin混合项目考虑Jackson或Gson多平台项目Kotlin Serialization是唯一选择5. 实际项目集成案例5.1 网络请求响应处理结合Ktor客户端处理API响应import io.ktor.client.* import io.ktor.client.call.* import io.ktor.client.request.* import kotlinx.serialization.Serializable Serializable data class ApiResponseT( val code: Int, val message: String, val data: T ) Serializable data class User(val id: String, val name: String) suspend fun fetchUser(client: HttpClient, userId: String): User { val response: ApiResponseUser client.get(https://api.example.com/users/$userId).body() if (response.code ! 200) throw Exception(response.message) return response.data }5.2 配置文件解析解析JSON格式的配置文件Serializable data class AppConfig( val server: ServerConfig, val database: DatabaseConfig, val features: MapString, Boolean ) Serializable data class ServerConfig( val host: String, val port: Int, val ssl: Boolean false ) Serializable data class DatabaseConfig( val url: String, val poolSize: Int 10 ) fun loadConfig(file: File): AppConfig { return Json.decodeFromStringAppConfig(file.readText()) }5.3 数据持久化实现简单的JSON格式数据存储class JsonDataStoreT : Any(private val serializer: KSerializerT, private val file: File) { private val json Json { prettyPrint true } fun save(data: T) { file.writeText(json.encodeToString(serializer, data)) } fun load(): T? { return if (file.exists()) { json.decodeFromString(serializer, file.readText()) } else null } } // 使用示例 Serializable data class AppState(val userId: String, val preferences: MapString, String) val store JsonDataStore(AppState.serializer(), File(app_state.json)) store.save(AppState(user123, mapOf(theme to dark))) val state store.load()6. 测试与验证策略6.1 单元测试配置为序列化逻辑编写单元测试class SerializationTest { private val json Json { ignoreUnknownKeys true } Test fun test basic serialization() { val user User(Test, 30, testexample.com) val jsonString json.encodeToString(user) assertTrue(jsonString.contains(Test)) val decoded json.decodeFromStringUser(jsonString) assertEquals(user, decoded) } Test fun test missing field with default() { val input {name:Test} val user json.decodeFromStringUser(input) assertEquals(18, user.age) // 验证默认值 } }6.2 边界情况测试测试各种边界条件Test fun test null handling() { val input {name:Test,email_address:null} val user json.decodeFromStringUser(input) assertNull(user.email) } Test fun test malformed json() { val input {name:Test, age: invalid} assertThrowsSerializationException { json.decodeFromStringUser(input) } }6.3 性能测试评估序列化性能Test fun test serialization performance() { val users List(1000) { User(User$it, it % 100, user$ittest.com) } val time measureTimeMillis { repeat(100) { json.encodeToString(users) } } println(Average time: ${time / 100.0}ms) assertTrue(time 1000) // 确保性能在可接受范围内 }7. 进阶主题与扩展7.1 多平台支持Kotlin Serialization的一个强大特性是支持多平台// 公共模块中定义可序列化类 Serializable expect class PlatformDate // 各平台实现 // JVM实现 Serializable actual typealias PlatformDate java.util.Date // JS实现 Serializable actual external class PlatformDate { // JavaScript Date相关实现 }7.2 自定义编码格式除了JSON还可以支持其他格式// 使用CBOR格式(需要添加额外依赖) implementation(org.jetbrains.kotlinx:kotlinx-serialization-cbor:1.6.0) val cbor Cbor { } val bytes cbor.encodeToByteArray(User.serializer(), user) val decoded cbor.decodeFromByteArrayUser(bytes)7.3 与KSP集成使用KSP(Kotlin Symbol Processing)进行高级代码生成// 在build.gradle.kts中添加KSP插件 plugins { id(com.google.devtools.ksp) version 1.9.0-1.0.12 } dependencies { ksp(org.jetbrains.kotlinx:kotlinx-serialization-ksp:1.6.0) }KSP可以生成更高效的序列化代码特别适合大型项目。8. 版本升级与迁移8.1 从旧版本迁移从1.5.x升级到1.6.x的主要变化改进了对Map的序列化支持增强了多态序列化的稳定性优化了默认值处理逻辑迁移步骤更新依赖版本检查自定义序列化器的实现测试边缘案例特别是涉及默认值和多态的情况8.2 兼容性考虑需要注意的兼容性问题序列化格式版本兼容性与Kotlin编译器版本的匹配与其他库(如Ktor)的版本协调建议的版本组合Kotlin版本Serialization版本1.8.x1.5.x1.9.x1.6.x8.3 废弃API处理1.6.x中废弃的API一些过时的扩展函数旧的多态序列化方式不推荐使用的配置选项替代方案已在文档中明确说明建议在升级前查阅官方迁移指南。