Skip to content

服务器引擎 ​

要运行 Ktor 服务器应用程序,首先需要创建并配置服务器。 服务器配置包含不同的设置项:

  • 用于处理网络请求的引擎。
  • 用于访问服务器的主机与端口值。
  • SSL 设置。

支持的平台 ​

下表列出了每个引擎支持的平台:

引擎平台HTTP/2
NettyJVM✅
JettyJVM✅
TomcatJVM✅
CIO (基于协程的 I/O)JVM, Native, GraalVM, JavaScript, WasmJs✖️
ServletApplicationEngineJVM✅

添加依赖项 ​

在使用所需的引擎之前,需要将相应的依赖项添加到你的构建脚本中:

  • ktor-server-netty
  • ktor-server-jetty-jakarta
  • ktor-server-tomcat-jakarta
  • ktor-server-cio

以下是为 Netty 添加依赖项的示例:

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

选择服务器的创建方式 ​

Ktor 服务器应用程序可以通过两种方式创建和运行:

  • 使用 embeddedServer 在代码中快速传递服务器参数
  • 使用 EngineMain 从外部 application.conf 或 application.yaml 文件中加载配置。

embeddedServer ​

embeddedServer() 函数接受一个引擎工厂,用于创建特定类型的引擎。在以下示例中,我们传入 Netty 工厂,以使用 Netty 引擎运行服务器并侦听 8080 端口:

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main(args: Array<String>) {
    embeddedServer(Netty, port = 8080) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

EngineMain ​

EngineMain 表示用于运行服务器的引擎。你可以使用以下引擎:

  • io.ktor.server.netty.EngineMain
  • io.ktor.server.jetty.jakarta.EngineMain
  • io.ktor.server.tomcat.jakarta.EngineMain
  • io.ktor.server.cio.EngineMain

创建并启动服务器 ​

EngineMain.main() 函数用于以选定的引擎启动服务器,并加载在外部配置文件中指定的应用程序模块。在以下示例中,应用程序的 main 函数启动了一个服务器:

kotlin
package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        get("/") {
            call.respondText("Hello, world!")
        }
    }
}
shell
ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

如果你需要使用构建系统任务来启动服务器,则需要将所需的 EngineMain 配置为主类:

kotlin
application {
    mainClass.set("io.ktor.server.netty.EngineMain")
}
groovy
mainClassName = "io.ktor.server.netty.EngineMain"
xml
<properties>
    <main.class>io.ktor.server.netty.EngineMain</main.class>
</properties>

创建服务器实例但不立即启动 ​

除了直接调用 EngineMain.main() 立即启动服务器之外,你还可以调用 EngineMain.createServer(),它会返回一个 EmbeddedServer 实例而不会启动它。

该方法让你可以自主控制何时调用 .start()、.stop(),或在服务器开始接受请求之前执行任意操作。

Kotlin
// 使用 Netty 的示例
val server = io.ktor.server.netty.EngineMain.createServer(args)
// 执行额外的初始化、日志记录、插桩等操作
server.start(wait = true)

配置引擎 ​

本节将介绍如何指定各种特定于引擎的选项。

在代码中 ​

embeddedServer 函数允许你通过 configure 参数传递特定于引擎的选项。该参数包含所有引擎通用的选项,由 ApplicationEngine.Configuration 类公开。

以下示例演示了如何配置使用 Netty 引擎的服务器。在 configure 块中,我们定义了一个 connector 来指定主机与端口,并自定义各种服务器参数:

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main(args: Array<String>) {
    embeddedServer(Netty, configure = {
        connectors.add(EngineConnectorBuilder().apply {
            host = "127.0.0.1"
            port = 8080
        })
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

connectors.add() 方法定义了一个包含指定主机 (127.0.0.1) 和端口 (8080) 的连接器。

除这些选项外,你还可以配置其他特定于引擎的属性。

Netty

Netty 特有的选项由 NettyApplicationEngine.Configuration 类公开。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main() {
    embeddedServer(Netty, configure = {
        requestQueueLimit = 16
        shareWorkGroup = false
        configureBootstrap = {
            // ...
        }
        responseWriteTimeoutSeconds = 10
    }) {
        // ...
    }.start(true)
}

Jetty

Jetty 特有的选项由 JettyApplicationEngineBase.Configuration 类公开。

你可以在 configureServer 块内配置 Jetty 服务器,该块提供了对 Server 实例的访问。

使用 idleTimeout 属性指定连接在关闭前可以处于空闲状态的时长。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.jetty.jakarta.*

fun main() {
    embeddedServer(Jetty, configure = {
        configureServer = { // this: Server -&gt;
            // ...
        }
        idleTimeout = 30.seconds
    }) {
        // ...
    }.start(true)
}

CIO

CIO 特有的选项由 CIOApplicationEngine.Configuration 类公开。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.cio.*

fun main() {
    embeddedServer(CIO, configure = {
        connectionIdleTimeoutSeconds = 45
    }) {
        // ...
    }.start(true)
}

Tomcat

如果使用 Tomcat 作为引擎,可以通过 configureTomcat 属性进行配置,该属性提供了对 Tomcat 实例的访问。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.tomcat.jakarta.*

fun main() {
    embeddedServer(Tomcat, configure = {
        configureTomcat = { // this: Tomcat -&gt;
            // ...
        }
    }) {
        // ...
    }.start(true)
}

在配置文件中 ​

如果使用 EngineMain,可以在 ktor.deployment 分组中指定所有引擎通用的选项。

shell
ktor {
    deployment {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }
}
yaml
ktor:
    deployment:
        connectionGroupSize: 2
        workerGroupSize: 5
        callGroupSize: 10
        shutdownGracePeriod: 2000
        shutdownTimeout: 3000

Netty

你还可以在配置文件的 ktor.deployment 分组中配置 Netty 特有的选项:

shell
ktor {
    deployment {
        maxInitialLineLength = 2048
        maxHeaderSize = 1024
        maxChunkSize = 42
    }
}
yaml
ktor:
    deployment:
        maxInitialLineLength: 2048
        maxHeaderSize: 1024
        maxChunkSize = 42