Skip to content

自訂 Json 執行個體 ​

預設的 Json 執行個體嚴格遵循 JSON 規範以及 Kotlin 類別中的宣告。

你可以透過 Json() 建構函式建立自訂的 Json 執行個體,以使用更具彈性的 JSON 功能或型別轉換:

kotlin
// 基於預設配置建立一個 Json 執行個體,允許特殊浮點值
val customJson = Json {
    allowSpecialFloatingPointValues = true
}

// 使用與預設相同的語法,透過 customJson 執行個體將物件編碼為字串
val jsonString = customJson.encodeToString(Data(Double.NaN))
println(jsonString)

以這種方式建立的 Json 執行個體是不可變(immutable)且執行緒安全的(thread-safe),因此可以安全地儲存在頂層屬性中以供重複使用。

重複使用自訂的 Json 執行個體可以快取類別專屬的資訊,進而提升效能。

你也可以基於現有的 Json 執行個體,使用相同的 builder 語法修改其設定來建立新執行個體:

kotlin
// 基於現有 Json 建立新執行個體
val lenientJson = Json(customJson) {
    isLenient = true
    prettyPrint = true
}

自訂 JSON 結構 ​

你可以自訂 Json 執行個體在編碼與解碼期間組織結構化資料的方式。 這能讓你控制哪些值會出現在輸出中,以及特定型別如何表示。

編碼預設值 ​

預設情況下,JSON 編碼器會省略預設屬性值,因為在解碼時這些值會自動套用至缺失的屬性上。 此行為對於預設值為 null 的可 null 屬性特別有用,因為它可以避免寫入不必要的 null 值。 如需更多詳細資訊,請參閱管理預設屬性的序列化一節。

若要變更此預設行為,請在 Json 執行個體中將 encodeDefaults 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以編碼預設值
val format = Json { encodeDefaults = true }

@Serializable
class Project(
    val name: String,
    val language: String = "Kotlin",
    val website: String? = null
)

fun main() {
    val data = Project("kotlinx.serialization")

    // 編碼所有屬性值,包含預設值
    println(format.encodeToString(data))
    // {"name":"kotlinx.serialization","language":"Kotlin","website":null}
}

省略明確的 null ​

預設情況下,所有 null 值都會被編碼到 JSON 輸出中。 若要省略 null 值,請在 Json 執行個體中將 explicitNulls 屬性設為 false:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體在序列化期間省略 null 值
val format = Json { explicitNulls = false }

@Serializable
data class Project(
    val name: String,
    val language: String,
    val version: String? = "1.2.2",
    val website: String?,
    val description: String? = null
)

fun main() {
    val data = Project("kotlinx.serialization", "Kotlin", null, null, null)
    val json = format.encodeToString(data)

    // 從 JSON 輸出中省略 version、website 和 description 屬性
    println(json)
    // {"name":"kotlinx.serialization","language":"Kotlin"}

    // 將沒有預設值的缺失可 null 屬性視為 null
    // 將具有預設值的屬性填入其預設值
    println(format.decodeFromString<Project>(json))
    // Project(name=kotlinx.serialization, language=Kotlin, version=1.2.2, website=null, description=null)
}

當 explicitNulls 設為 false 時,編碼與解碼可能會呈現不對稱。 在此範例中,version 屬性在編碼前為 null,但解碼後會變成 1.2.2。

你可以透過 coerceInputValues 屬性來設定解碼器,將某些無效的輸入值視為缺失屬性處理。 欲了解更多資訊,請參閱強制轉換輸入值一節。

允許結構化 Map 鍵 ​

JSON 格式原生不支援具有結構化鍵的 Map,因為 JSON 的鍵必須是僅代表基本型別或列舉的字串。 若要序列化與反序列化以自訂類別作為鍵的 Map,請使用 allowStructuredMapKeys 屬性:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以編碼具有結構化鍵的 Map
val format = Json { allowStructuredMapKeys = true }

@Serializable
data class Project(val name: String)

fun main() {
    val map = mapOf(
        Project("kotlinx.serialization") to "Serialization",
        Project("kotlinx.coroutines") to "Coroutines"
    )
    // 將帶有結構化鍵的 Map 序列化為 JSON 陣列:
    // [key1, value1, key2, value2,...]
    println(format.encodeToString(map))
    // [{"name":"kotlinx.serialization"},"Serialization",{"name":"kotlinx.coroutines"},"Coroutines"]
}

允許特殊浮點值 ​

預設情況下,特殊浮點值(例如 Double.NaN 和無限大)在 JSON 中是不受支援的,因為 JSON 規範禁止使用它們。

若要啟用它們的編碼與解碼,請在 Json 執行個體中將 allowSpecialFloatingPointValues 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以允許特殊浮點值
val format = Json { allowSpecialFloatingPointValues = true }

@Serializable
class Data(
    val value: Double
)

fun main() {
    val data = Data(Double.NaN)
    // 產生用於表示特殊浮點值的非標準 JSON 輸出
    println(format.encodeToString(data))
    // {"value":NaN}
}

指定多型類別鑑別器 ​

在處理多型資料時,你可以使用 classDiscriminator 屬性來指定一個鍵名,以識別已序列化多型物件的型別。 結合透過 @SerialName 註解定義的明確序列化名稱, 這種方法可以讓你完全掌控最終產生的 JSON 結構:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以使用自訂的類別鑑別器
val format = Json { classDiscriminator = "#class" }

@Serializable
sealed class Project {
    abstract val name: String
}

// 為 OwnedProject 類別指定自訂的序列化名稱
@Serializable
@SerialName("owned")
class OwnedProject(override val name: String, val owner: String) : Project()

// 為 SimpleProject 類別指定自訂的序列化名稱
@Serializable
@SerialName("simple")
class SimpleProject(override val name: String) : Project()

fun main() {
    val simpleProject: Project = SimpleProject("kotlinx.serialization")
    val ownedProject: Project = OwnedProject("kotlinx.coroutines", "kotlin")

    // 序列化 SimpleProject,包含 #class: "simple"
    println(format.encodeToString(simpleProject))
    // {"#class":"simple","name":"kotlinx.serialization"}

    // 序列化 OwnedProject,包含 #class: "owned"
    println(format.encodeToString(ownedProject))
    // {"#class":"owned","name":"kotlinx.coroutines","owner":"kotlin"}
}

雖然 Json 執行個體中的 classDiscriminator 屬性可讓你為所有多型型別指定單一鑑別器鍵,但實驗性的 @JsonClassDiscriminator 註解提供了更大的彈性。 它允許你直接在基底類別上定義自訂鑑別器,並自動由其所有子類別繼承。

若要進一步了解可繼承的序列化註解,請參閱 @InheritableSerialInfo。

以下是一個範例:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// @JsonClassDiscriminator 註解是可繼承的,因此 Base 的所有子類別都將具有相同的鑑別器
@Serializable
@OptIn(ExperimentalSerializationApi::class)
@JsonClassDiscriminator("message_type")
sealed class Base

// 從 Base 繼承鑑別器
@Serializable
sealed class ErrorClass: Base()

// 定義一個結合了訊息與可選錯誤的類別
@Serializable
data class Message(val message: Base, val error: ErrorClass?)

@Serializable
@SerialName("my.app.BaseMessage")
data class BaseMessage(val message: String) : Base()

@Serializable
@SerialName("my.app.GenericError")
data class GenericError(@SerialName("error_code") val errorCode: Int) : ErrorClass()

val format = Json { classDiscriminator = "#class" }

fun main() {
    val data = Message(BaseMessage("not found"), GenericError(404))
    // 對所有子類別使用來自 Base 的鑑別器
    println(format.encodeToString(data))
    // {"message":{"message_type":"my.app.BaseMessage","message":"not found"},"error":{"message_type":"my.app.GenericError","error_code":404}}
}

你無法在密封基底類別的子類別中指定不同的類別鑑別器。 只有具有相異、不重疊子類別的階層結構,才能定義自己的鑑別器。

當兩者皆指定了鑑別器時,@JsonClassDiscriminator 的優先級高於 Json 設定中的設定。

設定類別鑑別器輸出模式 ​

使用 JsonBuilder.classDiscriminatorMode 屬性來控制如何將類別鑑別器新增至你的 JSON 輸出中。 預設情況下,僅為多型型別新增鑑別器,這在處理多型類別階層結構時非常實用。

若要調整此行為,請將 ClassDiscriminatorMode 屬性設為下列選項之一:

  • POLYMORPHIC:(預設)僅為多型型別新增類別鑑別器。
  • ALL_JSON_OBJECTS:在可行的情況下,為所有 JSON 物件新增類別鑑別器。
  • NONE:完全省略類別鑑別器。

以下是將 ClassDiscriminatorMode 屬性設為 NONE 的範例:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以從輸出中省略類別鑑別器
val format = Json { classDiscriminatorMode = ClassDiscriminatorMode.NONE }

@Serializable
sealed class Project {
    abstract val name: String
}

@Serializable
class OwnedProject(override val name: String, val owner: String) : Project()

fun main() {
    val data: Project = OwnedProject("kotlinx.coroutines", "kotlin")
    // 序列化時不包含鑑別器
    println(format.encodeToString(data))
    // {"name":"kotlinx.coroutines","owner":"kotlin"}
}

沒有鑑別器時,基底類別的序列化器將無法把輸出還原序列化回適當的型別。

美化輸出 (Pretty printing) ​

預設情況下,Json 會產生緊湊的單行輸出。

你可以透過在輸出中啟用美化列印來加入縮排和換行,以提高可讀性。 若要執行此操作,請在 Json 執行個體中將 prettyPrint 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 建立自訂 Json 格式
val format = Json { prettyPrint = true }

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

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

    // 列印帶有換行與縮排的 JSON 輸出
    println(format.encodeToString(data))
}

此範例會列印出下列結果:

text
{
    "name": "kotlinx.serialization",
    "language": "Kotlin"
}

你可以使用 prettyPrintIndent 選項來自訂美化 JSON 中所使用的縮排。

例如,你可以將預設的四個空格替換為任何允許的空白字元,例如 \t 或 \n。

自訂 JSON 反序列化 ​

Kotlin 的 Json 剖析器提供了數種設定,可讓你自訂 JSON 資料的剖析與反序列化過程。

忽略未知鍵 ​

處理來自第三方服務或其他動態來源的 JSON 資料時,隨著時間推移,JSON 物件中可能會新增新的屬性。

預設情況下,未知的鍵(JSON 輸入中的屬性名稱)在反序列化期間會導致錯誤。 若要防止此情況發生,請在 Json 執行個體中將 ignoreUnknownKeys 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 建立一個忽略未知鍵的 Json 執行個體
val format = Json { ignoreUnknownKeys = true }

@Serializable
data class Project(val name: String)

fun main() {
    val data = format.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":"Kotlin"}
    """)
    // language 鍵被忽略,因為它不存在於 Project 類別中
    println(data)
    // Project(name=kotlinx.serialization)
}
Experimental

針對特定類別忽略未知鍵

除了為所有類別啟用 ignoreUnknownKeys 之外, 你也可以使用 @JsonIgnoreUnknownKeys 註解僅針對特定類別忽略未知鍵。 這能讓你在預設情況下維持嚴格的反序列化,僅在需要之處允許寬鬆處理。

@JsonIgnoreUnknownKeys 註解為實驗性功能。 若要選擇加入,請使用 @OptIn(ExperimentalSerializationApi::class) 註解或編譯器選項 -opt-in=kotlinx.serialization.ExperimentalSerializationApi:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@OptIn(ExperimentalSerializationApi::class)
@Serializable
// Outer 中的未知屬性在反序列化期間會被忽略
@JsonIgnoreUnknownKeys
data class Outer(val a: Int, val inner: Inner)

@Serializable
data class Inner(val x: String)

fun main() {
    val outer = Json.decodeFromString<Outer>(
        """{"a":1,"inner":{"x":"value"},"unknownKey":42}"""
    )
    println(outer)
    // Outer(a=1, inner=Inner(x=value))

    // 擲出例外
    // inner 內部的 unknownKey 不會被忽略,因為 Inner 未加上註解
    println(
        Json.decodeFromString<Outer>(
            """{"a":1,"inner":{"x":"value","unknownKey":"unexpected"}}"""
        )
    )
}

在此範例中,Inner 會因未知鍵而擲出 SerializationException,因為它並未以 @JsonIgnoreUnknownKeys 進行註解。

強制轉換輸入值 ​

處理來自第三方服務或其他動態來源的 JSON 資料時,格式可能會發生變更。 當實際值與預期型別不符時,這可能會在解碼期間導致例外。

預設的 Json 實作對於輸入型別非常嚴格。 若要放寬此限制,請在 Json 執行個體中將 coerceInputValues 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

val format = Json { coerceInputValues = true }

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

fun main() {
    val data = format.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":null}
    """)

    // 將 language 的無效 null 值強制轉換為其預設值
    println(data)
    // Project(name=kotlinx.serialization, language=Kotlin)
}

coerceInputValues 屬性僅影響解碼。它會將某些無效的輸入值視為對應屬性缺失來處理。 目前,它適用於:

  • 非可 null 型別的 null 輸入
  • 列舉的未知值

此清單在未來版本中可能會擴充,透過以預設值或 null 取代無效值, 讓包含此屬性的 Json 執行個體更具寬容性。

若缺少某個值,且存在預設屬性值,則會將其替換為該預設值。

對於列舉,僅在符合以下條件時才會將值替換為 null:

  • 未定義預設值。
  • explicitNulls 屬性設為 false。
  • 該屬性為可 null。

你可以結合 coerceInputValues 與 explicitNulls 屬性來處理無效的列舉值:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

enum class Color { BLACK, WHITE }

@Serializable
data class Brush(val foreground: Color = Color.BLACK, val background: Color?)

val json = Json { 
  coerceInputValues = true
  explicitNulls = false
}

fun main() {

    // 將未知的 foreground 值強制轉換為其預設值,並將 background 強制轉換為 null
    val brush = json.decodeFromString<Brush>("""{"foreground":"pink", "background":"purple"}""")
    println(brush)
    // Brush(foreground=BLACK, background=null)
}

允許尾隨逗號 ​

若要在 JSON 輸入中允許尾隨逗號,請將 allowTrailingComma 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 允許 JSON 物件與陣列中出現尾隨逗號
val format = Json { allowTrailingComma = true }

fun main() {
    val numbers = format.decodeFromString<List<Int>>(
        """
            [1, 2, 3,]
        """
    )
    println(numbers)
    // [1, 2, 3]
}

允許 JSON 中的註解 ​

使用 allowComments 屬性以允許 JSON 輸入中的註解。 啟用此屬性後,剖析器將接受輸入中以下形式的註解:

  • 以換行符號 \n 結尾的 // 行註解
  • /* */ 區塊註解

以下是一個範例:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 允許 JSON 輸入中的註解
val format = Json { allowComments = true }

fun main() {
    val numbers = format.decodeFromString<List<Int>>(
        """
            [
                // first element
                1,
                /* second element */
                2
            ]
        """
    )
    println(numbers)
    // [1, 2]
}

寬鬆剖析 ​

預設情況下,Json 剖析器會強制執行嚴格的 JSON 規則以確保符合 RFC-8259 規範, 該規範要求鍵和字串常值必須用引號包裹。

若要放寬這些限制,請在 Json 執行個體中將 isLenient 屬性設為 true:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

val format = Json { isLenient = true }

enum class Status { SUPPORTED }

@Serializable
data class Project(val name: String, val status: Status, val votes: Int)

fun main() {
    // 使用寬鬆剖析解碼 JSON 字串
    // 寬鬆剖析允許無引號的鍵、字串與列舉值
    val data = format.decodeFromString<Project>("""
        {
            name   : kotlinx.serialization,
            status : SUPPORTED,
            votes  : "9000"
        }
    """)
    println(data)
    // Project(name=kotlinx.serialization, status=SUPPORTED, votes=9000)
}

自訂 JSON 與 Kotlin 之間的名稱對應 ​

某些 JSON 資料可能無法完全符合 Kotlin 的命名慣例或預期格式。 為了解決這些問題,Kotlin serialization 提供了多種工具來管理命名差異、 處理多個 JSON 屬性名稱,並確保序列化資料具備一致的命名策略。

為單一 Kotlin 屬性接受替代的 JSON 屬性名稱 ​

當 JSON 屬性名稱在不同架構版本之間變更時, 你可以使用 @SerialName 註解來重新命名 JSON 屬性。

然而,這會導致無法解碼仍在使用舊屬性名稱的資料。 若要為單一屬性接受替代的 JSON 屬性名稱,請使用 @JsonNames 註解:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// 將 name 和 title 這兩個 JSON 屬性皆對應至 name 屬性
data class Project(@JsonNames("title") val name: String)

fun main() {
    val project = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""")
    println(project)
    // Project(name=kotlinx.serialization)

    val oldProject = Json.decodeFromString<Project>("""{"title":"kotlinx.coroutines"}""")
    // name 和 title 這兩個 JSON 屬性皆對應至 name 屬性
    println(oldProject)
    // Project(name=kotlinx.coroutines)
}

JsonBuilder 中的 useAlternativeNames 屬性用於啟用 @JsonNames 註解。 此屬性預設為 true,允許 Json 辨識並解碼單一屬性的多個名稱。

如果你沒有使用 @JsonNames 且希望提升效能, 特別是在使用 ignoreUnknownKeys 跳過許多未知屬性時,可以將此屬性設為 false。

以不區分大小寫的方式解碼列舉 ​

Kotlin 的命名慣例建議列舉值使用大寫搭配底線, 或使用大駝峰式大小寫(Upper CamelCase)。 預設情況下,Json 在解碼時會嚴格比對 Kotlin 列舉常數的名稱。

然而,來自外部資料來源的 JSON 資料可能會使用小寫或混合大小寫的名稱。 若要處理此類情況,請透過 JsonBuilder.decodeEnumsCaseInsensitive 屬性將 Json 執行個體設定為以不區分大小寫的方式解碼列舉值:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 設定 Json 執行個體以不區分大小寫的方式解碼列舉值
val format = Json { decodeEnumsCaseInsensitive = true }

enum class Cases { VALUE_A, @JsonNames("Alternative") VALUE_B }

@Serializable
data class CasesList(val cases: List<Cases>)

fun main() {
    // 解碼列舉值時忽略大小寫,包含替代名稱
    println(format.decodeFromString<CasesList>("""{"cases":["value_A", "alternative"]}""")) 
    // CasesList(cases=[VALUE_A, VALUE_B])
}

此屬性同時適用於序列化名稱以及透過 @JsonNames 註解指定的替代名稱, 確保所有值都能成功解碼。此屬性不會影響編碼。

套用全域命名策略 ​

當 JSON 輸入中的屬性名稱與 Kotlin 中的屬性名稱不同時,你可以使用 @SerialName 註解明確指定每個屬性的名稱。 但是,從其他架構或舊版程式碼庫遷移時,你可能需要以相同方式轉換每個序列化名稱。

針對這些情境,你可以在 Json 執行個體中使用 JsonBuilder.namingStrategy 屬性指定全域命名策略。 Kotlin serialization 提供了內建策略,例如 JsonNamingStrategy.SnakeCase:

kotlin
// 從序列化程式庫匯入宣告
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class Project(val projectName: String, val projectOwner: String)

// 設定 Json 執行個體以套用 SnakeCase 命名策略
val format = Json { namingStrategy = JsonNamingStrategy.SnakeCase }

fun main() {
    val project = format.decodeFromString<Project>("""{"project_name":"kotlinx.coroutines", "project_owner":"Kotlin"}""")
    // 序列化與反序列化時,所有序列化名稱都會從駝峰式大小寫轉換為蛇形命名法(snake_case)
    println(format.encodeToString(project.copy(projectName = "kotlinx.serialization")))
    // {"project_name":"kotlinx.serialization","project_owner":"Kotlin"}
}

透過 JsonNamingStrategy 使用全域命名策略時,請記住以下幾點:

  • 轉換會套用至所有屬性,無論序列化名稱是衍生自屬性名稱,或是使用 @SerialName 註解明確定義的。 你無法透過指定序列化名稱來將某個屬性排除於轉換之外。 若要在序列化期間保持特定名稱不變,請改用 @JsonNames 註解。
  • 若轉換後的名稱與其他轉換後的屬性名稱發生衝突,或是與 @JsonNames 註解指定的替代名稱衝突, 反序列化將會失敗並擲出例外。
  • 全域命名策略是隱式的。 這會讓單憑檢視類別定義很難確定序列化後的名稱。 這可能使 IDE 中的尋找用法(Find Usages)、重新命名(Rename)等工作,或是使用 grep 等工具進行全文檢索變得更加困難,進而可能增加錯誤風險與維護成本。

考慮到這些因素,在應用程式中實作全域命名策略之前,請仔細權衡利弊。

接續閱讀 ​