Server Plugin

CORS

所需依赖项：io.ktor:ktor-server-cors

代码示例： cors

原生服务器

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

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 了解有关其他配置选项的信息。