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 依赖项 了解如何向现有的 Gradle/Maven 项目中添加 Ktor Server 依赖项。 。

    目前基于 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 。