Skip to content
Experimental

使用 I/O 源序列化 JSON

Kotlin 序列化提供了用于处理 JVM 流以及 kotlinx-io 或 Okio 的 Source 与 Sink 的 API。

你可以使用这些 API 直接从 I/O 源序列化和反序列化 JSON,而无需创建中间字符串。 这些 API 使用 UTF-8 编码,当遇到无效的 JSON 数据时会抛出 SerializationException,发生 I/O 故障时会抛出 IOException。

在处理 I/O 资源时,正确关闭它们以防止资源泄漏非常重要。 你可以使用 .use() 函数来完成此操作,该函数会在操作完成时自动关闭资源。

将 JSON 序列化到 JVM 输出流 ​

使用 .encodeToStream() 扩展函数直接将 JSON 序列化到 JVM OutputStream:

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileOutputStream

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

fun main() {
    val project = Project("kotlinx.serialization", 9000)
    
    // 为 project.json 文件创建 OutputStream
    FileOutputStream("project.json").use { output ->
        
        // 将 project 实例序列化到 OutputStream 中
        Json.encodeToStream(project, output)
    }
}

在此示例中,Project 的 JSON 表示形式被序列化到 project.json 文件中。

从 JVM 输入流反序列化 JSON ​

要直接从 JVM InputStream 反序列化 JSON,请使用 .decodeFromStream() 扩展函数:

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileInputStream

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

fun main() {
    // 打开一个 InputStream
    FileInputStream("project.json").use { input ->

        // 将 InputStream 中的 JSON 内容反序列化为 Project 实例
        val project = Json.decodeFromStream<Project>(input)

        // 打印反序列化后的 Project 实例
        println(project)
    }
}

在此示例中,输入流中的 JSON 内容被反序列化为单个 Project 实例。

如果你的输入在顶层 JSON 数组中包含多个 JSON 对象,或者包含以空格分隔的对象,你可以使用 .decodeToSequence() 延迟处理这些元素。 这使你可以在解析每个值时对其进行处理,例如:

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileInputStream

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

fun main() {
    // 为包含 Project 对象 JSON 数组的 projects.json 文件打开一个 InputStream
    FileInputStream("projects.json").use { input ->

        // 从 InputStream 延迟反序列化每个 Project
        val projects = Json.decodeToSequence<Project>(input)

        // 逐个处理元素
        for (project in projects) {
            println(project)
        }
    }
}

由 .decodeToSequence() 返回的序列只能遍历一次,因为它们与底层流相关联。

在序列完全求值之前如果其底层流已关闭,访问该序列可能会导致异常。

使用 kotlinx-io 和 Okio 进行 JSON 序列化 ​

除了 JVM 流之外,你还可以使用 I/O 类型来处理 JSON,例如来自 kotlinx-io 库(目前处于 Alpha 阶段)的 kotlinx.io.Sink 和 kotlinx.io.Source,以及来自 Okio 库的 okio.BufferedSink 和 okio.BufferedSource。

你可以使用以下 Json 扩展函数通过这些 I/O 类型直接读写 JSON:

接下来的部分介绍了结合这些 API 使用 kotlinx-io 类型的示例。
你可以类似地将 Okio 类型与其对应的 okio.BufferedSink 和 okio.BufferedSource API 配合使用。

为 kotlinx-io 和 Okio 添加依赖项 ​

要将这些扩展函数与 kotlinx-io 或 Okio 类型一起使用,请添加相应的依赖项:

为 kotlinx-io 添加依赖项 ​

kotlin
// build.gradle(.kts)
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-io:1.11.0")
    implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.9.1")
}
xml
<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json-io</artifactId>
        <version>1.11.0</version>
    </dependency>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-io-core</artifactId>
        <version>0.9.1</version>
    </dependency>
</dependencies>

为 Okio 添加依赖项 ​

kotlin
// build.gradle(.kts)
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-okio:1.11.0")
    implementation("com.squareup.okio:okio:3.16.2")
}
xml
<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json-okio</artifactId>
        <version>1.11.0</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.okio</groupId>
        <artifactId>okio</artifactId>
        <version>3.16.2</version>
    </dependency>
</dependencies>

将 JSON 序列化到 Sink ​

要将 JSON 序列化到 Sink,请使用 .encodeToSink() 函数:

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 导入 kotlinx-io 类型与 JSON I/O 支持的声明
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*

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

@OptIn(ExperimentalSerializationApi::class)
fun main() {
    val project = Project("kotlinx.serialization", 9000)

    // 为 project.json 文件创建 Sink
    val path = Path("project.json")
    SystemFileSystem.sink(path).buffered().use { sink: Sink ->

        // 将 Project 实例直接序列化到 Sink 中
        Json.encodeToSink(project, sink)
    }
}

从 Source 反序列化 JSON ​

要从 Source 反序列化 JSON,请使用 .decodeFromSource() 函数:

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 导入 kotlinx-io 类型与 JSON I/O 支持的声明
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*

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

@OptIn(ExperimentalSerializationApi::class)
fun main() {
    // 为 project.json 文件打开一个 Source
    val path = Path("project.json")
    SystemFileSystem.source(path).buffered().use { source: Source ->

        // 直接从 Source 反序列化 Project 实例
        val project = Json.decodeFromSource<Project>(source)

        println(project)
    }
}

如果你的输入包含大型 JSON 数组或多个顶层 JSON 对象, 你可以使用 .decodeSourceToSequence() 函数将 Source 转换为延迟解码的 Sequence<T>。

kotlin
// 从序列化库导入声明
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// 导入 kotlinx-io 类型与 JSON I/O 支持的声明
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*

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

@OptIn(ExperimentalSerializationApi::class)
fun main() {
    // 为包含多个 JSON 对象的 projects.json 文件打开一个 Source
    val path = Path("projects.json")
    SystemFileSystem.source(path).buffered().use { source: Source ->

        // 从 Source 读取时延迟反序列化每个 Project
        val projects: Sequence<Project> = Json.decodeSourceToSequence(source)

        for (project in projects) {
            println(project)
        }
    }
}

由 .decodeSourceToSequence() 返回的序列只能遍历一次,因为它们与底层 Source 相关联。

在序列完全求值之前如果其底层 source 已关闭,访问该序列可能会导致异常。

下一步 ​