CORS
必要相依性:io.ktor:ktor-server-cors
程式碼範例: cors
原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅
如果你的伺服器需要處理跨來源請求 (cross-origin requests), 則需要安裝並設定 CORS Ktor 外掛程式。此外掛程式允許你設定允許的主機、HTTP 方法、用戶端設定的標頭等。
新增相依性
若要使用 CORS,請將 ktor-server-cors 構件新增至你的建置指令碼:
implementation(ktorLibs.server.cors)implementation ktorLibs.server.cors<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-cors-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝 CORS
若要將 CORS 外掛程式安裝至你的應用程式中, 請在指定的 模組模組可讓您透過對路由進行分組來建構應用程式。 中將其傳遞給 install 函式。 以下範例展示如何安裝 CORS:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(CORS)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
// ...
fun Application.module() {
install(CORS)
// ...
}CORS 外掛程式也可以安裝至特定路由。 如果你需要針對不同的應用程式資源使用不同的 CORS 設定,這會很有用。
如果你將 CORS 外掛程式安裝至特定路由,則需要為該路由新增 options 處理常式。這能讓 Ktor 正確回應 CORS 預檢請求 (preflight request)。
設定 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 scheme。
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 管理的下列用戶端標頭:
AcceptAccept-LanguageContent-Language
若要允許其他標頭,請使用 allowHeader 函式。
install(CORS) {
allowHeader(HttpHeaders.ContentType)
allowHeader(HttpHeaders.Authorization)
}若要允許自訂標頭,請使用 allowHeaders 或 allowHeadersPrefixed 函式。例如,以下程式碼片段 展示了如何允許以 custom- 為前綴的標頭。
install(CORS) {
allowHeadersPrefixed("custom-")
}請注意,對於非簡單內容類型 (non-simple content types),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 進一步了解其他設定選項。
