伺服器引擎
若要執行 Ktor 伺服器應用程式,您需要先建立並配置伺服器。 伺服器配置包含不同的設定:
- 用於處理網路請求的引擎。
- 用於存取伺服器的主機與連接埠數值。
- SSL 設定。
支援的平台
下表列出各個引擎所支援的平台:
| 引擎 | 平台 | HTTP/2 |
|---|---|---|
Netty | JVM | ✅ |
Jetty | JVM | ✅ |
Tomcat | JVM | ✅ |
CIO (Coroutine-based 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)
// 執行額外的初始化、記錄、檢測(instrumentation)等操作
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