ファイルでの設定
Ktorでは、ホストアドレスやポート、ロードするモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。など、さまざまなサーバーパラメータを設定できます。 設定方法は、サーバーの作成に使用した方法(embeddedServerまたはEngineMainアプリケーションのデプロイのニーズに応じてサーバーを作成する方法を学びます。)によって異なります。
EngineMainの場合、KtorはHOCONまたはYAML形式を使用する構成ファイルから設定を読み込みます。この方法により、サーバー設定の柔軟性が向上し、アプリケーションを再コンパイルすることなく設定を変更できるようになります。さらに、コマンドラインからアプリケーションを実行し、対応するコマンドライン引数を渡すことで、必要なサーバーパラメータをオーバーライド (override) することも可能です。
概要
サーバーの起動にEngineMainを使用する場合、Ktorはresourcesディレクトリにあるapplication.*という名前のファイルから設定を自動的に読み込みます。以下の2つの構成形式がサポートされています。
HOCON (application.conf)
YAML (application.yaml)
YAML構成ファイルを使用するには、
ktor-server-config-yaml依存関係既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。を追加する必要があります。現在、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には、以下にリストされている追加のオプションが必要です。
オートリロードに使用される監視パス。
サーブレットWARアーカイブを使用して、サーブレットコンテナ内で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} # または $PORT この場合、環境変数の値がリスニングポートの指定に使用されます。実行時にPORT環境変数が存在しない場合は、次のようにデフォルトのポート値を指定できます。
ktor {
deployment {
port = 8080
port = ${?PORT}
}
}ktor:
deployment:
port: ${PORT:8080} # または "$PORT:8080"コード内での構成の読み取り
Ktorを使用すると、構成ファイルで指定されたプロパティ値にアプリケーションコードからアクセスできます。 以下の例では、ktor.deployment.portプロパティを指定しています。
ktor {
deployment {
port = 8080
}
}ktor:
deployment:
port: 8080ApplicationEnvironment.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クラスにデシリアライズ (deserialize) できます。
以下の例では、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を参照してください。
