Skip to content

檔案中的組態

Ktor 允許您配置各種伺服器參數,例如主機位址與連接埠、要載入的 模組模組可讓您透過對路由進行分組來建構應用程式。 等等。 組態取決於您建立伺服器的方式 —— embeddedServer 或 EngineMain 了解如何根據您的應用程式部署需求建立伺服器。 。

對於 EngineMain,Ktor 會從使用 HOCON 或 YAML 格式的組態檔案中載入其組態。這種方式為配置伺服器提供了更大的靈活性,並允許您在不重新編譯應用程式的情況下更改組態。此外,您可以從命令列執行應用程式,並透過傳遞對應的 命令列 引數來覆寫所需的伺服器參數。

概覽

如果您使用 EngineMain 來啟動伺服器,Ktor 會自動從位於 resources 目錄中名為 application.* 的檔案載入組態設定。支援兩種組態格式:

  • HOCON ( application.conf )

  • YAML ( application.yaml )

    要使用 YAML 組態檔案,您需要新增 ktor-server-config-yaml 相依性 了解如何將 Ktor Server 相依性新增至現有的 Gradle/Maven 專案。 。

    目前 Maven 型 Ktor 專案不支援 YAML 組態。

組態檔案應至少包含使用 ktor.application.modules 屬性指定的 要載入的模組 模組可讓您透過對路由進行分組來建構應用程式。 ,例如:

shell
ktor {
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    application:
        modules:
            - com.example.ApplicationKt.module

在這種情況下,Ktor 會呼叫下方 Application.kt 檔案中的 Application.module 函式:

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!")
        }
    }
}

除了要載入的模組外,您還可以配置各種伺服器設定,包括 預定義 (例如連接埠或主機、SSL 設定等)以及自訂設定。 讓我們來看看幾個範例。

基本組態

在下面的範例中,使用 ktor.deployment.port 屬性將伺服器接聽連接埠設定為 8080。

shell
ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

引擎組態

如果您使用 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

SSL 組態

下面的範例使 Ktor 能夠在 8443 SSL 連接埠上進行監聽,並在獨立的 security 區塊中指定所需的 SSL 設定 必要相依性: io.ktor:ktor-network-tls-certificates 。

shell
ktor {
    deployment {
        port = 8080
        sslPort = 8443
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }

    security {
        ssl {
            keyStore = keystore.jks
            keyAlias = sampleAlias
            keyStorePassword = foobar
            privateKeyPassword = foobar
            trustStore = truststore.jks
            trustStorePassword = foobar
            enabledProtocols = ["TLSv1.2", "TLSv1.3"]
        }
    }
}
yaml
ktor:
    deployment:
        port: 8080
        sslPort: 8443
    application:
        modules:
            - com.example.ApplicationKt.module

    security:
        ssl:
            keyStore: keystore.jks
            keyAlias: sampleAlias
            keyStorePassword: foobar
            privateKeyPassword: foobar
            trustStore: truststore.jks
            trustStorePassword: foobar
            enabledProtocols: ["TLSv1.2", "TLSv1.3"]

自訂組態

除了指定 預定義屬性 外, Ktor 還允許您在組態檔案中保留自訂設定。 下方的組態檔案包含一個用於保留 JWT 設定的自訂 jwt 群組。

shell
ktor {
    deployment {
        port = 8080
    }

    application {
        modules = [ com.example.ApplicationKt.main ]
    }
}

jwt {
    secret = "secret"
    issuer = "http://0.0.0.0:8080/"
    audience = "http://0.0.0.0:8080/hello"
    realm = "Access to 'hello'"
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.main

jwt:
    secret: "secret"
    issuer: "http://0.0.0.0:8080/"
    audience: "http://0.0.0.0:8080/hello"
    realm: "Access to 'hello'"

您可以在程式碼中 讀取並處理此類設定。

請注意,敏感資料(如私鑰、資料庫連線設定等)不應以純文字形式儲存在組態檔案中。請考慮使用 環境變數 來指定這些參數。

預定義屬性

以下是可以在 組態檔案 中使用的預定義設定清單。

ktor.deployment.host

主機位址。

範例 :0.0.0.0

ktor.deployment.port

接聽連接埠。您可以將此屬性設為 0 以在隨機連接埠上執行伺服器。

範例 :8080、0

ktor.deployment.sslPort

接聽 SSL 連接埠。您可以將此屬性設為 0 以在隨機連接埠上執行伺服器。

範例 :8443、0

請注意,SSL 需要額外的選項,列於下方。

ktor.deployment.watch

用於 自動重新載入 的監看路徑。

ktor.deployment.rootPath

Servlet了解如何使用 WAR 封存檔在 Servlet 容器內執行並部署 Ktor 應用程式。 內容路徑。

範例 :/

ktor.deployment.shutdown.url

關閉 URL。 請注意,此選項使用 Shutdown URL程式碼範例: shutdown-url 外掛程式。

ktor.deployment.shutdownGracePeriod

伺服器停止接受新請求前的最長時間(以毫秒為單位)。

ktor.deployment.shutdownTimeout

等待伺服器完全停止的最長時間(以毫秒為單位)。

ktor.deployment.callGroupSize

用於處理應用程式呼叫的執行緒池最小大小。

ktor.deployment.connectionGroupSize

用於接受新連線並開始呼叫處理的執行緒計數。

ktor.deployment.workerGroupSize

用於處理連線、剖析訊息以及執行引擎內部工作的事件群組大小。

如果您已設定 ktor.deployment.sslPort,則需要指定下列 SSL 特定 必要相依性: io.ktor:ktor-network-tls-certificates 屬性:

ktor.security.ssl.keyStore

SSL 金鑰庫。

ktor.security.ssl.keyAlias

SSL 金鑰庫的別名。

ktor.security.ssl.keyStorePassword

SSL 金鑰庫的密碼。

ktor.security.ssl.privateKeyPassword

SSL 私鑰的密碼。

環境變數

在組態檔案中,您可以使用環境變數來替換參數。

  • 在 HOCON (application.conf) 中,僅支援 ${ENV} 語法。
  • 在 YAML (application.yaml) 中,支援 ${ENV} 和 $ENV 兩種語法。

例如,您可以透過以下方式將 PORT 環境變數指派給 ktor.deployment.port 屬性:

shell
ktor {
    deployment {
        port = ${PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT} # or $PORT

在這種情況下,將使用環境變數值來指定接聽連接埠。 如果 PORT 環境變數在執行時不存在,您可以按如下方式提供預設連接埠值:

shell
ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT:8080} # or "$PORT:8080"

在程式碼中讀取組態

Ktor 允許您從應用程式程式碼中存取組態檔案中指定的屬性值。 在以下範例中,您指定了 ktor.deployment.port 屬性:

shell
ktor {
    deployment {
        port = 8080
    }
}
yaml
ktor:
    deployment:
        port: 8080

您可以使用 ApplicationEnvironment.config() 函式存取應用程式的組態並擷取屬性值。使用 .property() 函式存取必要的值,或使用 .propertyOrNull() 存取選填值:

kotlin
fun Application.module() {
    val port = environment.config.propertyOrNull("ktor.deployment.port")?.getString() ?: "8080"
    routing {
        get {
            call.respondText("Listening on port $port")
        }
    }
}

將組態還原序列化為資料類別

您可以將組態還原序列化為 Kotlin 類別,以實現對組態值的型別安全存取。

下面的範例定義了 app 和 security 組態區段,並將它們映射到可序列化的 Kotlin 資料類別。

shell
app {
    port = 8080
    host = "0.0.0.0"
}

security {
    clientId = ${?CLIENT_ID}
    clientSecret = ${?CLIENT_SECRET}
}
yaml
app:
    port: 8080
    host: "0.0.0.0"
security:
    clientId: $CLIENT_ID
    clientSecret: $CLIENT_SECRET

使用 Application.property() 或 Application.propertyOrNull() 函式來還原序列化特定的組態區段:

kotlin
@Serializable
data class Security(val clientId: String, val clientSecret: String)

fun Application.module() {
    val securityConfig: Security = property("security")

    println("Authorization header: ${securityConfig.clientId}:${securityConfig.clientSecret}")
}

如果您需要還原序列化整個 ApplicationConfig,請使用 ApplicationConfig.getAs() 函式:

kotlin
@Serializable
data class App(val port: Int, val host: String)
@Serializable
data class Security(val clientId: String, val clientSecret: String)
@Serializable
data class Config(val app: App, val security: Security)

fun Application.module() {
    val config = environment.config.getAs<Config>()

    val clientId = config.security.clientId
    val clientSecret = config.security.clientSecret

    println("Authorization header: $clientId:$clientSecret")
}

命令列

如果您使用 EngineMain 建立伺服器,您可以從命令列執行 封裝好的應用程式了解如何使用 Ktor Gradle 外掛程式建立並執行可執行的 fat JAR。,並透過傳遞對應的命令列引數來覆寫所需的伺服器參數。例如,您可以按以下方式覆寫組態檔案中指定的連接埠:

shell
java -jar sample-app.jar -port=8080

可用的命令列選項列於下方:

-jar

JAR 檔案路徑。

-config

自訂組態檔案的路徑,用於替代 resources 中的 application.conf / application.yaml 。

範例 :java -jar sample-app.jar -config=anotherfile.conf

注意 :您可以傳遞多個值。java -jar sample-app.jar -config=config-base.conf -config=config-dev.conf。在這種情況下,所有組態都將合併,且右側組態中的值具有優先權。

-host

主機位址。

-port

接聽連接埠。

-watch

用於 自動重新載入 的監看路徑。

SSL 特定必要相依性: io.ktor:ktor-network-tls-certificates 選項:

-sslPort

接聽 SSL 連接埠。

-sslKeyStore

SSL 金鑰庫。

如果您需要覆寫沒有對應命令列選項的 預定義屬性,請使用 -P 旗標,例如:

java -jar sample-app.jar -P:ktor.deployment.callGroupSize=7

您也可以使用 -P 旗標來覆寫 自訂屬性。

範例:使用自訂屬性指定環境

您可以使用自訂組態屬性,根據伺服器執行的環境(例如本機開發或生產環境)來更改應用程式行為。

為此,請在 application.conf 或 application.yaml 中定義自訂屬性,並從 環境變數 中指派其值。在下面的範例中,KTOR_ENV 環境變數被指派給自訂的 ktor.environment 屬性。隨後可以針對本機和生產環境為 KTOR_ENV 設定不同的值。

ktor {
    environment = ${?KTOR_ENV}
}
yaml
ktor:
    environment: $?KTOR_ENV

您可以在執行時透過 在程式碼中讀取組態 來存取 ktor.environment 的值,並執行所需的操作:

kotlin
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module() {
    val env = environment.config.propertyOrNull("ktor.environment")?.getString()
    routing {
        get {
            call.respondText(when (env) {
                "dev" -> "Development"
                "prod" -> "Production"
                else -> "..."
            })
        }
    }
}

如需完整程式碼範例,請參閱 engine-main-custom-environment 。