Server Plugin

壓縮

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

程式碼範例： compression

原生伺服器

Ktor 支援 Kotlin/Native，並允許您在沒有額外執行階段或虛擬機的情況下執行伺服器。

支援：✖️

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

透過 Compression 外掛程式，您可以：

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

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

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

新增相依性

要使用 Compression，您需要在組建指令碼中包含 ktor-server-compression 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

若要包含 Zstandard 壓縮，請新增 ktor-server-compression-zstd 相依性：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 Compression

要將 Compression 外掛程式安裝到應用程式，請將其傳遞給指定

模組

模組允許您透過分組路由來組織應用程式結構。

中的 install 函式。 下方的程式碼片段展示了如何安裝 Compression ...

• ... 在 embeddedServer 函式呼叫內。
• ... 在明確定義的 module 內，該模組是 Application 類別的擴充函式。

embeddedServermodule

這會在伺服器上啟用 gzip、deflate 與 identity 編碼器。 在下一章中，我們將了解如何僅啟用特定的編碼器並設定壓縮資料的條件。 請注意，如有需要，每個新增的編碼器都將用於解壓縮請求主體。

設定壓縮設定

您可以透過多種方式設定壓縮：僅啟用特定編碼器、指定其優先級、僅壓縮特定內容類型等。

新增特定編碼器

要僅啟用特定的編碼器，請呼叫對應的擴充函式，例如：

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

您可以透過設定 priority 屬性來指定每個壓縮演算法的優先級：

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 壓縮所有文字子類型：

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

您可以在此處找到完整的範例：compression。

設定回應大小

Compression 外掛程式允許您對大小不超過指定值的請求停用壓縮。要執行此操作，請將所需的值（以位元組為單位）傳遞給 minimumSize 函式：

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

指定自訂條件

如有必要，您可以使用 condition 函式提供自訂條件，並根據特定的請求參數壓縮資料。下方的程式碼片段展示了如何針對指定的 URI 壓縮請求：

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

HTTPS 安全性

啟用了壓縮的 HTTPS 容易受到 BREACH 攻擊。您可以使用多種方式來緩解此攻擊。例如，當 referrer 標頭指示跨站點請求時，您可以停用壓縮。在 Ktor 中，這可以透過檢查 referrer 標頭值來達成：

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

Zstandard 壓縮級別

您可以使用 level 參數設定 zstd 的壓縮級別。預設壓縮級別為 3，但您可以根據需求進行調整。

install(Compression) {
    // 預設為 level = 3
    zstd(level = 20)
}

實作自訂編碼器

如有必要，您透過實作 ContentEncoder 介面來提供自己的編碼器。 請參閱 GzipEncoder 作為實作範例。