Server Plugin

压缩

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

代码示例: compression

原生服务器

Ktor 支持 Kotlin/Native，允许您无需额外运行时或虚拟机即可运行服务器。

支持: ✖️

Ktor 提供了通过使用 Compression plugin 来压缩响应体和解压缩请求体的能力。 您可以使用不同的压缩算法，包括 gzip 和 deflate，指定压缩数据所需的条件（例如内容类型或响应大小），甚至可以根据特定的请求参数来压缩数据。

请注意，Compression plugin 当前不支持 SSE 响应。

关于如何在 Ktor 中提供预压缩的静态文件，请参见 预压缩文件。

添加依赖项

要使用 Compression，您需要在构建脚本中包含 ktor-server-compression 构件：

Gradle (Kotlin)Gradle (Groovy)Maven

安装 Compression

要将 Compression plugin 安装到应用程序， 请将其传递给指定

模块

模块允许您通过分组路由来组织应用程序。

中的 install 函数。 以下代码片段展示了如何安装 Compression ...

• ... 在 embeddedServer 函数调用内部。
• ... 在显式定义的 module 内部，它是 Application 类的扩展函数。

embeddedServermodule

这会在服务器上启用 gzip、deflate 和 identity 编码器。 在下一章中，我们将了解如何仅启用特定的编码器并配置压缩数据的条件。 请注意，每个添加的编码器都将在需要时用于解压缩请求体。

配置压缩设置

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

添加特定编码器

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

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

您可以通过设置 priority 属性来指定每个压缩算法的优先级：

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

在上面的示例中，deflate 具有更高的优先级值并优先于 gzip。请注意，服务器首先查看 Accept-Encoding header 中 质量值 ，然后考虑指定的优先级。

配置内容类型

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

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

您可以在此处找到完整示例：compression。

配置响应大小

Compression plugin 允许您对大小不超过指定值的响应禁用压缩。为此，请将所需值（以字节为单位）传递给 minimumSize 函数：

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

指定自定义条件

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

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

HTTPS 安全

启用了压缩的 HTTPS 容易受到 BREACH 攻击。您可以使用各种方法来缓解此攻击。例如，当 referrer header 指示跨站请求时，您可以禁用压缩。在 Ktor 中，这可以通过检测 referrer header 值来完成：

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

实现自定义编码器

如有必要，您可以通过实现 ContentEncoder interface 来提供自己的编码器。 有关实现的示例，请参见 GzipEncoder。