服务器引擎
要运行 Ktor 服务器应用程序,首先需要创建并配置服务器。 服务器配置包含不同的设置项:
- 用于处理网络请求的引擎。
- 用于访问服务器的主机与端口值。
- SSL 设置。
支持的平台
下表列出了每个引擎支持的平台:
| 引擎 | 平台 | HTTP/2 |
|---|---|---|
Netty | JVM | ✅ |
Jetty | JVM | ✅ |
Tomcat | JVM | ✅ |
CIO (基于协程的 I/O) | JVM, Native, GraalVM, JavaScript, WasmJs | ✖️ |
ServletApplicationEngine | JVM | ✅ |
添加依赖项
在使用所需的引擎之前,需要将相应的依赖项添加到你的构建脚本中:
ktor-server-nettyktor-server-jetty-jakartaktor-server-tomcat-jakartaktor-server-cio
以下是为 Netty 添加依赖项的示例:
implementation(ktorLibs.server.netty)implementation ktorLibs.server.netty<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 端口:
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.EngineMainio.ktor.server.jetty.jakarta.EngineMainio.ktor.server.tomcat.jakarta.EngineMainio.ktor.server.cio.EngineMain
创建并启动服务器
EngineMain.main() 函数用于以选定的引擎启动服务器,并加载在外部配置文件中指定的应用程序模块。在以下示例中,应用程序的 main 函数启动了一个服务器:
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!")
}
}
}ktor {
deployment {
port = 8080
}
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
deployment:
port: 8080
application:
modules:
- com.example.ApplicationKt.module如果你需要使用构建系统任务来启动服务器,则需要将所需的 EngineMain 配置为主类:
application {
mainClass.set("io.ktor.server.netty.EngineMain")
}mainClassName = "io.ktor.server.netty.EngineMain"<properties>
<main.class>io.ktor.server.netty.EngineMain</main.class>
</properties>创建服务器实例但不立即启动
除了直接调用 EngineMain.main() 立即启动服务器之外,你还可以调用 EngineMain.createServer(),它会返回一个 EmbeddedServer 实例而不会启动它。
该方法让你可以自主控制何时调用 .start()、.stop(),或在服务器开始接受请求之前执行任意操作。
// 使用 Netty 的示例
val server = io.ktor.server.netty.EngineMain.createServer(args)
// 执行额外的初始化、日志记录、插桩等操作
server.start(wait = true)配置引擎
本节将介绍如何指定各种特定于引擎的选项。
在代码中
embeddedServer 函数允许你通过 configure 参数传递特定于引擎的选项。该参数包含所有引擎通用的选项,由 ApplicationEngine.Configuration 类公开。
以下示例演示了如何配置使用 Netty 引擎的服务器。在 configure 块中,我们定义了一个 connector 来指定主机与端口,并自定义各种服务器参数:
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 类公开。
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 属性指定连接在关闭前可以处于空闲状态的时长。
import io.ktor.server.engine.*
import io.ktor.server.jetty.jakarta.*
fun main() {
embeddedServer(Jetty, configure = {
configureServer = { // this: Server ->
// ...
}
idleTimeout = 30.seconds
}) {
// ...
}.start(true)
}CIO
CIO 特有的选项由 CIOApplicationEngine.Configuration 类公开。
import io.ktor.server.engine.*
import io.ktor.server.cio.*
fun main() {
embeddedServer(CIO, configure = {
connectionIdleTimeoutSeconds = 45
}) {
// ...
}.start(true)
}Tomcat
如果使用 Tomcat 作为引擎,可以通过 configureTomcat 属性进行配置,该属性提供了对 Tomcat 实例的访问。
import io.ktor.server.engine.*
import io.ktor.server.tomcat.jakarta.*
fun main() {
embeddedServer(Tomcat, configure = {
configureTomcat = { // this: Tomcat ->
// ...
}
}) {
// ...
}.start(true)
}在配置文件中
如果使用 EngineMain,可以在 ktor.deployment 分组中指定所有引擎通用的选项。
ktor {
deployment {
connectionGroupSize = 2
workerGroupSize = 5
callGroupSize = 10
shutdownGracePeriod = 2000
shutdownTimeout = 3000
}
}ktor:
deployment:
connectionGroupSize: 2
workerGroupSize: 5
callGroupSize: 10
shutdownGracePeriod: 2000
shutdownTimeout: 3000