JSON 元素
Kotlin serialization 还支持在结构层面操作 JSON。 你可以使用 JsonElement API 在将 JSON 结构转换为 Kotlin 类型或字符串之前,直接对其进行检查、修改与构建。
JsonElement 有三个直接子类型,分别代表核心的 JSON 结构:
JsonPrimitive处理基本 JSON 元素,例如字符串、数字、布尔值和null。null值由JsonPrimitive的一个特殊子类JsonNull表示。 每个JsonPrimitive都存储其值的字符串表示形式,你可以通过其JsonPrimitive.content属性进行访问。JsonArray表示 JSON 数组。它是包含JsonElement项的 KotlinList。JsonObject表示 JSON 对象。它是键为String、值为JsonElement的 KotlinMap。
将字符串解析为 JSON 元素
你可以将字符串解析为 JsonElement,以便在将其转换为 Kotlin 类型或字符串之前先处理 JSON 结构。
使用 Json.parseToJsonElement() 函数将输入解析为 JSON 元素树,而无需对其进行解码或反序列化:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = Json.parseToJsonElement("""
{"name":"kotlinx.serialization","language":"Kotlin"}
""")
// JsonElement.toString() 会生成一个有效的 JSON 字符串
println(element)
// {"name":"kotlinx.serialization","language":"Kotlin"}
}访问 JSON 元素的内容
你可以直接通过 JsonElement API 的扩展属性访问 JSON 元素的内容。 这些扩展属性会将元素转换为特定的子类型, 如果该元素不具备预期的 JSON 结构,则会抛出 IllegalArgumentException。
可用的扩展属性包括:
jsonPrimitive返回一个JsonPrimitive。jsonArray返回一个JsonArray。jsonObject返回一个JsonObject。
类似地,JsonPrimitive 也提供了用于将值解析为 Kotlin 基本类型的扩展属性,例如 int、intOrNull、long 以及 longOrNull。
以下示例展示了在处理已知结构的 JSON 数据时如何使用这些扩展属性:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = Json.parseToJsonElement("""
{
"name": "kotlinx.serialization",
"forks": [{"votes": 42}, {"votes": 9000}, {}]
}
""")
val sum = element
// 从 JsonObject 访问 forks 键
.jsonObject["forks"]!!
// 作为 JsonArray 访问该值,并将每个 JsonObject 的 votes 值求和为 Int
.jsonArray.sumOf { it.jsonObject["votes"]?.jsonPrimitive?.int ?: 0 }
println(sum)
// 9042
}如果你预先不知道 JSON 的结构,可以检查元素类型并显式处理每个 JsonElement 子类型。 例如,你可以使用带有 when 表达式的帮助函数:
fun processElement(element: JsonElement): String = when (element) {
is JsonObject -> "JsonObject with keys: ${element.keys}"
is JsonArray -> "JsonArray with ${element.size} elements"
is JsonPrimitive -> "JsonPrimitive with content: ${element.content}"
}创建 JSON 元素
你可以直接创建特定 JsonElement 子类型的实例。
要创建 JsonPrimitive,请使用 JsonPrimitive() 函数:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
// 从不同的 Kotlin 基本类型创建 JsonPrimitive 值
val number = JsonPrimitive(42)
val text = JsonPrimitive("kotlinx.serialization")
println(number)
// 42
println(text)
// "kotlinx.serialization"
}你可以通过直接调用构造函数或使用构建器函数来创建 JsonArray 和 JsonObject 元素:
- 要从
List创建JsonArray,可以使用JsonArray(),或者使用buildJsonArray()构建器函数。 - 要从
Map创建JsonObject,可以使用JsonObject(),或者使用buildJsonObject()构建器函数。
这些构建器函数提供了类似于 Kotlin 标准库集合构建器的 DSL,并包含 JSON 特有的重载和内部构建器函数。
以下示例突显了 JSON 构建器 DSL 的主要功能:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = buildJsonObject {
// 向 JsonObject 添加一个简单的键值对
put("name", "kotlinx.serialization")
// 在 owner 键下添加一个嵌套的 JsonObject
putJsonObject("owner") {
put("name", "kotlin")
}
// 添加一个包含多个 JsonObject 的 JsonArray
putJsonArray("forks") {
// 向 JsonArray 添加一个 JsonObject
addJsonObject {
put("votes", 42)
}
addJsonObject {
put("votes", 9000)
}
}
}
// 输出生成的 JSON 字符串
println(element)
// {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"forks":[{"votes":42},{"votes":9000}]}
}编码 JSON 字面量内容
虽然 JSON 规范没有限制数字的大小或精度,但使用 JsonPrimitive() 函数序列化任意大小的数字可能会引发一些问题。
例如,如果对大数字使用 Double,该值可能会被截断,从而丢失精度。 如果使用 Kotlin/JVM 的 BigDecimal,精度得以保留,但 JsonPrimitive() 会将该值编码为字符串而不是数字:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
val format = Json { prettyPrint = true }
fun main() {
val pi = BigDecimal("3.141592653589793238462643383279")
// 将 BigDecimal 转换为 Double,可能导致截断
val piJsonDouble = JsonPrimitive(pi.toDouble())
// 将 BigDecimal 转换为 String,保留了精度,但在 JSON 中会被视作字符串
val piJsonString = JsonPrimitive(pi.toString())
val piObject = buildJsonObject {
put("pi_double", piJsonDouble)
put("pi_string", piJsonString)
}
println(format.encodeToString(piObject))
// "pi_double": 3.141592653589793,
// "pi_string": "3.141592653589793238462643383279"
}在本例中,即使 pi 被定义为带有 30 位小数的数字,生成的 JSON 也无法保留该精度。 Double 值被截断为 15 位小数,而 String 值则被包裹在引号中,因此它变成了 JSON 字符串而非数字。
为了避免这些问题,你可以使用 JsonUnquotedLiteral() 函数来编码任意未加引号的值(如本例中 pi 的字符串值):
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
val format = Json { prettyPrint = true }
fun main() {
val pi = BigDecimal("3.141592653589793238462643383279")
// 使用 JsonUnquotedLiteral() 编码原始 JSON 内容
@OptIn(ExperimentalSerializationApi::class)
val piJsonLiteral = JsonUnquotedLiteral(pi.toString())
// 转换为 Double 和 String
val piJsonDouble = JsonPrimitive(pi.toDouble())
val piJsonString = JsonPrimitive(pi.toString())
val piObject = buildJsonObject {
put("pi_literal", piJsonLiteral)
put("pi_double", piJsonDouble)
put("pi_string", piJsonString)
}
// pi_literal 现在精确匹配所定义的值
println(format.encodeToString(piObject))
// "pi_literal": 3.141592653589793238462643383279,
// "pi_double": 3.141592653589793,
// "pi_string": "3.141592653589793238462643383279"
}要将 pi 解码回 BigDecimal,请提取 JsonPrimitive 的字符串内容:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
fun main() {
val piObjectJson = """
{
"pi_literal": 3.141592653589793238462643383279
}
""".trimIndent()
// 将 JSON 字符串解码为 JsonObject
val piObject: JsonObject = Json.decodeFromString(piObjectJson)
// 从 JsonPrimitive 提取字符串内容
val piJsonLiteral = piObject["pi_literal"]!!.jsonPrimitive.content
// 将字符串转换为 BigDecimal
val pi = BigDecimal(piJsonLiteral)
// 输出解码后的 pi 值,保留全部 30 位小数
println(pi)
// 3.141592653589793238462643383279
}本例为简单起见使用了 JsonPrimitive。关于更具可复用性的方法,请参阅转换 JSON 结构。
JSON null 字面量
为避免产生不一致的状态,你不能使用 JsonUnquotedLiteral() 函数编码字符串 "null"。 如果尝试这样做,则会抛出异常:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@OptIn(ExperimentalSerializationApi::class)
fun main() {
JsonUnquotedLiteral("null")
// Exception in thread "main" kotlinx.serialization.json.internal.JsonEncodingException
}要表示 JSON null 字面量值,请使用 JsonNull:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val possiblyNull = JsonNull
println(possiblyNull)
// null
}解码 JSON 元素
要将 JsonElement 类的实例解码为可序列化对象,请使用 Json.decodeFromJsonElement() 函数:
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
data class Project(val name: String, val language: String)
fun main() {
val element = buildJsonObject {
put("name", "kotlinx.serialization")
put("language", "Kotlin")
}
// 将 JsonElement 解码为 Project 对象
val data = Json.decodeFromJsonElement<Project>(element)
println(data)
// Project(name=kotlinx.serialization, language=Kotlin)
}下一步
- 了解如何在序列化和反序列化期间转换 JSON,从而更好地掌控你的数据。
- 了解如何序列化类以及如何修改
@Serializable注解的默认行为。
