Server Plugin

壓縮

所需依賴項：io.ktor:ktor-server-compression

程式碼範例： compression

原生伺服器

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

支援：✖️

Ktor 提供了使用 Compression 外掛程式壓縮回應主體和解壓縮請求主體的能力。 您可以使用不同的壓縮演算法，包括 gzip 和 deflate，指定壓縮資料所需的條件（例如內容類型或回應大小），甚至可以根據特定的請求參數壓縮資料。

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

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

新增依賴項

若要使用 Compression，您需要在建置腳本中包含 ktor-server-compression artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 Compression

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

模組

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

中的 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 標頭中的 品質 值，然後再考慮指定的優先級。

設定內容類型

預設情況下，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
        }
    }
}

實作自訂編碼器

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