Skip to content
Server Plugin

压缩

所需依赖项: io.ktor:ktor-server-compression

代码示例: compression

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持: ✖️

Ktor 提供了使用 Compression 插件压缩响应体和解压缩请求体的功能。

使用 Compression 插件,您可以:

  • 使用不同的压缩算法,包括 gzip、zstd 和 deflate。
  • 指定压缩数据所需的条件,例如内容类型或响应大小。
  • 根据特定的请求参数压缩数据。

请注意,Compression 插件目前不支持 SSE 响应。

要了解如何在 Ktor 中提供预压缩的静态文件,请参阅预压缩文件。

添加依赖项 ​

要使用 Compression,请将 ktor-server-compression 工件添加到构建脚本中:

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

要包含 Zstandard 压缩,请添加 ktor-server-compression-zstd 依赖项:

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

安装 Compression ​

要将 Compression 插件安装到应用程序中, 请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。 以下示例展示了如何安装 Compression:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类显式定义的 module() 扩展函数中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Compression)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(Compression)
    // ...
}

这将在服务器上启用 gzip、deflate 和 identity 编码器。

配置压缩设置 ​

你可以通过多种方式配置压缩:仅启用特定的编码器、指定其优先级、仅压缩特定的内容类型等等。

添加特定编码器 ​

要仅启用特定编码器,请调用相应的扩展函数,例如:

kotlin
install(Compression) {
    gzip()
    deflate()
    zstd()
}

你可以通过设置 priority 属性来为每个压缩算法指定优先级:

kotlin
install(Compression) {
    gzip {
        priority = 0.9
    }
    deflate {
        priority = 1.0
    }
    zstd {
        priority = 0.8
    }
}

在上述示例中,deflate 具有更高的优先级值,并且优先于 gzip 和 zstd。请注意,服务器首先会查看 Accept-Encoding 请求头中的品质 (quality) 值,然后再考虑指定的优先级。

配置内容类型 ​

默认情况下,Ktor 不会压缩特定的内容类型,例如 audio、video、image 以及 text/event-stream。你可以通过调用 matchContentType 来选择要压缩的内容类型,或者使用 excludeContentType 从压缩中排除所需的媒体类型。以下代码段展示了如何使用 gzip 压缩 JavaScript 代码,并使用 deflate 压缩所有文本子类型:

kotlin
install(Compression) {
    gzip {
        matchContentType(
            ContentType.Application.JavaScript
        )
    }
    deflate {
        matchContentType(
            ContentType.Text.Any
        )
    }
}

你可以在此处找到完整示例:compression。

配置响应大小 ​

Compression 插件允许你对大小未超过指定值的响应禁用压缩。为此,请将所需的值(以字节为单位)传递给 minimumSize 函数:

kotlin
    install(Compression) {
    deflate {
        minimumSize(1024)
    }
}

指定自定义条件 ​

如有必要,你可以使用 condition 函数提供自定义条件,并根据特定的请求参数压缩数据。以下代码段展示了如何针对指定的 URI 压缩请求:

kotlin
install(Compression) {
    gzip {
        condition {
            request.uri == "/orders"
        }
    }
}

HTTPS 安全性 ​

启用了压缩的 HTTPS 容易受到 BREACH 攻击。你可以使用多种方法来缓解此类攻击。例如,当 referrer 请求头指示为跨站请求时,可以禁用压缩。在 Ktor 中,可以通过检查 referrer 请求头的值来实现此操作:

kotlin
install(Compression) {
    gzip {
        condition {
            request.headers[HttpHeaders.Referrer]?.startsWith("https://my.domain/") == true
        }
    }
}

Zstandard 压缩级别 ​

你可以使用 level 参数配置 zstd 的压缩级别。默认压缩级别为 3,但你可以根据需要进行调整。

kotlin
install(Compression) {
    // 默认为 level = 3
    zstd(level = 20)
}

解压缩 ​

默认情况下,Compression 插件压缩服务器响应。要启用请求解压缩,请将 mode 属性设置为 CompressionConfig.Mode.DecompressRequest:

kotlin
install(Compression) { 
    mode = CompressionConfig.Mode.DecompressRequest
    gzip()
}

启用请求解压缩后,插件会在请求体被其他接收转换(例如反序列化和 multipart 处理)处理之前,使用配置的解码器解压缩请求体。

实现自定义编码器 ​

如有必要,你可以通过实现 ContentEncoder 接口来提供自己的编码器。 有关实现的示例,请参阅 GzipEncoder。