服务器引擎

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

• 用于处理网络请求的引擎。
• 用于访问服务器的主机名 (host) 和端口 (port) 值。
• SSL 设置。

支持的平台

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

引擎	平台	HTTP/2
Netty	JVM	✅
Jetty	JVM	✅
Tomcat	JVM	✅
CIO (基于协程的 I/O)	JVM, Native, GraalVM, JavaScript, WasmJs	✖️
ServletApplicationEngine	JVM	✅

添加依赖项

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

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

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

Gradle (Kotlin)Gradle (Groovy)Maven

选择创建服务器的方式

可以通过两种方式创建并运行 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.EngineMain
• io.ktor.server.jetty.jakarta.EngineMain
• io.ktor.server.tomcat.jakarta.EngineMain
• io.ktor.server.cio.EngineMain

创建并启动服务器

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

Application.ktapplication.confapplication.yaml

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 配置为主类：

Gradle (Kotlin)Gradle (Groovy)Maven

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 来指定主机名和端口，并自定义了各种服务器参数：

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

除了这些选项外，您还可以配置其他引擎特定的属性。

Netty

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

Jetty

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

您可以在 configureServer 块中配置 Jetty 服务器，该块提供了对 Server 实例的访问。

使用 idleTimeout 属性指定连接在关闭之前可以保持空闲的时间。

CIO

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

Tomcat

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

在配置文件中配置

如果您使用 EngineMain，可以在 ktor.deployment 组内指定所有引擎通用的选项。

application.confapplication.yaml

Netty

您也可以在配置文件的 ktor.deployment 组内配置 Netty 特有的选项：

application.confapplication.yaml