创建、打开并运行新的 Ktor 项目
在本教程中,您将学习如何创建、打开和运行您的第一个 Ktor 服务器项目。成功运行后,您可以完成一系列任务以熟悉 Ktor。
这是帮助您开始使用 Ktor 构建服务器应用程序系列教程的第一篇。您可以独立完成每个教程,但我们强烈建议您按照推荐的顺序进行学习:
- 创建、打开并运行新的 Ktor 项目。
- 处理请求并生成响应通过构建一个任务管理器应用程序,学习在 Kotlin 中使用 Ktor 处理路由、请求和形参的基础知识。。
- 创建生成 JSON 的 RESTful API了解如何使用 Kotlin 和 Ktor 构建后端服务,并包含一个生成 JSON 文件的 RESTful API 示例。。
- 使用 Thymeleaf 模板创建网站了解如何使用 Ktor 和 Thymeleaf 模板在 Kotlin 中构建网站。。
- 创建 WebSocket 应用程序了解如何利用 WebSockets 发送和接收内容。。
- 使用 Exposed 集成数据库了解使用 Exposed SQL 库将 Ktor 服务连接到数据库仓库的过程。。
创建新的 Ktor 项目
创建新 Ktor 项目最快的方法之一是使用基于 Web 的 Ktor 项目生成器。
或者,您也可以使用适用于 IntelliJ IDEA Ultimate 的专用 Ktor 插件或 Ktor CLI 工具来生成项目。
使用 Ktor 项目生成器
要使用 Ktor 项目生成器创建新项目,请按照以下步骤操作:
前往 Ktor 项目生成器。
在 Project artifact 字段中,输入 com.example.ktor-sample 作为项目工件的名称。

点击 Configure 以打开设置下拉菜单:

提供以下设置项:
Build System: 选择所需的构建系统了解如何向现有的 Gradle/Maven 项目中添加 Ktor Server 依赖项。。可以是 Gradle Kotlin、Gradle Groovy、Maven 或 Amper。
Engine: 选择用于运行服务器的引擎了解用于处理网络请求的引擎。。
Configuration: 选择是在 YAML 或 HOCON 文件中了解如何在配置文件中配置各种服务器参数。指定服务器参数,还是在代码中了解如何在代码中配置各种服务器参数。指定。
目前基于 Maven 的 Ktor 项目不支持 YAML 配置。
在本教程中,您可以保留这些设置的默认值。
点击 Done 以保存配置并关闭菜单。
下方列出了一组可以添加到项目中的插件插件提供常见功能性,例如序列化、内容编码、压缩等。。插件是为 Ktor 应用程序提供常用功能的基础构建块,例如身份验证、序列化和内容编码、压缩、Cookie 支持等。
在本教程中,现阶段您无需添加任何插件。
点击 Download 按钮以生成并下载您的 Ktor 项目。

下载应会自动开始。
生成新项目后,接下来请继续进行解压缩并运行您的 Ktor 项目。
使用适用于 IntelliJ IDEA Ultimate 的 Ktor 插件
本节介绍如何使用适用于 IntelliJ IDEA Ultimate 的 Ktor 插件设置项目。
要创建新的 Ktor 项目,请打开 IntelliJ IDEA 并按以下步骤操作:
在欢迎屏幕上,点击 New Project。
或者,从主菜单中选择 File | New | Project。
在 New Project 向导中,从左侧列表中选择 Ktor。
在右侧窗格中,您可以指定以下设置:

Name:指定项目名称。输入 ktor-sample 作为项目名称。
Location:指定项目的目录。
Website: 指定用于生成包名的网域。
Artifact: 该字段显示生成的工件名称。
Engine: 选择用于运行服务器的引擎了解用于处理网络请求的引擎。。
Include samples: 保持启用此选项以添加插件的示例代码。
点击 Advanced Settings 以展开附加设置菜单:

提供以下设置项:
Build System: 选择所需的构建系统了解如何向现有的 Gradle/Maven 项目中添加 Ktor Server 依赖项。。可以是 Gradle Kotlin、Gradle Groovy、Maven 或 Amper。
Ktor version: 选择所需的 Ktor 版本。
Configuration: 选择是在 YAML 或 HOCON 文件中了解如何在配置文件中配置各种服务器参数。指定服务器参数,还是在代码中了解如何在代码中配置各种服务器参数。指定。
目前基于 Maven 的 Ktor 项目不支持 YAML 配置。
在本教程中,您可以保留这些设置的默认值。
点击 Next 进入下一页。

在此页面上,您可以选择一组插件插件提供常见功能性,例如序列化、内容编码、压缩等。——这些是提供 Ktor 应用程序通用功能的基础构建块,例如身份验证、序列化和内容编码、压缩、Cookie 支持等。
在本教程中,现阶段您无需添加任何插件。
点击 Create 并等待 IntelliJ IDEA 生成项目并安装依赖项。
创建新项目后,接下来请继续学习如何打开、浏览并运行应用程序。
使用 Ktor CLI 工具
本节介绍如何使用 Ktor CLI 工具设置项目。
要创建新的 Ktor 项目,请打开您常用的终端并按照以下步骤操作:
- 使用以下命令之一安装 Ktor CLI 工具: console
brew install ktorconsolewinget install JetBrains.KtorCLI - 要在交互模式下生成新项目,请使用以下命令: console
ktor new - 输入 ktor-sample 作为项目名称:

(可选)您还可以通过编辑项目名称下方的 Location 路径来更改项目的保存位置。
- 按 Enter 键继续。
- 在下一步中,您可以搜索并向项目添加插件插件提供常见功能性,例如序列化、内容编码、压缩等。。插件是为 Ktor 应用程序提供常用功能的基础构建块,例如身份验证、序列化和内容编码、压缩、Cookie 支持等。

在本教程中,现阶段您无需添加任何插件。
- 按 CTRL+G 生成项目。
或者,您也可以通过选择 CREATE PROJECT (CTRL+G) 并按 Enter 键来生成项目。
解压缩并运行您的 Ktor 项目
在本节中,您将学习如何从命令行解压缩、构建和运行项目。以下步骤假设:
- 您已创建并下载了名为 ktor-sample 的 Gradle 项目。
- 该项目位于您主目录中名为 myprojects 的文件夹内。
如有必要,请根据您自己的设置修改名称和路径。
打开您常用的命令行工具并按照以下步骤操作:
在终端窗口中,导航到下载项目的文件夹:
consolecd ~/myprojects将 ZIP 压缩包解压缩到同名文件夹中:
consoleunzip ktor-sample.zip -d ktor-sampleconsoletar -xf ktor-sample.zip现在您的目录中将包含该 ZIP 压缩包和解压后的文件夹。
从该目录进入新创建的文件夹:
consolecd ktor-sample在 macOS 和 UNIX 系统上,您必须为 Gradle 帮助程序脚本添加可执行权限,以便系统将其识别为可运行的命令。为此,请使用
chmod命令:consolechmod +x ./gradlew要构建项目,请使用以下命令:
console./gradlew buildconsolegradlew build构建成功后,请继续进行下一步以运行项目。
要运行项目,请使用以下命令:
console./gradlew runconsolegradlew run要验证项目是否正在运行,请在浏览器中打开终端输出中显示的 URL(http://0.0.0.0:8080)。 您应该会在浏览器中看到显示的“Hello World!”消息:

祝贺您!您已成功启动了 Ktor 项目。
在 IntelliJ IDEA 中打开、浏览并运行您的 Ktor 项目
打开项目
如果您安装了 IntelliJ IDEA,可以轻松地从命令行打开该项目。
请确保您位于项目文件夹中,然后输入 idea 命令,后跟一个英文句点表示当前文件夹:
idea .或者,若要手动打开项目,请启动 IntelliJ IDEA。
如果打开了欢迎屏幕,请点击 Open。否则,请转到主菜单中的 File | Open,选择 ktor-sample 文件夹将其打开。
浏览项目
打开项目后,您可以看到如下结构:

若要查看完整布局,请点击每个文件夹旁的展开箭头以展开 Project 视图中的文件夹。
应用程序源代码位于 src/main/kotlin 下。默认创建了两个文件,分别命名为 Application.kt 和 Routing.kt。

项目的名称在 settings.gradle.kts 文件中配置:
rootProject.name = "ktor-sample"配置文件以及其他类型的内容存放在 src/main/resources 文件夹中。

运行项目
点击右侧侧边栏上的 Gradle 图标(
)打开 Gradle 工具窗口。
在此工具窗口中,导航到 Tasks | application,双击 run 任务。

您的 Ktor 应用程序将在 IDE 底部的 Run 工具窗口中启动:

先前在命令行中显示的消息现在将显示在 Run 工具窗口中。
若要确认项目正在运行,请在浏览器中打开指定的 URL(http://0.0.0.0:8080)。
您应该会再次看到屏幕上显示的“Hello World!”消息:

若要在 IntelliJ IDEA 内运行项目:
您可以通过 Run 工具窗口管理应用程序。
- 要终止应用程序,请点击停止按钮
。
- 要重新启动进程,请点击重新运行按钮
。
这些选项在 IntelliJ IDEA Run 工具窗口文档中有进一步说明。
可尝试的其他任务
以下是您可能希望尝试的一些其他任务:
这些任务彼此独立,但难度逐渐增加。按列出的顺序尝试是循序渐进学习的最简单方式。为简单起见并避免重复,以下说明均假定您按顺序尝试这些任务。
凡需要编写代码之处,我们均已指定了代码和相应的导入。IDE 可能会自动为您添加这些导入。
更改默认端口
在配置文件中更改端口
如果您选择将配置保存在外部的 YAML 或 HOCON 文件中,请在 Project 视图中导航到 src/main/resources 文件夹并按以下步骤操作:
- 打开您的配置文件(application.yaml 或 application.conf)。它应如下所示: yaml
ktor: deployment: port: 8080 application: modules: - com.example.RoutingKt.configureRoutinggenericktor { deployment { port = 8080 port = ${?PORT} } application { modules = [ com.example.RoutingKt.configureRouting ] } } - 将文件中的
port值更改为您选择的另一个数字,例如9292。 点击重新运行按钮(
)以重新启动应用程序。
要验证应用程序是否在新端口号下运行,您可以在浏览器中打开新的 URL(http://0.0.0.0:9292),或者在 IntelliJ IDEA 中创建新的 HTTP 请求文件:

在代码中更改端口
创建新的 Ktor 项目时,您可以选择在代码中或在外部的 YAML 或 HOCON 文件中存储配置。
如果您选择在代码中存储配置,请在 Project 视图中导航到 src/main/kotlin 文件夹并按以下步骤操作:
打开 main.kt 文件。您应该会看到类似如下的代码:
kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 8080, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }在
embeddedServer()函数中,将port形参更改为您选择的另一个数字,例如9292。kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 9292, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }点击重新运行按钮(
)以重新启动应用程序。
要验证应用程序是否在新端口号下运行,您可以在浏览器中打开新的 URL(http://0.0.0.0:9292),或者在 IntelliJ IDEA 中创建新的 HTTP 请求文件:

添加新的 HTTP 端点
在 Project 工具窗口中,导航到 src/main/kotlin 文件夹并按以下步骤操作:
打开 Routing.kt 文件。您应该会看到如下代码:
kotlinfun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }要创建新端点,请如下所示插入附加路由:
kotlinfun Application.configureRouting() { routing { // ... get("/test1") { val text = "<h1>Hello From Ktor</h1>" val type = ContentType.parse("text/html") call.respondText(text, type) } } }请注意,您可以将/test1URL 更改为您喜欢的任何内容。IDE 会自动添加
ContentType的导入:kotlinimport io.ktor.http.ContentType点击重新运行按钮(
)以重新启动应用程序。
在浏览器中请求新的 URL(http://0.0.0.0:9292/test1)。端口号取决于您是否完成了更改默认端口任务。您应该会看到如下所示的输出:

如果您创建了 HTTP 请求文件,也可以在其中验证新端点:
httpGET http://0.0.0.0:9292 ### GET http://0.0.0.0:9292/test1请注意,需要使用包含三个井号(###)的行来分隔不同的请求。
配置静态内容
在 Project 工具窗口中,导航到 src/main/kotlin 文件夹并按以下步骤操作:
打开 Routing.kt 文件并将以下路由添加到 routing 部分:
kotlinfun Application.configureRouting() { routing { staticResources("/content", "mycontent") // ... } }该行的含义如下:
- 调用
staticResources()使您的应用程序能够提供标准网站内容,例如 HTML 和 JavaScript 文件。尽管这些内容可以在浏览器中执行,但从服务器的角度来看,它们被视为静态内容。 - URL
/content指定了用于提取此内容的路径。 - 路径
mycontent是存放静态内容的文件夹名称。Ktor 将在resources目录中查找该文件夹。
- 调用
如果 IDE 未自动添加,请手动添加以下导入:
kotlinimport io.ktor.server.http.content.staticResources在 Project 工具窗口中,右键点击 src/main/resources 文件夹并选择 New | Directory。
或者,选中 src/main/resources 文件夹,按 ⌘Cmd+N(macOS)或 Ctrl+N(Windows/Linux),然后点击 Directory。
将新目录命名为
mycontent并按 ↩Enter 键。右键点击新建的文件夹,然后点击 New | File。
将新文件命名为 sample.html 并按 ↩Enter 键。
使用有效的 HTML 填充新创建的文件页面,例如:
html<html lang="en"> <head> <meta charset="UTF-8" /> <title>My sample</title> </head> <body> <h1>This page is built with:</h1> <ol> <li>Ktor</li> <li>Kotlin</li> <li>HTML</li> </ol> </body> </html>点击重新运行按钮(
)以重新启动应用程序。
当您在浏览器中打开 http://0.0.0.0:9292/content/sample.html 时,应会显示示例页面的内容:

编写集成测试
Ktor 支持创建集成测试了解如何使用专用的测试引擎测试您的服务器应用程序。,并且生成的项目已捆绑了此功能。
若要使用此功能,请按照以下步骤操作:
导航到 src/test/kotlin 文件夹。
打开 ServerTest.kt 文件。您应该会看到如下代码:
kotlinclass ServerTest { @Test fun `test root endpoint`() = testApplication { // 加载默认配置 configure() // 验证服务器根路径返回 200 assertEquals(HttpStatusCode.OK, client.get("/").status) } }testApplication()函数会创建一个新的 Ktor 实例。此实例运行在测试环境中,而不是诸如 Netty 之类的服务器中。然后,您可以使用
configure()函数来调用从embeddedServer()调用的相同设置。最后,您可以使用内置的
client对象和 JUnit 断言来发送示例请求并检查响应。
您可以使用在 IntelliJ IDEA 中执行测试的任何标准方式来运行该测试。请注意,由于您运行的是一个新的 Ktor 实例,因此测试的成功或失败并不取决于您的应用程序是否正在 0.0.0.0 运行。
如果您已成功完成添加新的 HTTP 端点任务,请添加以下测试:
@Test
fun `test new endpoint`() = testApplication {
configure()
val response = client.get("/test1")
assertEquals(HttpStatusCode.OK, response.status)
assertEquals("html", response.contentType()?.contentSubtype)
assertContains(response.bodyAsText(), "Hello From Ktor")
}添加以下附加导入:
import io.ktor.http.contentType
import io.ktor.client.statement.bodyAsText注册错误处理程序
您可以使用 StatusPages 插件StatusPages 允许 Ktor 应用程序根据抛出的异常或状态码对任何失败状态做出适当响应。来处理 Ktor 应用程序中的错误。
在接下来的步骤中,您将学习如何手动添加和配置该插件。实现这一目标包含四个步骤:
添加新依赖项
打开 build.gradle.kts 文件并添加新依赖项,如下所示:
kotlindependencies { implementation(ktorLibs.server.config.yaml) implementation(ktorLibs.server.core) implementation(ktorLibs.server.netty) // 添加新依赖项 implementation(ktorLibs.server.statusPages) implementation(libs.logback.classic) testImplementation(libs.kotlin.test) testImplementation(ktorLibs.server.testHost) }按 Shift+⌘Cmd+I(macOS)或 Ctrl+Shift+O(Windows/Linux)重新加载项目。
在 Project 工具窗口中,导航到项目根文件夹并按以下步骤操作:
安装插件并指定异常处理程序
导航到 Routing.kt 中的
.configureRouting()方法,并添加以下代码行:kotlinfun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... } }这些代码行会安装
StatusPages插件,并指定当引发IllegalStateException类型的异常时应执行的操作。添加以下导入:
kotlinimport io.ktor.server.plugins.statuspages.StatusPages
请注意,通常在响应中会设置 HTTP 错误代码,但出于此任务的目的,输出直接显示在浏览器中。
编写示例代码以触发处理程序
仍在
.configureRouting()方法中,如下所示添加其他路由:kotlinfun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... get("/error-test") { throw IllegalStateException("Too Busy") } } }现在您已添加了一个 URL 为
/error-test的端点。触发此端点时,将引发处理程序中所用类型的异常。
重新启动并调用示例代码
点击重新运行按钮(
)以重新启动应用程序。
在浏览器中,转到 URL http://0.0.0.0:9292/error-test。您应该会看到如下所示的错误消息:

后续步骤
如果您已经完成了所有附加任务,那么现在您已经掌握了配置 Ktor 服务器、集成 Ktor 插件以及实现新路由的方法。然而,这仅仅是个开始。要更深入地了解 Ktor 的核心概念,请继续阅读本指南的下一篇教程。
接下来,您将学习如何通过创建任务管理器应用程序来处理请求并生成响应通过构建一个任务管理器应用程序,学习在 Kotlin 中使用 Ktor 处理路由、请求和形参的基础知识。。
