Skip to content
Server Plugin

壓縮 (Compression)

必要相依性: io.ktor:ktor-server-compression

程式碼範例: compression

Native 伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。支援: ✖️

Ktor 透過 Compression 外掛程式提供壓縮回應主體與解壓縮請求主體的功能。

透過 Compression 外掛程式,你可以:

  • 使用不同的壓縮演算法,包含 gzip、zstd 和 deflate。
  • 指定壓縮資料所需的條件,例如內容類型或回應大小。
  • 根據特定請求參數壓縮資料。

請注意,Compression 外掛程式目前不支援 SSE 回應。

若要了解如何在 Ktor 中提供預先壓縮的靜態檔案,請參閱預先壓縮檔案。

新增相依性 ​

若要使用 Compression,請將 ktor-server-compression 產物新增至你的組建指令碼中:

kotlin
implementation(ktorLibs.server.compression)
上述程式碼片段使用 Ktor 版本目錄 (Version Catalog) 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.compression
上述程式碼片段使用 Ktor 版本目錄 (Version Catalog) 來指定 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 版本目錄 (Version Catalog) 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.compression.zstd
上述程式碼片段使用 Ktor 版本目錄 (Version Catalog) 來指定 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。