Server Plugin

CORS

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

代码示例: cors

原生服务器

Ktor 支持 Kotlin/Native 并允许你在没有额外运行时或虚拟机的情况下运行服务器。

支持: ✅

如果你的服务器需要处理跨域请求，则需要安装并配置 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 中了解其他配置选项。