Server Plugin

CORS

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

程式碼範例： cors

Native 伺服器

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

支援：✅

如果您的伺服器需要處理跨來源請求， 您需要安裝並設定 CORS Ktor 外掛程式。此外掛程式可讓您設定允許的主機、HTTP 方法、用戶端設定的標頭等。

新增相依性

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

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 CORS

要在應用程式中安裝 CORS 外掛程式， 請將其傳遞給指定

模組

Modules allow you to structure your application by grouping routes.

中的 install 函式。 以下程式碼片段顯示如何安裝 CORS ...

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

embeddedServermodule

CORS 外掛程式也可以安裝到特定路由。 如果您需要為不同的應用程式資源使用不同的 CORS 配置，這會很有用。

如果您將 CORS 外掛程式安裝到特定路由，則需要為該路由新增 options 處理常式。這可讓 Ktor 正確回應 CORS 預檢請求。

設定 CORS

CORS 特定的設定是由 CORSConfig 類別公開的。讓我們看看如何進行這些設定。

概覽

假設您有一個監聽 8080 埠號的伺服器，其 /customer 路由會以 JSON 資料進行回應。以下程式碼片段顯示了使用 Fetch API 從在另一個埠號上運作的用戶端發出的範例請求，這使該請求成為跨來源請求：

function saveCustomer() {
    fetch('http://0.0.0.0:8080/customer',
        {
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            method: "POST",
            body: JSON.stringify({id: 3, firstName: "Jet", lastName: "Brains"})
        })
        .then(response => response.text())
        .then(data => {
            console.log('Success:', data);
            alert(data);
        })
        .catch((error) => {
            console.error('Error:', error);
        });
}

為了在後端允許此類請求，您需要按照以下方式設定 CORS 外掛程式：

install(CORS) {
    allowHost("0.0.0.0:8081")
    allowHeader(HttpHeaders.ContentType)
}

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

主機

要指定可以發出跨來源請求的允許主機，請使用 allowHost 函式。除了主機名稱外， 您還可以指定埠號、子網域列表或支援的 HTTP 協定 (schemes)。

install(CORS) {
    allowHost("client-host")
    allowHost("client-host:8081")
    allowHost("client-host", subDomains = listOf("en", "de", "es"))
    allowHost("client-host", schemes = listOf("http", "https"))
}

要允許來自任何主機的跨來源請求，請使用 anyHost 函式。

install(CORS) {
    anyHost()
}

HTTP 方法

預設情況下，CORS 外掛程式允許 GET、POST 和 HEAD HTTP 方法。要新增其他方法，請使用 allowMethod 函式。

install(CORS) {
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Put)
    allowMethod(HttpMethod.Patch)
    allowMethod(HttpMethod.Delete)
}

允許標頭

預設情況下，CORS 外掛程式允許以下由 Access-Control-Allow-Headers 管理的用戶端標頭：

• Accept
• Accept-Language
• Content-Language

要允許額外的標頭，請使用 allowHeader 函式。

install(CORS) {
    allowHeader(HttpHeaders.ContentType)
    allowHeader(HttpHeaders.Authorization)
}

要允許自訂標頭，請使用 allowHeaders 或 allowHeadersPrefixed 函式。例如，以下程式碼片段 顯示如何允許以 custom- 為前綴的標頭。

install(CORS) {
    allowHeadersPrefixed("custom-")
}

請注意，對於非簡單內容類型，allowHeaders 或 allowHeadersPrefixed 需要將 allowNonSimpleContentTypes 屬性設定為 true。

公開標頭

Access-Control-Expose-Headers 標頭會將指定的標頭新增至瀏覽器中 JavaScript 可以存取的允許清單中。 要設定此類標頭，請使用 exposeHeader 函式。

install(CORS) {
    // ...
    exposeHeader("X-My-Custom-Header")
    exposeHeader("X-Another-Custom-Header")
}

憑據

預設情況下，瀏覽器不會隨跨來源請求發送憑據資訊（例如 Cookie 或驗證資訊）。要允許傳遞此資訊，請使用 allowCredentials 屬性將 Access-Control-Allow-Credentials 回應標頭設定為 true。

install(CORS) {
    allowCredentials = true
}

其他

CORS 外掛程式還允許您指定其他 CORS 相關設定。例如，您可以 使用 maxAgeInSeconds 來指定預檢請求的回應可以快取多長時間，而無需發送另一個預檢請求。

install(CORS) {
    maxAgeInSeconds = 3600
}

您可以從 CORSConfig 了解其他配置選項。