Skip to content

服务器插件 ​

Ktor 中典型的请求/响应流水线如下所示:

Request Response Pipeline

服务器接收请求并通过请求流水线对其进行处理。Ktor 将请求路由到相应的处理程序,并由您的应用程序逻辑进行处理。随后,响应在发送到客户端之前会经过响应流水线。

通过插件添加功能性 ​

许多应用程序都需要独立于应用程序逻辑的功能性。这包括身份验证、序列化和内容编码、压缩、标头、Cookie 等。在 Ktor 中,这些功能性由 插件 提供。

插件可以拦截请求和响应处理的不同阶段。因此,它们可以应用于请求/响应流水线中的不同节点:

Plugin pipeline

插件运行的具体阶段取决于该插件本身以及它所使用的钩子或流水线阶段。通常,请求的处理流程如下:

  • 路由机制确定应由哪个处理程序处理该请求。
  • 在移交给处理程序之前,请求会由一个或多个插件进行处理。
  • 处理程序使用应用程序逻辑生成响应。
  • 在将响应发送给客户端之前,响应会由一个或多个插件进行处理。

路由也是一种插件 ​

插件旨在提供最大的灵活性,并可存在于请求/响应流水线的任何环节。在 Ktor 中,routing 本身就是作为一个插件实现的:

Routing as a Plugin

添加插件依赖项 ​

大多数插件都需要单独的依赖项。例如,CORS 插件在构建脚本中需要 ktor-server-cors 工件:

kotlin
implementation(ktorLibs.server.cors)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.cors
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-cors-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

有关可用插件的完整列表,请参阅 Ktor 项目生成器。有关特定插件所需的依赖项,请参阅相应的插件文档。

安装插件 ​

插件通常在服务器的初始化阶段使用 install() 函数进行配置。根据您创建服务器的方式,您可以在 embeddedServer() 函数内部或在应用程序模块中安装插件:

kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun main() {
    embeddedServer(Netty, port = 8080) {
        install(CORS)
        install(Compression)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(CORS)
    install(Compression)
    // ...
}

您可以在安装插件时通过向 install() 函数传递配置块来进行配置。

例如,在安装 Sessions 插件时,您可以通过指定会话类型和 Cookie 名称来配置基于 Cookie 的会话:

kotlin
install(Sessions) {
    cookie<MyCookie>("MY_COOKIE")
}

将插件安装到特定路由 ​

在 Ktor 中,您不仅可以全局安装插件,还可以将其安装到特定路由上。当不同资源需要不同的插件配置时,这非常有用。

例如,以下代码演示了如何在 /index 路由上安装 CachingHeader 插件并将其配置为添加缓存标头:

kotlin
route("/index") {
    install(CachingHeaders) {
        options { call, content -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 1800)) }
    }
    get {
        call.respondText("Index page")
    }
}

当在多个层级安装同一插件时,Ktor 会应用以下规则:

  • 安装到特定路由的插件配置会覆盖相应的全局插件配置。
  • 如果同一路由被多次定义并且包含同一插件的多次安装,路由机制将合并该路由的安装配置。以最后一次安装为准。

在以下示例中,对 /index/a 和 /index/b 的调用都仅由第二个 CachingHeaders 安装项进行处理:

kotlin
routing {
    route("index") {
        install(CachingHeaders) { /* First configuration */ }
        get("a") {
            // ...
        }
    }
    route("index") {
        install(CachingHeaders) { /* Second configuration */ }
        get("b") {
            // ...
        }
    }
}

默认、可用与自定义插件 ​

Ktor 默认不安装应用程序插件。请安装能够提供您的应用程序所需功能性的插件。

Ktor 提供了丰富多样的插件。您可以在 Ktor 项目生成器中找到可用插件的完整列表。

您还可以创建自己的自定义插件,以封装可在整个应用程序中重复使用或与其他应用程序共享的功能性。