文件中的配置

文件中的配置

Ktor 允许您配置各种服务器参数，例如主机地址和端口、要加载的

模块

模块允许您通过对路由进行分组来构建应用程序。

等。 配置取决于您创建服务器的方式 ——

embeddedServer 或 EngineMain

了解如何根据您的应用程序部署需求创建服务器。

。

对于 EngineMain，Ktor 从使用 HOCON 或 YAML 格式的配置文件中加载其配置。这种方式为配置服务器提供了更大的灵活性，并允许您在不重新编译应用程序的情况下更改配置。此外，您可以从命令行运行应用程序，并通过传递相应的 命令行 参数来覆盖所需的服务器参数。

概览

如果您使用 EngineMain 启动服务器，Ktor 会自动从位于 resources 目录中名为 application.* 的文件加载配置设置。支持两种配置格式：

• HOCON ( application.conf )

• YAML ( application.yaml )

  NOTE

  要使用 YAML 配置文件，您需要添加 ktor-server-config-yaml

  依赖项

  了解如何将 Ktor Server 依赖项添加到现有的 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 。