檔案中的組態

檔案中的組態

Ktor 允許您配置各種伺服器參數，例如主機位址與連接埠、要載入的

模組

模組允許您透過分組路由來建構應用程式。

等等。 組態取決於您建立伺服器的方式 ——

embeddedServer 或 EngineMain

了解如何根據您的應用程式部署需求建立伺服器。

。

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

概覽

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

• HOCON ( application.conf )

• YAML ( application.yaml )

  NOTE

  要使用 YAML 組態檔案，您需要新增 ktor-server-config-yaml

  相依性

  了解如何將 Ktor 伺服器相依性新增至現有的 Gradle/Maven 專案。

  。

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

組態檔案應至少包含使用 ktor.application.modules 屬性指定的

要載入的模組

模組允許您透過分組路由來建構應用程式。

，例如：

application.confapplication.yaml

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

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

基本組態

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

application.confapplication.yaml

引擎組態

如果您使用 EngineMain，您可以在 ktor.deployment 群組中指定適用於所有引擎的選項。

application.confapplication.yaml

Netty

您也可以在 ktor.deployment 群組內的組態檔案中配置 Netty 特定的選項：

application.confapplication.yaml

SSL 組態

下面的範例使 Ktor 能夠在 8443 SSL 連接埠上進行監聽，並在獨立的 security 區塊中指定所需的

SSL 設定

需要的相依性：io.ktor:ktor-network-tls-certificates 程式碼範例：ssl-engine-main、ssl-embedded-server

。

application.confapplication.yaml

自訂組態

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

application.confapplication.yaml

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

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

預定義屬性

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

ktor.deployment.host

主機位址。

範例 ：0.0.0.0

ktor.deployment.port

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

範例 ：8080、0

ktor.deployment.sslPort

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

範例 ：8443、0

NOTE

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

ktor.deployment.watch

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

ktor.deployment.rootPath

Servlet

了解如何使用 WAR 封存檔在 Servlet 容器中執行和部署 Ktor 應用程式。

內容路徑。

範例 ：/

ktor.deployment.shutdown.url

關閉 URL。 請注意，此選項使用

Shutdown URL

程式碼範例：%example_name%

外掛程式。

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 程式碼範例：ssl-engine-main、ssl-embedded-server

屬性：

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 屬性：

application.confapplication.yaml

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

application.confapplication.yaml

在程式碼中讀取組態

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

application.confapplication.yaml

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

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

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

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

application.confapplication.yaml

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

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

命令列

如果您使用 EngineMain 建立伺服器，您可以從命令列執行

封裝好的應用程式

了解如何使用 Ktor Gradle 外掛程式建立並執行可執行 Fat JAR。

，並透過傳遞對應的命令列引數來覆寫所需的伺服器參數。例如，您可以按以下方式覆寫組態檔案中指定的連接埠：

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

-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 程式碼範例：ssl-engine-main、ssl-embedded-server

選項：

-sslPort

接聽 SSL 連接埠。

-sslKeyStore

SSL 金鑰庫。

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

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

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

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

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

application.confapplication.yaml

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

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