Skip to content
Client Plugin

Ktor Client 中的内容协商与序列化

所需依赖项:io.ktor:ktor-client-content-negotiation

代码示例: client-json-kotlinx

ContentNegotiation 插件主要有两个用途:

  • 使用 Accept 和 Content-Type 标头在客户端与服务器之间协商媒体类型。
  • 以支持的格式序列化请求体并反序列化响应体。Ktor 提供了对 JSON、XML、CBOR 和 ProtoBuf 的内置支持。

在服务器端,Ktor 提供了用于序列化和反序列化内容的 ContentNegotiation 插件。

添加依赖项 ​

内容协商 ​

要使用 ContentNegotiation,请将 ktor-client-content-negotiation 构件添加到构建脚本中:

kotlin
implementation(ktorLibs.client.contentNegotiation)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.client.contentNegotiation
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-content-negotiation-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

针对特定格式的序列化器需要额外的构件。

例如,kotlinx.serialization 处理 JSON 时需要 ktor-serialization-kotlinx-json 依赖项。Ktor 会根据包含的构件自动选择默认序列化器。如有需要,你可以显式指定序列化器并对其进行配置。

要详细了解 Ktor 客户端所需的构件,请参阅 添加客户端依赖项了解如何向现有项目添加客户端依赖项。。

序列化 ​

在使用 kotlinx.serialization 转换器之前,请按照 Setup 小节中的说明添加 Kotlin 序列化插件。

JSON ​

要序列化和反序列化 JSON 数据,请向项目添加序列化库。Ktor 支持 kotlinx.serialization、Gson 或 Jackson。

在构建脚本中添加 ktor-serialization-kotlinx-json 构件:

kotlin
implementation(ktorLibs.serialization.kotlinx.json)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.json
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

在构建脚本中添加 ktor-serialization-gson 构件:

kotlin
implementation(ktorLibs.serialization.gson)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.gson
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-gson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

在构建脚本中添加 ktor-serialization-jackson 构件:

kotlin
implementation(ktorLibs.serialization.jackson)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.jackson
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-jackson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

XML ​

要序列化和反序列化 XML,请在构建脚本中添加 ktor-serialization-kotlinx-xml 构件:

kotlin
implementation(ktorLibs.serialization.kotlinx.xml)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.xml
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CBOR ​

要序列化和反序列化 CBOR,请在构建脚本中添加 ktor-serialization-kotlinx-cbor 构件:

kotlin
implementation(ktorLibs.serialization.kotlinx.cbor)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.cbor
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ProtoBuf ​

要序列化和反序列化 ProtoBuf,请在构建脚本中添加 ktor-serialization-kotlinx-protobuf 构件:

kotlin
implementation(ktorLibs.serialization.kotlinx.protobuf)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.protobuf
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安装 ContentNegotiation ​

要安装 ContentNegotiation 插件,请在客户端配置块中将其传递给 install 函数:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation)
}

然后,你可以配置所需的 JSON 序列化器。

配置序列化器 ​

JSON 序列化器 ​

要在应用程序中注册 JSON 序列化器,请调用 json() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json()
    }
}

要自定义 JSON 序列化,请在 json() 构造函数中传入 Json 配置:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })
    }
}

有关可用的配置选项,请参阅 JsonBuilder。

有关完整示例,请参阅 client-json-kotlinx。

要在应用程序中注册 Gson 序列化器,请调用 gson() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        gson()
    }
}

要自定义 Gson 序列化,请向 gson() 函数传递一个配置块。有关可用的配置选项,请参阅 GsonBuilder。

要在应用程序中注册 Jackson 序列化器,请调用 jackson() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson()
    }
}

要自定义 Jackson 序列化,请使用 ObjectMapper 提供的设置:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
import com.fasterxml.jackson.databind.*
import java.text.DateFormat

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson {
            enable(SerializationFeature.INDENT_OUTPUT)
            dateFormat = DateFormat.getDateInstance()
        }
    }
}

XML 序列化器 ​

要在应用程序中注册 XML 序列化器,请调用 xml() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml()
    }
}

要自定义 XML 序列化,请向 xml() 函数传递所需的选项:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
import nl.adaptivity.xmlutil.*
import nl.adaptivity.xmlutil.serialization.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml(format = XML {
            xmlDeclMode = XmlDeclMode.Charset
        })
    }
}

CBOR 序列化器 ​

要在应用程序中注册 CBOR 序列化器,请调用 cbor() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor()
    }
}

要自定义 CBOR 序列化,请在 cbor() 构造函数中传入 Cbor 配置:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
import kotlinx.serialization.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor(Cbor {
            ignoreUnknownKeys = true
        })
    }
}

有关可用的配置选项,请参阅 CborBuilder。

ProtoBuf 序列化器 ​

要在应用程序中注册 ProtoBuf 序列化器,请调用 protobuf() 函数:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf()
    }
}

要自定义 ProtoBuf 序列化,请向 protobuf() 函数传递 ProtoBuf 配置:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
import kotlinx.serialization.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf(ProtoBuf {
            encodeDefaults = true
        })
    }
}

有关可用选项,请参阅 ProtoBufBuilder。

配置 Accept 标头 ​

默认情况下,ContentNegotiation 插件会将已注册的内容类型添加到传出请求的 Accept 标头中。

如果你显式设置了 Accept 标头,并且不希望插件添加已注册的内容类型,请将 acceptHeaderMergeStrategy 属性设置为 ContentTypeMergeStrategy.SkipIfPresent:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        register(ContentType.Application.Json, noOpJsonConverter)
        acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
    }
}

使用 SkipIfPresent 时,插件会保留现有的 Accept 标头。如果请求不包含 Accept 标头,插件将照常添加已注册的内容类型。

发送和接收数据 ​

创建数据类 ​

以下示例使用 Customer 数据类来表示客户端发送和接收的数据:

kotlin
data class Customer(val id: Int, val firstName: String, val lastName: String)

如果你使用的是 kotlinx.serialization,请使用 @Serializable 为该类添加注解:

kotlin
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

kotlinx.serialization 库支持对以下类型进行序列化/反序列化:

发送数据 ​

要在请求体中发送类实例,请使用 setBody() 函数传入该实例,并使用 contentType() 函数设置内容类型。

以下示例将 Customer 对象作为 JSON 发送:

kotlin
val response: HttpResponse = client.post("http://localhost:8080/customer") {
    contentType(ContentType.Application.Json)
    setBody(Customer(3, "Jet", "Brains"))
}

ContentNegotiation 插件会使用配置的序列化器将请求体转换为指定格式。

要以其他已注册的格式发送数据,请指定相应的内容类型,例如 ContentType.Application.Xml 或 ContentType.Application.Cbor。

接收数据 ​

当服务器返回具有受支持内容类型的响应时,ContentNegotiation 插件可以将响应体反序列化为预期类型。

例如,要将 JSON 响应反序列化为 Customer 对象,请调用 body() 函数:

kotlin
val customer: Customer = client.get("http://localhost:8080/customer/3").body()

有关完整示例,请参阅 client-json-kotlinx。