Skip to content

伺服器引擎 ​

若要執行 Ktor 伺服器應用程式,您需要先建立並配置伺服器。 伺服器配置包含不同的設定:

  • 用於處理網路請求的引擎。
  • 用於存取伺服器的主機與連接埠數值。
  • SSL 設定。

支援的平台 ​

下表列出各個引擎所支援的平台:

引擎平台HTTP/2
NettyJVM✅
JettyJVM✅
TomcatJVM✅
CIO (Coroutine-based 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)
// 執行額外的初始化、記錄、檢測(instrumentation)等操作
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