https://www.runoob.com/kotlin/kotlin-tutorial.html

kotlin serialization 使用指南

Kotlin serialization是由kotlin官方提供，可将kotlin对象序列化和反序列化的插件，支持序列化格式包括：JSON, Protobuf, CBOR, Hocon 和Properties

serialization使用非常简单：

//序列化

val data = Project("kotlinx.serialization", "Kotlin")

val json = Json.encodeToString(data)

//反序列化

val obj = Json.decodeFromString<Project>(json)

一、添加serialization依赖

在module build.gradle里添加

plugins {

id 'kotlin-android'

id 'kotlinx-serialization'

id 'kotlin-kapt'

}

dependencies {

implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.0"

}

在project build.gradle里添加

buildscript {

ext.kotlin_version = '1.5.31'

repositories { mavenCentral() }

dependencies {

classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"

}

}

二、Kotlin 序列化指南

1、序列化操作

@Serializable

class Project(val name: String, val language: String)

fun main() {

val data = Project("kotlinx.serialization", "Kotlin")

println(Json.encodeToString(data))

}

1、可以被序列化的字段

只有具有支持字段的类的属性会被序列化，因此具有 getter/setter 且没有支持字段和委托属性的属性不会被序列化，如下例所示。

@Serializable

class Project(

// name带有支持字段属性，可以被序列化

var name: String

) {

var stars: Int = 0 // 带有支持字段属性，可以被序列化

val path: String //未带字段，不会被序列化

get() = "kotlin/$name"

var id by ::name //代理属性，不会被序列化

}

fun main() {

val data = Project("kotlinx.serialization").apply { stars = 9000 }

println(Json.encodeToString(data))

}

//print:{"name":"kotlinx.serialization","stars":9000}

2、默认值操作

默认情况下，默认值不会参与编码：

@Serializable

data class Project(val name: String, val language: String = "Kotlin")

fun main() {

val data = Project("kotlinx.serialization")

println(Json.encodeToString(data))

}

//print:{"name":"kotlinx.serialization"}

如果需要默认值参与序列化，可设置encodeDefaults属性：

@Serializable

class Project(

val name: String, val language: String = "Kotlin", val website: String? = null)

fun main() {

val data = Project("kotlinx.serialization")

println(Json { encodeDefaults = true }.encodeToString(data))

}

//print:{"name":"kotlinx.serialization","language":"Kotlin","website":null}

如果不希望null参与序列化，explicitNulls可设置为false

3、强制安全类型

serialization执行Kotlin语言的类型安全，如果json里面有null，而对应属性没有标记为可空，则会报异常

@Serializable

data class Project(val name: String, val language: String = "Kotlin")

fun main() {

val data = Json.decodeFromString<Project>("""

{"name":"kotlinx.serialization","language":null}""")

println(data)

}

报错：Unexpected JSON token at offset 52: Expected string literal but 'null' literal was found.

Use 'coerceInputValues = true' in 'Json {}` builder to coerce nulls to default values.

如果希望json为null时，使用默认值，则设置coerceInputValues = true

@Serializable

data class Project(val name: String, val language: String = "Kotlin")

fun main() {

val data = Json { coerceInputValues = true }.decodeFromString<Project>("""

{"name":"kotlinx.serialization","language":null}

""")

println(data)

}

//print：Project(name=kotlinx.serialization, language=Kotlin)

4、序列字段名称

默认情况下，编码表示中使用的属性名称（在我们的示例中为 JSON）与它们在源代码中的名称相同。用于序列化的名称称为序列名称，可以使用@SerialName注释进行更改

@Serializable

class Project(val name: String, @SerialName("lang") val language: String)

fun main() {

val data = Project("kotlinx.serialization", "Kotlin")

println(Json.encodeToString(data))

}

//print：{"name":"kotlinx.serialization","lang":"Kotlin"}

2、反序列化操作

@Serializable

class Project(val name: String, val language: String)

fun main() {

val data = Project("kotlinx.serialization", "Kotlin")

println(Json.encodeToString(data))

}

1、可选属性

只有在序列中存在对象的所有属性时，才能反序列化对象。例如:

@Serializable

data class Project(val name: String, val language: String)

fun main() {

val data = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""")

println(data)

}

由于json中没有language属性，会报异常：Exception in thread "main" kotlinx.serialization.MissingFieldException: Field 'language' is required for type with serial name 'example.exampleClasses04.Project', but it was missing

可以通过向属性添加默认值来修复此问题，如：

@Serializable

data class Project(val name: String, val language: String = "Kotlin")

fun main() {

val data = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""")

println(data)

}

//print：Project(name=kotlinx.serialization, language=Kotlin)

2、必需属性

在反序列化，如果你希望json必需包含指定的属性名，可以使用@Required注解

@Serializable

data class Project(val name: String, @Required val language: String = "Kotlin")

fun main() {

val data = Json.decodeFromString<Project>("""

{"name":"kotlinx.serialization"}

""")

println(data)

}

例子中，由于json未包含被标记为@Required的language属性，会报异常Field 'language' is required for type with serial name 'example.exampleClasses07.Project', but it was missing

3、JSON属性设置

Json {

prettyPrint = true //json格式化

isLenient = true //宽松解析，json格式异常也可解析，如：{name:"小红",age:"18"} + Person(val name:String,val age:Int) ->Person("小红",18)

ignoreUnknownKeys = true //忽略未知键，如{"name":"小红","age":"18"} ->Person(val name:String)

coerceInputValues = true //强制输入值，如果json属性与对象格式不符，则使用对象默认值，如：{"name":"小红","age":null} + Person(val name:String = "小绿"，val age:Int = 18) ->Person("小红",18)

encodeDefaults = true //编码默认值,默认情况下，默认值的属性不会参与序列化，通过设置encodeDefaults = true,可让默认属性参与序列化(可参考上述例子)

explicitNulls = true //序列化时是否忽略null

allowStructuredMapKeys = true //允许结构化映射(map的key可以使用对象)

allowSpecialFloatingPointValues = true //特殊浮点值：允许Double为NaN或无穷大

}

1、格式化

@Serializable

data class Person(val name:String,val age:Int)

val json = Json {

prettyPrint = true //是否格式化，默认false

prettyPrintIndent = " " //除首行外各行缩进，默认四个空格

}

println(json.encodeToString(Person("小明",18)))

//print:

{

"name": "小明",

"age": 18

}

2、宽松解析

val json = "{name:小明,age:\"18\"}" //这是一条格式有问题的json

val person = Json {

isLenient = true //json格式有问题，也有可能解析成功，默认false

}.decodeFromString<Person>(json)

println(person)

//print:Person(name=小明, age=18)

3、忽略未知键

默认情况下，json和实例化对像键值需要一一对应，但实际案例中，json和对象参数名可能无法一一对应，这种情况可以忽略未使用的键

@Serializable

data class Person(val name:String)

val json = """{"name":"小明","age":18}"""

println(Json{

ignoreUnknownKeys = true

}.decodeFromString<Person>(json))

//print:Person(name=小明)

4、强制输入值

json的值类型和实例化对象类型不一致时，使用对象的默认值

@Serializable

data class Person(val name:String = "小明",val age:Int = 18)

val json = """{"name":"小红","age":null}"""

println(Json{

coerceInputValues = true //默认false

}.decodeFromString<Person>(json))

//print:Person(name=小红, age=18)

5、编码默认值

序列化时，对象默认值参与序列化

@Serializable

data class Person(val name:String = "小明",val age:Int = 18)

println(Json{

encodeDefaults = false

}.encodeToString(Person(name = "小红")))

//plint:{"name":"小红"}

println(Json{

encodeDefaults = true

}.encodeToString(Person(name = "小红")))

//plint:{"name":"小红","age":18}

6、序列化时忽略null

@Serializable

data class Person(val name:String = "小明",val age:Int? = null)

println(Json{

encodeDefaults = true

explicitNulls = false

}.encodeToString(Person(name = "小红",age = null)))

//print:{"name":"小红"}

//explicitNulls = true时，值为null也会参与序列化

println(Json{

encodeDefaults = true

explicitNulls = true

}.encodeToString(Person(name = "小红",age = null)))