kotlinx.serialization 1.0正式版

我們很高興與你分享kotlinx.serialization這個多平臺序列化庫的1.0版。作為首個穩定版本，我們終於可以認為能用於生產了

無論你是透過Kotlin Multiplatform Mobile編寫Android應用，編寫服務端,還是透過Kotlin/JS構建Web前端，kotlinx.serialization都提供了簡潔且功能強大的純Kotlin API，可輕鬆將JSON解析為型別安全的Kotlin物件，反之亦然。為了慶祝該版本的釋出，我們想簡述一下kotlinx.serialization 1.0附帶的可用於生產的特性，並瞭解該庫與其他方案的區別。

在深入瞭解之前，我們想邀請你參加Kotlin 1.4線上活動，Leonid Startsev將詳細介紹以前，現在，以及kotlinx.serialization的未來。請不要錯過！

Register for the Kotlin 1.4 Online Event

首次使用kotlinx.serialization對Kotlin物件進行序列化和反序列化

一般而言，序列化是軟體專案中很常見的需求。移動應用或Web前端多透過API將JSON純文字解析為物件。而服務端和後端用於接受和響應JSON格式化過的請求。並且當你想儲存資料到硬碟時，使用JSON是一種易於人閱讀的流行格式。

如你所見，對Kotlin物件進行(反)序列化是你在專案中遲早都會遇到的過程。選擇kotlinx.serialization可使整個流程變得非常簡單：將庫新增到專案中後，要將基本的Kotlin物件解析為JSON形式非常簡單，透過@Serializable註解其類，並呼叫Json物件上提供的encodeToString和decodeFromString<T>擴充套件函式：

import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class User(val name: String, val yearOfBirth: Int)

fun main() {
   // Serialization (Kotlin object to JSON string)

   val data = User("Louis", 1901)
   val string = Json.encodeToString(data)
   println(string) // {"name":"Louis","yearOfBirth":1901}

   // Deserialization (JSON string to Kotlin object)

   val obj = Json.decodeFromString<User>(string)
   println(obj) // User(name=Louis, yearOfBirth=1901)
}

當然，kotlinx.serialization不是唯一可以用來序列化的庫。在JVM生態系統中，還有許多其他庫用於JSON。但是，最流行的不一定專為Kotlin而設計，而且可能根本不適用於Kotlin Multiplatform專案。除此之外，還有充足理由為你專案去擇kotlinx.serialization。

為何選擇Kotlinx.serialization?

kotlinx.serialization中包含的幾個特性和設計使它與其他庫區分開來，通常這會讓它的使用體驗更讓人著迷。讓我們仔細看看其中的一些配置。

Kotlin through and through

kotlinx.serialization不只是用純Kotlin編寫，而且還能在所有Kotlin Multiplatform目標(包括Kotlin/Native和Kotli /JS)上使用。它的序列化功能也是考慮到Kotlin的型別系統而構建的。無論你是嘗試使用預設的屬性初始值來序列化data class，單例object還是嘗試對通用的List<T>進行反序列化：kotlinx.serialization都會如期執行。最好看一下具體示例，它將一個複雜的專案物件(由data class所定義)列表轉換為其JSON表示，然後返回：

@Serializable
data class Project(
   val name: String,
   val owner: Account,
   val group: String = "R&D"
)

@Serializable
data class Account(val userName: String)

val moonshot = Project("Moonshot", Account("Jane"))
val cleanup = Project("Cleanup", Account("Mike"), "Maintenance")

fun main() {
   val string = Json.encodeToString(listOf(moonshot, cleanup))
   println(string)
   // [{"name":"Moonshot","owner":{"userName":"Jane"}},{"name":"Cleanup","owner":{"userName":"Mike"},"group":"Maintenance"}]

   val projectCollection = Json.decodeFromString<List<Project>>(string)
   println(projectCollection)
   // [Project(name=Moonshot, owner=Account(userName=Jane), group=R&D), Project(name=Cleanup, owner=Account(userName=Mike), group=Maintenance)]
}

如你所見，kotlinx.serialization仍然可以處理帶泛型集合的型別安全反序列化。儘管由於JVM上的集合會受型別擦除影響，這不是一個常規的操作。因此這種情況，其他庫會要求使用變通方案，例如使用type-tokens。但由於kotlinx.serialization使用編譯器外掛進行整合，所以它開箱即用的行為(可以在projectCollection示例中看到)已經是你所希望看到的——不需要依賴任何方案！

我們想保證，即便是應用未曾啟動過，你也能儘可能多地發現問題，所以kotlinx.serialization也致力於實現編譯時安全性。例如，在上面的示例中，如果未將Account類明確標記為@ Serializable，則會導致編譯時異常Account型別非可序列化，這很容易便能發現和修復該錯誤，避免釋出後崩潰。

多型序列化

kotlinx.serialization讓輕鬆且安全地處理序列化物件的繼承體系成為可能——這是傳統上敏感但非常需要的特性。因為該庫瞭解Kotlin獨特的型別系統，所以使用多型序列化的最直接方法是構建一個密封類的層次結構，其中所有子類都被明確標記為@Serializable。因為在編譯時就知道了密封類的層次結構，所以kotlinx.serialization外掛可以使用該資訊，並且子類及超類序列化的程式碼仍保持簡潔：

@Serializable
sealed class Message {
   abstract val content: String
}

@Serializable
data class BroadcastMessage(override val content: String) : Message()

@Serializable
data class DirectMessage(override val content: String, val recipient: String) : Message()

fun main() {
   val data: List<Message> = listOf(
       DirectMessage("Hey, Joe!", "Joe"),
       BroadcastMessage("Hey, all!")
   )
   val string = Json.encodeToString(data)
   println(string)
   // [{"type":"DirectMessage","content":"Hey, Joe!","recipient":"Joe"},{"type":"BroadcastMessage","content":"Hey, all!"}]

   val obj = Json.decodeFromString<List<Message>>(string)
   println(obj)
   // [DirectMessage(content=Hey, Joe!, recipient=Joe), BroadcastMessage(content=Hey, all!)]
}

從字串變數可以看到，kotlinx.serialization會智慧地新增type屬性到包含特定子型別的JSON物件中，這個行為完全自動。當你需要兼顧客戶端和伺服器時，這可以輕鬆地透過繼承關係來構造訊息，而無需手動推斷另一端的子型別。

密封類是在kotlinx.serialization中使用多型序列化的最便捷方法，並且已涵蓋了大量用例，同時該庫實際上還提供了超出這些封閉層次體系的功能。要了解相關功能的更多資訊，請檢視指南中有關多型的部分。

強大的可定製性

特別是在與外部系統和API通訊時，你可能無法完全控制所接收JSON訊息的準確格式。另一方面，你可能會覺得有必要調整kotlinx.serialization的輸出，以確保通訊的遠端能接受。

Kotlinx.serialization帶有豐富的DSL配置項，你可以透過它調整常規輸入及輸出的處理，修改general settings，例如啟用pretty-printing，lenient parsing或ignoring unknown keys。對於類和物件的特定配置，你可以透過註解來定義這些行為，例如重新命名欄位(@SerialName)或序列化時忽略(@Transient)。這些註解以及其他註解，也包含在指南中。如果你的用例有所需要，甚至還可以為特定型別的物件提供完全自定義的序列化。

這些功能的組合可以調整庫的行為，使其完全符合你對序列化的要求和格式的規範。

框架整合

無論專案中包含了什麼庫，你都可以使用kotlinx.serialization簡潔的介面，但許多框架還可透過直接整合使用kotlinx.serialization。以下是我們要強調的一些示例

• 如果你將** Ktor 作為服務端框架，可以透過提供的官方整合，將kotlinx.serialization與內容協商結合使用，從而可以直接針對傳入和傳出請求接收和響應Kotlin物件。而Kotlin Multiplatform專案中可用的Ktor-Clients**對應項也透過kotlinx.serialization提供了JSON有效負載處理。
• Spring MVC最近增加了對kotlinx.serialization的支援，並且SébastienDeleuze對Spring WebFlux提出了類似的整合。
• Http4k為kotlinx.serialization的HTTP訊息往返提供了優先的支援。
• Fuel提供了一個擴充套件包，讓Android HTTP客戶端能使用kotlinx.serialization。
• 如果你在使用MongoDB，則KMongo庫透過kotlinx.serialization提供物件對映。
• 如果你透過Retrofit 2將HTTP API轉換為Kotlin介面，則可以使用Jake Wharton的序列化轉換器和整合kotlinx.serialization。

直接與kotlinx.serialization整合的第三方專案越來越多，我們非常興奮——現在我們的庫已能用於生產，我們希望不久將來能看到更多類似的整合！

未來多格式支援

在1.0版中，與JSON相關的功能都是穩定且可用於生產的——但是kotlinx.serialization並不止步於此！除JSON外，團隊還打算相容HOCON，ProtoBuf，CBOR和Properties的序列化格式。儘管這些格式仍在設計和開發中，因此具有不同程度的穩定性和平臺相容性，但是你可以嘗試一下。它們作為單獨的工件使用，可以在指引中找到它們，以及對其格式狀態的簡短描述。

和開發團隊的正式格式一樣，還有許多由社群維護的格式，例如BSON，XML和YAML。但是請注意，這些格式是由社群成員建立且維護的。並且建立自定義格式仍然是一項實驗性功能，因此可能會做出重大更改，它們的維護者或許會收到延遲的更新。

現在，我們重點介紹了使kotlinx.serialization易於使用的許多特性，希望你能瞭然於心，為什麼要為當前(或下一個)專案選擇這個庫——這是一個快速的過程！

向你的專案新增kotlinx.serialization

要在你的專案中使用kotlinx.serialization，只需將編譯器外掛和執行時庫新增到專案中。在你的build.gradle(.kts)中，將以下項新增到plugin塊：

plugins {
   kotlin("plugin.serialization") version "1.4.0"
}

接下來，將執行時庫依賴項新增到build.gradle(.kts)檔案中的dependencies塊。如果你在Kotlin Multiplatform專案中工作，那麼可以將依賴項新增到common目標依賴模組中——所有平臺特定的依賴項將自動新增：

dependencies {
   implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0")
}

現在，你就可以開始使用kotlinx.serialization了！可以隨意嘗試該博文中包含的示例，嘗試自己的用例，或嘗試使用本指南的示例 。

深入 & 反饋

我們希望你能喜歡kotlinx.serialization的簡要概述！要獲取更多資訊，包括最新的安裝說明，請訪問其在GitHub上的主頁。請務必檢視kotlinx.serialization指引，包含庫的基本及高階特性的詳細資訊，並且涵蓋了本博文中提到的許多主題。如果你在使用該庫時遇到任何麻煩，可以在專案的問題跟蹤器或Kotlin Slack的#serialization頻道中尋求幫助。

欲瞭解幕後的獨家情況以及對序列化庫的更深入解釋，Leonid Startsev在Kotlin 1.4線上活動期間有關kotlinx.serialization演講，這也是一個再次邀請你參加的好時機——我們期待著在那兒見！

Register for the Kotlin 1.4 Online Event

如果你以前使用過kotlinx.serialization，請透過更新日誌和遷移指南來了解已更改的內容以及如何將專案升級到穩定版本。

感謝團隊

我們對提供反饋，提交PR，使用kotlinx.serialization 1.0之前的版本或以任何其他方式對庫做出貢獻的所有人說“謝謝”。你們的意見對於幫助團隊交付功能強大，易於使用且Kotlin優先的多平臺序列化庫非常有價值。在我們的第一個穩定版本釋出之前，你們報告的700多個問題，這些問題有助於解決bug和消除設計中的任何不足。在專案的持續發展過程中，希望你能不斷支援和反饋，幫助我們不斷改進和創新。所以：謝謝大家——享受絕佳的Kotlin！