檔案中的組態
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 屬性指定的 要載入的模組 模組可讓您透過對路由進行分組來建構應用程式。 ,例如:
ktor {
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
application:
modules:
- com.example.ApplicationKt.module 在這種情況下,Ktor 會呼叫下方 Application.kt 檔案中的 Application.module 函式:
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。
ktor {
deployment {
port = 8080
}
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
deployment:
port: 8080
application:
modules:
- com.example.ApplicationKt.module引擎組態
如果您使用 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: 3000SSL 組態
下面的範例使 Ktor 能夠在 8443 SSL 連接埠上進行監聽,並在獨立的 security 區塊中指定所需的 SSL 設定 必要相依性: io.ktor:ktor-network-tls-certificates 。
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:
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 群組。
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:
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'"您可以在程式碼中 讀取並處理此類設定。
請注意,敏感資料(如私鑰、資料庫連線設定等)不應以純文字形式儲存在組態檔案中。請考慮使用 環境變數 來指定這些參數。
預定義屬性
以下是可以在 組態檔案 中使用的預定義設定清單。
主機位址。
範例 :0.0.0.0
接聽連接埠。您可以將此屬性設為 0 以在隨機連接埠上執行伺服器。
範例 :8080、0
接聽 SSL 連接埠。您可以將此屬性設為 0 以在隨機連接埠上執行伺服器。
範例 :8443、0
請注意,SSL 需要額外的選項,列於下方。
用於 自動重新載入 的監看路徑。
Servlet了解如何使用 WAR 封存檔在 Servlet 容器內執行並部署 Ktor 應用程式。 內容路徑。
範例 :/
關閉 URL。 請注意,此選項使用 Shutdown URL程式碼範例: shutdown-url 外掛程式。
伺服器停止接受新請求前的最長時間(以毫秒為單位)。
等待伺服器完全停止的最長時間(以毫秒為單位)。
用於處理應用程式呼叫的執行緒池最小大小。
用於接受新連線並開始呼叫處理的執行緒計數。
用於處理連線、剖析訊息以及執行引擎內部工作的事件群組大小。
如果您已設定 ktor.deployment.sslPort,則需要指定下列 SSL 特定 必要相依性: io.ktor:ktor-network-tls-certificates 屬性:
SSL 金鑰庫。
SSL 金鑰庫的別名。
SSL 金鑰庫的密碼。
SSL 私鑰的密碼。
環境變數
在組態檔案中,您可以使用環境變數來替換參數。
- 在 HOCON (application.conf) 中,僅支援
${ENV}語法。 - 在 YAML (application.yaml) 中,支援
${ENV}和$ENV兩種語法。
例如,您可以透過以下方式將 PORT 環境變數指派給 ktor.deployment.port 屬性:
ktor {
deployment {
port = ${PORT}
}
}ktor:
deployment:
port: ${PORT} # or $PORT 在這種情況下,將使用環境變數值來指定接聽連接埠。 如果 PORT 環境變數在執行時不存在,您可以按如下方式提供預設連接埠值:
ktor {
deployment {
port = 8080
port = ${?PORT}
}
}ktor:
deployment:
port: ${PORT:8080} # or "$PORT:8080"在程式碼中讀取組態
Ktor 允許您從應用程式程式碼中存取組態檔案中指定的屬性值。 在以下範例中,您指定了 ktor.deployment.port 屬性:
ktor {
deployment {
port = 8080
}
}ktor:
deployment:
port: 8080 您可以使用 ApplicationEnvironment.config() 函式存取應用程式的組態並擷取屬性值。使用 .property() 函式存取必要的值,或使用 .propertyOrNull() 存取選填值:
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 資料類別。
app {
port = 8080
host = "0.0.0.0"
}
security {
clientId = ${?CLIENT_ID}
clientSecret = ${?CLIENT_SECRET}
}app:
port: 8080
host: "0.0.0.0"
security:
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET 使用 Application.property() 或 Application.propertyOrNull() 函式來還原序列化特定的組態區段:
@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() 函式:
@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。,並透過傳遞對應的命令列引數來覆寫所需的伺服器參數。例如,您可以按以下方式覆寫組態檔案中指定的連接埠:
java -jar sample-app.jar -port=8080可用的命令列選項列於下方:
JAR 檔案路徑。
自訂組態檔案的路徑,用於替代 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。在這種情況下,所有組態都將合併,且右側組態中的值具有優先權。
主機位址。
接聽連接埠。
用於 自動重新載入 的監看路徑。
SSL 特定必要相依性: io.ktor:ktor-network-tls-certificates 選項:
接聽 SSL 連接埠。
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}
}ktor:
environment: $?KTOR_ENV 您可以在執行時透過 在程式碼中讀取組態 來存取 ktor.environment 的值,並執行所需的操作:
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 。
