JSON 元素
Kotlin 序列化也支援在結構層級處理 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,以便在將 JSON 結構轉換為 Kotlin 型別或字串之前對其進行處理。
使用 Json.parseToJsonElement() 函式將輸入剖析為 JSON 元素樹,而無需進行解碼或反序列化:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = Json.parseToJsonElement("""
{"name":"kotlinx.serialization","language":"Kotlin"}
""")
// JsonElement.toString() gives you a valid JSON string
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 資料時,如何使用這些擴充屬性:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = Json.parseToJsonElement("""
{
"name": "kotlinx.serialization",
"forks": [{"votes": 42}, {"votes": 9000}, {}]
}
""")
val sum = element
// Accesses the forks key from the JsonObject
.jsonObject["forks"]!!
// Accesses the value as a JsonArray and sums the votes values from each JsonObject as 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() 函式:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
// Creates JsonPrimitive values from different Kotlin primitives
val number = JsonPrimitive(42)
val text = JsonPrimitive("kotlinx.serialization")
println(number)
// 42
println(text)
// "kotlinx.serialization"
}你可以透過直接呼叫其建構函式或使用 builder 函式來建立 JsonArray 和 JsonObject 元素:
- 若要從
List建立JsonArray,請使用JsonArray(),或使用buildJsonArray()builder 函式。 - 若要從
Map建立JsonObject,請使用JsonObject(),或使用buildJsonObject()builder 函式。
Builder 函式提供了類似於 Kotlin 標準函式庫集合 builder 的 DSL,並具有 JSON 特定的多載和內部 builder 函式。
以下範例重點介紹了 JSON builder DSL 的主要功能:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val element = buildJsonObject {
// Adds a simple key-value pair to the JsonObject
put("name", "kotlinx.serialization")
// Adds a nested JsonObject under the owner key
putJsonObject("owner") {
put("name", "kotlin")
}
// Adds a JsonArray with multiple JsonObjects
putJsonArray("forks") {
// Adds a JsonObject to the JsonArray
addJsonObject {
put("votes", 42)
}
addJsonObject {
put("votes", 9000)
}
}
}
// Prints the resulting JSON string
println(element)
// {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"forks":[{"votes":42},{"votes":9000}]}
}編碼常值 JSON 內容
雖然 JSON 規格沒有限制數字的大小或精準度,但使用 JsonPrimitive() 函式序列化任意大小的數字可能會導致一些問題。
例如,如果你對大數使用 Double,該值可能會被截斷並遺失精準度。 如果你使用 Kotlin/JVM 的 BigDecimal,該值會保持精確,但 JsonPrimitive() 會將該值編碼為字串而不是數字:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
val format = Json { prettyPrint = true }
fun main() {
val pi = BigDecimal("3.141592653589793238462643383279")
// Converts the BigDecimal to a Double, causing potential truncation
val piJsonDouble = JsonPrimitive(pi.toDouble())
// Converts the BigDecimal to a String, preserving the precision but treating it as a string in 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 的字串值:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
val format = Json { prettyPrint = true }
fun main() {
val pi = BigDecimal("3.141592653589793238462643383279")
// Encodes the raw JSON content using JsonUnquotedLiteral()
@OptIn(ExperimentalSerializationApi::class)
val piJsonLiteral = JsonUnquotedLiteral(pi.toString())
// Converts to Double and 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 now accurately matches the value defined
println(format.encodeToString(piObject))
// "pi_literal": 3.141592653589793238462643383279,
// "pi_double": 3.141592653589793,
// "pi_string": "3.141592653589793238462643383279"
}若要將 pi 解碼回 BigDecimal,請擷取 JsonPrimitive 的字串內容:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal
fun main() {
val piObjectJson = """
{
"pi_literal": 3.141592653589793238462643383279
}
""".trimIndent()
// Decodes the JSON string into a JsonObject
val piObject: JsonObject = Json.decodeFromString(piObjectJson)
// Extracts the string content from the JsonPrimitive
val piJsonLiteral = piObject["pi_literal"]!!.jsonPrimitive.content
// Converts the string to a BigDecimal
val pi = BigDecimal(piJsonLiteral)
// Prints the decoded value of pi, preserving all 30 decimal places
println(pi)
// 3.141592653589793238462643383279
}為了簡潔起見,本範例使用了 JsonPrimitive。若要了解更多可重複使用的方法,請參閱 轉換 JSON 結構。
JSON null 常值
為了避免產生不一致的狀態,你無法使用 JsonUnquotedLiteral() 函式編碼字串 "null"。 如果嘗試這樣做,將會擲出例外:
// Imports declarations from the serialization library
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:
// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*
fun main() {
val possiblyNull = JsonNull
println(possiblyNull)
// null
}解碼 JSON 元素
若要將 JsonElement 類別的執行個體解碼為可序列化物件,請使用 Json.decodeFromJsonElement() 函式:
// Imports declarations from the serialization library
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")
}
// Decodes the JsonElement into a Project object
val data = Json.decodeFromJsonElement<Project>(element)
println(data)
// Project(name=kotlinx.serialization, language=Kotlin)
}後續步驟
- 探索如何在序列化與反序列化期間轉換 JSON,以更好地控制你的資料。
- 了解如何序列化類別,以及如何修改
@Serializable註解的預設行為。
