Skip to content

Ktor 3.3.0 最新变化 ​

发布日期:2025 年 9 月 11 日

Ktor 3.3.0 在服务器、客户端和工具链方面带来了诸多新功能。以下是此功能版本的主要亮点:

Ktor Server ​

静态资源的自定义回退 ​

Ktor 3.3.0 为静态内容引入了全新的 fallback() 函数,允许您在未找到所请求的资源时定义自定义行为。

与始终提供相同回退文件的 default() 不同,fallback() 允许您访问最初请求的路径以及当前的 ApplicationCall。您可以使用它进行重定向、返回自定义状态码或动态提供不同的文件。

若要定义自定义回退行为,请在 staticFiles()、staticResources()、staticZip() 或 staticFileSystem() 中使用 fallback() 函数:

kotlin
staticFiles("/files", File("textFiles")) {
    fallback { requestedPath, call ->
        when {
            requestedPath.endsWith(".php") -> call.respondRedirect("/static/index.html") // 绝对路径
            requestedPath.endsWith(".kt") -> call.respondRedirect("Default.kt") // 相对路径
            requestedPath.endsWith(".xml") -> call.respond(HttpStatusCode.Gone)
            else -> call.respondFile(File("files/index.html"))
        }
    }
}

静态内容的 LastModified 与 Etag 标头 ​

Ktor 3.3.0 引入了对静态资源 ETag 和 LastModified 标头的支持。安装 ConditionalHeaders 插件后,您可以处理条件标头,从而在内容自上次请求以来未发生变更时避免发送内容正文:

kotlin
staticFiles("/filesWithEtagAndLastModified", File("files")) {
    etag { resource -> EntityTagVersion("etag") }
    lastModified { resource -> GMTDate() }
}

这些值会根据每个资源动态计算并应用到响应中。

您还可以使用预定义的提供程序,例如使用资源内容的 SHA-256 哈希来生成强 ETag:

kotlin
staticFiles("/filesWithStrongGeneratedEtag", File("files")) {
    etag(ETagProvider.StrongSha256)
}

开发模式自动重载限制 ​

在 Ktor 3.2.0 中,引入的对挂起模块函数的支持引发了一个回归问题,导致使用阻塞模块引用的应用程序中自动重载停止工作。

该回归问题在 3.3.0 中仍然存在,自动重载仅在使用 suspend 函数模块和配置引用时可正常运行。

支持的模块声明示例如下:

kotlin
// 受支持 — 挂起函数引用
embeddedServer(Netty, port = 8080, module = Application::mySuspendModule)

// 受支持 — 配置引用 (application.conf / application.yaml)
ktor {
    application {
        modules = [ com.example.ApplicationKt.mySuspendModule ]
    }
}

我们计划在未来的版本中恢复对阻塞函数引用的支持。在此之前,在 development 模式下请优先使用 suspend 模块或配置引用。

HTTP/2 明文 (h2c) 支持 ​

Ktor 3.3.0 为 Netty 引擎引入了对明文 HTTP/2 (h2c) 的支持,允许在不使用 TLS 加密的情况下进行 HTTP/2 通信。 这种配置通常用于受信任的环境,例如本地测试或专用网络。

要启用 h2c,请在引擎配置中将 enableH2c 标志设置为 true。 有关详细信息,请参阅不使用 TLS 的 HTTP/2。

Ktor Client ​

SSE 响应体缓冲区 ​

此前,在发生 SSE 错误后尝试调用 response.bodyAsText() 会因重复消费问题而失败。

Ktor 3.3.0 引入了可配置的诊断缓冲区,允许您捕获已处理的 SSE 数据以进行调试和错误处理。

您可以在安装 SSE 插件时进行全局配置缓冲区:

kotlin
install(SSE) {
    bufferPolicy = SSEBufferPolicy.LastEvents(10)
}

或者按单次调用进行配置:

kotlin
client.sse(url, { bufferPolicy(SSEBufferPolicy.All) }) {
    // …
}

随着 SSE 流的消费,客户端会在内存缓冲区中保留已处理数据的快照(无需从网络重新读取)。如果发生错误,您可以安全地调用 response?.bodyAsText() 进行日志记录或诊断。

有关详细信息,请参阅响应缓冲。

WebRTC 客户端 ​

此版本引入了实验性 WebRTC 客户端支持,用于多平台项目中的点对点实时通信。

WebRTC 支持视频通话、多人游戏和协作工具等应用程序。通过此版本,您现在可以使用统一的 Kotlin API 在 JavaScript/Wasm 和 Android 目标之间建立对等连接并交换数据通道。未来版本计划支持 iOS、JVM 桌面和 Native 等其他目标。

您可以通过选择适用于您平台的引擎并提供配置来创建 WebRtcClient,类似于 HttpClient:

kotlin
val jsClient = WebRtcClient(JsWebRtc) {
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}
kotlin
val androidClient = WebRtcClient(AndroidWebRtc) {
    context = appContext // 必需:提供 Android context
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}
kotlin
val iosClient = WebRtcClient(IosWebRtc) {
    // 相同配置,不需要额外的 context
}
kotlin
val jvmClient = WebRtcClient(JvmWebRtc) {
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}

创建后,客户端可以使用交互式连通建立 (ICE) 建立点对点连接。协商完成后,对等端即可打开数据通道并交换消息。

kotlin
val connection = client.createPeerConnection()

// 添加远程 ICE 候选者(通过您的信令通道接收)
connection.addIceCandidate(WebRtc.IceCandidate(candidateString, sdpMid, sdpMLineIndex))

// 等待所有本地候选者收集完毕
connection.awaitIceGatheringComplete()

// 监听传入的数据通道事件
connection.dataChannelEvents.collect { event ->
   when (event) {
     is Open -> println("Another peer opened a chanel: ${event.channel}")
     is Closed -> println("Data channel is closed")
     is Closing, is BufferedAmountLow, is Error -> println(event)
   }
}

// 创建通道并收发消息
val channel = connection.createDataChannel("chat")
channel.send("hello")
val answer = channel.receiveText()

有关用法和限制的更多详细信息,请参阅 WebRTC 客户端文档。

OkHttp 版本更新 ​

在 Ktor 3.3.0 中,Ktor 客户端的 OkHttp 引擎已升级为使用 OkHttp 5.1.0(此前为 4.12.0)。对于直接与 OkHttp 交互的项目,该主要版本升级可能会引入 API 变更。此类项目应验证兼容性。

统一 OkHttp SSE 会话 ​

OkHttp 引擎现在使用用于 Server-Sent Events (SSE) 的标准 API,取代了此前引入的 OkHttpSSESession。 此变更统一了所有客户端引擎上的 SSE 处理,并解决了 OkHttp 特定实现的局限性。

Gradle 插件 ​

Experimental

OpenAPI 规范生成

Ktor 3.3.0 通过 Gradle 插件和编译器插件引入了实验性 OpenAPI 生成功能。这允许您在构建时直接根据应用程序代码生成 OpenAPI 规范。

它提供以下功能:

  • 分析 Ktor 路由定义并合并嵌套路由、局部扩展和资源路径。
  • 解析前面的 KDoc 注解以提供 OpenAPI 元数据,包括:
    • 路径、查询、标头、Cookie 和正文形参
    • 响应代码和类型
    • 安全性、描述、弃用信息和外部文档链接
  • 从 call.receive() 和 call.respond() 推断请求体和响应体。

生成 OpenAPI 规范 ​

要根据 Ktor 路由和 KDoc 注解生成 OpenAPI 规范文件,请使用以下命令:

shell
./gradlew buildOpenApi

提供规范服务 ​

若要在运行时提供生成的规范,可以使用 OpenAPI 或 SwaggerUI 插件。

以下示例在 OpenAPI 端点处提供生成的规范文件:

kotlin
routing {
    openAPI("/docs", swaggerFile = "openapi/generated.json")
}

有关此功能的更多详细信息,请参阅 OpenAPI 规范生成。

共享 ​

Jetty 版本更新 ​

Jetty 服务器和客户端引擎已升级为使用 Jetty 12。对于大多数应用程序,此升级完全向后兼容,但客户端和服务器代码现在在内部利用了更新后的 Jetty API。

如果您的项目直接使用 Jetty API,请注意存在破坏性变更。有关更多详细信息,请参阅官方 Jetty 迁移指南。