Ktor 3.6.0 新功能
Ktor 3.6.0 在伺服器與用戶端方面帶來了一系列改進。此功能版本的主要亮點包括:
- Netty 伺服器引擎中實驗性的 HTTP/3 支援
- Kotlin Multiplatform 的預設用戶端引擎
- 實驗性的具型別身分驗證支援
- 實驗性的 OpenID Connect 外掛程式
- JVM 上的 WebRTC 用戶端支援
Ktor 伺服器
請求參數的額外型別支援
Ktor 3.6.0 擴充了將請求參數轉換為具型別值時預設支援的型別組合。
現已支援以下型別:
Bytejava.lang.ByteUByteUIntUShortULongUuid
例如,你可以透過屬性委託直接在路由處理常式中取得 Uuid 參數:
get {
val uuid: Uuid by call.parameters
}預壓縮靜態檔案支援 Zstandard (zstd) 與 DEFLATE
Ktor 現在可以提供 Zstandard (zstd) 與 DEFLATE 格式的預壓縮靜態內容。
若要啟用新格式,請在 preCompressed() 函式中使用 CompressedFileType.ZSTD 與 CompressedFileType.DEFLATE 列舉常數:
staticResources("staticResources", "public") {
preCompressed(
CompressedFileType.ZSTD,
CompressedFileType.DEFLATE
)
}OpenAPI 標籤描述
現在可以直接在 openAPI {} 和 swaggerUI {} 設定區塊中為 OpenAPI 標籤定義描述:
swaggerUI("/swagger") {
info = OpenApiInfo("Books API from routes", "1.0.0")
tag(
name = "Books",
description = "Operations on books"
)
}標籤描述會新增至產生的 OpenAPI 文件的頂層元資料中。
新的 ApplicationCall.respondHtmlPartial() 函式
新的 .respondHtmlPartial() 函式取代了 .respondHtmlFragment(),用於回應部分 HTML 內容。
它使用 TagConsumer<Appendable> 作為 Lambda 接收者,讓你可以傳回不受限制的 HTML 內容,例如表格儲存格:
call.respondHtmlPartial(HttpStatusCode.Created) {
td { +"Created!" }
}已棄用的 .respondHtmlFragment() 函式使用 FlowContent,限制了可傳回的 HTML 元素。現在已棄用並建議改用 .respondHtmlPartial()。
Netty
HTTP/3 支援
Netty 伺服器引擎現在包含對基於 QUIC 的 HTTP/3 的實驗性支援。
若要啟用 HTTP/3,請設定 SSL 連接器並在 Netty 引擎設定中呼叫 enableHttp3() 函式:
embeddedServer(Netty, environment, {
// SSL connector is required
sslConnector(
keyStore = keyStore,
keyAlias = "server",
keyStorePassword = { "changeit".toCharArray() },
privateKeyPassword = { "changeit".toCharArray() }
) {
port = 8443
host = "0.0.0.0"
}
enableHttp3 {
quicTokenHandler = HmacQuicTokenHandler() // Optional
quicMaxIdleTimeout = 30.seconds
quicInitialMaxData = 10_000_000
quicInitialMaxStreamDataBidirectionalLocal = 1_000_000
quicInitialMaxStreamDataBidirectionalRemote = 1_000_000
quicInitialMaxStreamsBidirectional = 100
udpSocketCount = 1
udpReceiveBufferSize = 0
udpSendBufferSize = 0
configureQuicServerCodec = { /* Optional low-level Netty tuning */ }
}
}) { /* Application */ }.start(wait = true)你也可以使用 enableHttp3 {} 區塊來設定 QUIC 特定的選項,例如連線逾時、流量控制限制以及 UDP 通訊端設定。
同時使用 h2c 與基於 TLS 的 HTTP/2
Netty 伺服器引擎現在可以在同一台伺服器上同時提供基於明文的 HTTP/2 (h2c) 與基於 TLS 的 HTTP/2 服務。
這允許你設定一個明文連接器和一個 SSL 連接器,然後同時啟用 HTTP/2 和 h2c:
embeddedServer(Netty, configure = {
connector {
port = 8080
}
sslConnector(...) {
port = 8443
}
enableHttp2 = true
enableH2c = true
}) {
// ...
}明文連接器接受 h2c 連線,而 SSL 連接器則提供基於 TLS 的 HTTP/2 服務。
結合身分驗證主體的速率限制
RateLimit 外掛程式現在可以在請求驗證期間存取身分驗證主體(Principal)。
這允許你將 rateLimit() 函式巢狀置於 authenticate() 內,並在 requestKey() 函式中使用 call.principal() 來針對每個已驗證使用者套用速率限制:
install(Authentication) {
basic("auth") { validate { UserIdPrincipal(it.name) } }
}
install(RateLimit) {
register(RateLimitName("per-user")) {
rateLimiter(limit = 10, refillPeriod = 60.seconds)
requestKey {
call.principal<UserIdPrincipal>()?.name ?: "anonymous"
}
}
}
routing {
authenticate("auth") {
rateLimit(RateLimitName("per-user")) {
get("/api") { call.respondText("OK") }
}
}
}你也可以將 rateLimit() 放在 authenticate() 之外,以便在身分驗證之前套用速率限制。當速率限制不相依於已驗證的主體時,可使用此方法。
型別安全的身分驗證配置 API
Ktor 3.6.0 引入了實驗性的型別安全身分驗證配置 API。你不再需要安裝具名提供者並透過字串參照它,而是建立一個配置(scheme)值並將其傳遞給需要的路由。在受保護的路由內部,call.principal 具有該配置的主體型別,且保證為非 null:
data class User(val id: String, val email: String)
val jwtAuth = jwt<User>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential ->
val payload = credential.payload
User(
id = payload.subject,
email = payload.getClaim("email").asString()
)
}
}
routing {
authenticateWith(jwtAuth) {
get("/profile") {
call.respondText(call.principal.email)
}
}
}此 API 還新增了選擇性加入的角色檢查、匿名後備機制、具型別的工作階段以及 OAuth 2.0 支援。
型別安全的身分驗證配置 API 標記有 @ExperimentalKtorApi 並使用 Kotlin 上下文參數(context parameters),需要 Kotlin 2.4.0 或 -Xcontext-parameters 編譯器選項。現有的 install(Authentication) API 仍受支援,你可以在同一個應用程式中同時使用這兩種 API。
OpenID Connect 外掛程式
Ktor 3.6.0 新增了實驗性的 OpenID Connect 外掛程式。你不再需要分別設定探索(discovery)、JWKS 解析、JWT 驗證和 OAuth 回呼,而是使用提供者的簽發者(issuer)URL 註冊該提供者,即可取得具型別的身分驗證配置:
suspend fun Application.module() {
val oidc = install(Oidc)
val google = oidc.identityProvider("google") {
issuer = "https://accounts.google.com"
bearer { audience = setOf("my-api") }
}
routing {
authenticateWith(google.jwtBearer) {
get("/me") {
call.respond(call.principal.userInfo)
}
}
}
}該外掛程式同時支援驗證連入存取權杖的資源伺服器,以及具備工作階段、登出和權杖重新整理功能的瀏覽器登入。它實作了帶有 PKCE 的授權碼流程、權杖自我檢查(token introspection,RFC 7662)、資源指示器(RFC 8707)以及受保護資源元資料(RFC 9728)。
該外掛程式標記有 @ExperimentalKtorApi,建置於型別安全的配置 API 之上,且僅適用於 JVM。
使用 ApplicationCall.receive() 支援可為 null 的請求主體
Ktor 現在支援在 ApplicationCall.receive() 函式中使用可為 null 的型別引數。
.receiveNullable() 函式已被棄用。當請求主體可能為 null 時,請搭配可為 null 的型別使用 .receive():
post("/") {
val payload = call.receiveNullable<Payload?>()
} post("/") {
val payload = call.receive<Payload?>()
}這使得預期的請求協定在型別中更加明確:
receive<MyType>()需要非 null 值。receive<MyType?>()接受值或null。
例如,端點可以使用 null 來清除現有的通知偏好設定:
@Serializable
data class NotificationPreferences(
val emailEnabled: Boolean,
val pushEnabled: Boolean,
)
put("/users/{userId}/notification-preferences") {
val userId = call.parameters.getOrFail("userId")
val preferences = call.receive<NotificationPreferences?>()
if (preferences == null) {
preferenceService.clear(userId)
} else {
preferenceService.update(userId, preferences)
}
call.respond(HttpStatusCode.NoContent)
}對 .receive() 的不可為 null 呼叫仍像以前一樣運作。回應 API 不受影響。
Ktor 用戶端
多平台專案的預設用戶端引擎
Ktor 3.6.0 引入了 ktor-client-engine-defaults 構件,為 Kotlin Multiplatform 專案提供了一組精心挑選的 HTTP 用戶端引擎。
將此相依性新增至 commonMain 原始碼集:
kotlin {
sourceSets {
commonMain {
dependencies {
api("io.ktor:ktor-client-engine-defaults:3.6.0")
}
}
}
}接著你便可以在不指定引擎的情況下建立 HttpClient:
val client = HttpClient()針對每個目標平台,Ktor 會使用 ktor-client-engine-defaults 提供的預設引擎。如果有超過一個引擎可用,用戶端會選擇優先順序最高的引擎。預設情況下 CIO 的優先順序最低,因此用戶端會優先選擇其他可用引擎,而非 CIO。
如果你的多平台專案目前在所有支援的目標上皆使用 CIO,請考慮將 CIO 相依性替換為 ktor-client-engine-defaults。這能讓 Ktor 為每個平台提供精選的預設引擎,同時避免在通用原始碼集中進行引擎選擇。
當你需要特定引擎的設定或行為時,仍然可以宣告特定的用戶端引擎。
JVM 上的 WebRTC 用戶端支援
實驗性的 WebRTC 用戶端現已支援 JVM 桌面應用程式。
JVM 實作使用 webrtc-java 原生 WebRTC 繫結,並提供對對等連線(peer connections)、音訊與視訊軌道、資料通道以及連線統計資訊的支援。
JVM 支援目前有幾項平台特定的限制。如需更多資訊,請參閱 WebRTC 用戶端文件。
適用於 HTTP 快取的多平台檔案儲存
HttpCache 外掛程式現在支援多平台檔案儲存。
先前,FileStorage() 函式僅在 JVM 上可用,且需要 java.io.File。現在它使用 kotlinx-io 程式庫,允許你在任何支援的平台上使用 Path 來設定基於檔案的永續快取。
val client = HttpClient {
install(HttpCache) {
val cacheFile = Files.createDirectories(Paths.get("build/cache")).toFile()
publicStorage(FileStorage(cacheFile))
}
}val client = HttpClient {
install(HttpCache) {
publicStorage(FileStorage(Path("build/cache")))
}
}這取代了在將其傳遞給 FileStorage() 之前先建立 File 的 JVM 專屬設定。
控制 ContentNegotiation 中的 Accept 標頭合併
現在你可以控制用戶端 ContentNegotiation 外掛程式如何將已註冊的內容型別與現有的 Accept 標頭進行合併。
預設情況下,ContentNegotiation 外掛程式會新增尚未在請求的 Accept 標頭中呈現的已註冊內容型別。
如果你明確設定了 Accept 標頭,且不希望外掛程式新增已註冊的內容型別,請將 acceptHeaderMergeStrategy 屬性設為 ContentTypeMergeStrategy.SkipIfPresent:
install(ContentNegotiation) {
register(ContentType.Application.Json, noOpJsonConverter)
acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
}使用 SkipIfPresent 時,外掛程式會保留現有的 Accept 標頭。如果請求未包含 Accept 標頭,外掛程式將像往常一樣新增已註冊的內容型別。
CIO 用戶端引擎中的非同步 DNS 解析
此版本新增了對 CIO 用戶端引擎中自訂 DNS 解析的支援。
在 JVM 上,CIO 引擎先前依賴系統 DNS 解析,這可能會阻塞執行緒。你現在可以在 CIO 引擎設定中使用 dnsResolver 屬性覆寫 DNS 解析。
例如,使用 CioDnsResolver() 函式透過特定 DNS 伺服器非同步解析主機名稱並設定逾時:
HttpClient(CIO) {
engine {
dnsResolver = CioDnsResolver(
server = "1.1.1.1",
timeout = 3.seconds
)
}
}覆寫 JavaScript 用戶端引擎中的 fetch()
你現在可以覆寫 JavaScript 用戶端引擎所使用的全域 fetch() 函式。
若要提供自訂實作,請在 Js 引擎設定中設定 fetch 屬性:
val client = HttpClient(Js) {
engine {
fetch = { url, init ->
Promise.reject(IllegalStateException("Networking not available"))
}
}
}這在與提供自身 fetch() 包裝函式(wrapper)的 JavaScript 程式庫(例如 AWS WAF)進行整合時非常實用。如果你沒有設定 fetch,該引擎將繼續使用全域 fetch() 函式。
共用
剖析 Cookie 標頭時保留重複的 Cookie
你現在可以使用 parseClientCookies() 函式來剖析包含多個同名 Cookie 的 Cookie 標頭。
與傳回 Map<String, String> 且對重複名稱僅保留最後一個值的 parseClientCookiesHeader() 函式不同,parseClientCookies() 函式會傳回 List<Pair<String, String>> 並保留重複的 Cookie 項目:
val header = "name=value1; name=value2"
val cookies = parseClientCookies(header)
// [("name", "value1"), ("name", "value2")]
val cookieMap = parseClientCookiesHeader(header)
// {"name"="value2"}當需要保留重複的 Cookie 名稱時,請使用 parseClientCookies()。
