Skip to content
Client Plugin

内容编码

所需依赖项:io.ktor:ktor-client-encoding

代码示例: client-content-encoding

Ktor 客户端提供了 ContentEncoding 插件,允许你启用指定的压缩算法(例如 gzip 和 deflate)并配置其设置。

该插件提供以下功能:

  • 设置带有指定品质值的 Accept-Encoding 请求头。
  • 可选地对请求体进行编码。
  • 解码从服务器接收到的内容以获取原始有效负载。

添加依赖项 ​

要使用 ContentEncoding,请将 ktor-client-encoding 构件添加到你的构建脚本中:

kotlin
implementation(ktorLibs.client.encoding)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.client.encoding
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-encoding-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
要详细了解 Ktor 客户端所需的构件,请参阅添加客户端依赖项了解如何向现有项目添加客户端依赖项。。

安装 ContentEncoding ​

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

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.compression.*
//...
val client = HttpClient(CIO) {
    install(ContentEncoding)
}

配置 ContentEncoding ​

启用编码器 ​

你可以配置支持哪些编码器,并指定它们的品质值(用于 Accept-Encoding 请求头中)。

下面的示例启用了带有自定义品质值的 deflate 和 gzip 编码器:

kotlin
val client = HttpClient(CIO) {
    install(ContentEncoding) {
        deflate(1.0F)
        gzip(0.9F)
    }
}

如有必要,你可以实现 ContentEncoder 接口以创建自定义编码器,并使用 customEncoder() 函数进行注册。

设置 mode 属性 ​

默认情况下,ContentEncoding 仅处理响应解压缩。你可以使用 mode 属性来定义插件的工作方式。

可用值如下:

ContentEncodingConfig.Mode.DecompressResponse
仅解压缩响应。这是默认模式。
ContentEncodingConfig.Mode.CompressRequest
仅启用请求体压缩。
ContentEncodingConfig.Mode.All
同时启用响应解压缩与请求压缩。

编码请求体 ​

要启用请求压缩,请设置 mode 属性并在 HttpRequestBuilder 块中使用 compress() 函数:

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.compression.*
//...
val client = HttpClient(CIO) {
    install(ContentEncoding) {
        mode = ContentEncodingConfig.Mode.CompressRequest
        gzip()
    }
}
client.post("/upload") {
    compress("gzip")
    setBody(someLongBody)
}

在此示例中:

  • mode = ContentEncodingConfig.Mode.CompressRequest 启用了请求压缩。
  • gzip() 注册了 gzip 编码器。
  • compress("gzip") 对该特定请求应用 gzip 压缩。
  • Content-Encoding 请求头会自动添加。

有关处理响应的更多详情,请参阅接收响应。