文件中的配置
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 属性指定的 要加载的模块 模块允许您通过对路由进行分组来构建应用程序结构。 ,例如:
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 。
