Server Plugin

CORS

所需依賴: io.ktor:ktor-server-cors

程式碼範例: cors

原生伺服器

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

支援: ✅

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

添加依賴

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

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 CORS

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

模組

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

中的 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 方案。

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 了解其他配置選項。