服务器引擎

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

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

支持的平台

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

Engine	平台	HTTP/2
Netty	JVM	✅
Jetty	JVM	✅
Tomcat	JVM	✅
CIO (基于协程的 I/O)	JVM, 原生, 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()，或者在服务器开始接受请求之前执行任何操作。

// Example using Netty
val server = io.ktor.server.netty.EngineMain.createServer(args)
// perform additional initialization, logging, instrumentation, etc.
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