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 构件添加到构建脚本中:
implementation(ktorLibs.client.contentNegotiation)implementation ktorLibs.client.contentNegotiation<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 会根据包含的构件自动选择默认序列化器。如有需要,你可以显式指定序列化器并对其进行配置。
序列化
在使用 kotlinx.serialization 转换器之前,请按照 Setup 小节中的说明添加 Kotlin 序列化插件。
JSON
要序列化和反序列化 JSON 数据,请向项目添加序列化库。Ktor 支持 kotlinx.serialization、Gson 或 Jackson。
在构建脚本中添加 ktor-serialization-kotlinx-json 构件:
implementation(ktorLibs.serialization.kotlinx.json)implementation ktorLibs.serialization.kotlinx.json<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>在构建脚本中添加 ktor-serialization-gson 构件:
implementation(ktorLibs.serialization.gson)implementation ktorLibs.serialization.gson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-gson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>在构建脚本中添加 ktor-serialization-jackson 构件:
implementation(ktorLibs.serialization.jackson)implementation ktorLibs.serialization.jackson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-jackson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>XML
要序列化和反序列化 XML,请在构建脚本中添加 ktor-serialization-kotlinx-xml 构件:
implementation(ktorLibs.serialization.kotlinx.xml)implementation ktorLibs.serialization.kotlinx.xml<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CBOR
要序列化和反序列化 CBOR,请在构建脚本中添加 ktor-serialization-kotlinx-cbor 构件:
implementation(ktorLibs.serialization.kotlinx.cbor)implementation ktorLibs.serialization.kotlinx.cbor<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ProtoBuf
要序列化和反序列化 ProtoBuf,请在构建脚本中添加 ktor-serialization-kotlinx-protobuf 构件:
implementation(ktorLibs.serialization.kotlinx.protobuf)implementation ktorLibs.serialization.kotlinx.protobuf<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安装 ContentNegotiation
要安装 ContentNegotiation 插件,请在客户端配置块中将其传递给 install 函数:
val client = HttpClient(CIO) {
install(ContentNegotiation)
}然后,你可以配置所需的 JSON 序列化器。
配置序列化器
JSON 序列化器
要在应用程序中注册 JSON 序列化器,请调用 json() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json()
}
}要自定义 JSON 序列化,请在 json() 构造函数中传入 Json 配置:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
}有关可用的配置选项,请参阅 JsonBuilder。
有关完整示例,请参阅 client-json-kotlinx。
要在应用程序中注册 Gson 序列化器,请调用 gson() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
gson()
}
}要自定义 Gson 序列化,请向 gson() 函数传递一个配置块。有关可用的配置选项,请参阅 GsonBuilder。
要在应用程序中注册 Jackson 序列化器,请调用 jackson() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
jackson()
}
}要自定义 Jackson 序列化,请使用 ObjectMapper 提供的设置:
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() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
xml()
}
}要自定义 XML 序列化,请向 xml() 函数传递所需的选项:
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() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
cbor()
}
}要自定义 CBOR 序列化,请在 cbor() 构造函数中传入 Cbor 配置:
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() 函数:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf()
}
}要自定义 ProtoBuf 序列化,请向 protobuf() 函数传递 ProtoBuf 配置:
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:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
register(ContentType.Application.Json, noOpJsonConverter)
acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
}
}使用 SkipIfPresent 时,插件会保留现有的 Accept 标头。如果请求不包含 Accept 标头,插件将照常添加已注册的内容类型。
发送和接收数据
创建数据类
以下示例使用 Customer 数据类来表示客户端发送和接收的数据:
data class Customer(val id: Int, val firstName: String, val lastName: String)如果你使用的是 kotlinx.serialization,请使用 @Serializable 为该类添加注解:
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)kotlinx.serialization 库支持对以下类型进行序列化/反序列化:
发送数据
要在请求体中发送类实例,请使用 setBody() 函数传入该实例,并使用 contentType() 函数设置内容类型。
以下示例将 Customer 对象作为 JSON 发送:
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() 函数:
val customer: Customer = client.get("http://localhost:8080/customer/3").body()有关完整示例,请参阅 client-json-kotlinx。
