创建、打开并运行新的 Ktor 项目

代码示例: tutorial-server-get-started

在本教程中，您将学习如何创建、打开并运行 您的第一个 Ktor 服务器项目。一旦项目成功运行，您可以尝试一系列任务来熟悉 Ktor。

这是 Ktor 服务器应用程序系列教程的第一部分，旨在帮助您入门。您可以独立完成每个教程， 但我们强烈建议您按照建议的顺序进行学习：

1. 创建、打开并运行新的 Ktor 项目。
2. 处理请求并生成响应

   通过构建任务管理器应用程序，了解如何使用 Ktor 在 Kotlin 中进行路由、处理请求和参数的基础知识。
   。
3. 创建生成 JSON 的 RESTful API

   了解如何使用 Kotlin 和 Ktor 构建后端服务，其中包括一个生成 JSON 文件的 RESTful API 示例。
   。
4. 使用 Thymeleaf 模板创建网站

   了解如何使用 Kotlin、Ktor 和 Thymeleaf 模板构建网站。
   。
5. 创建 WebSocket 应用程序

   了解如何利用 WebSocket 的强大功能发送和接收内容。
   。
6. 使用 Exposed 集成数据库

   了解使用 Exposed SQL 库将 Ktor 服务连接到数据库版本库的过程。
   。

创建新的 Ktor 项目

创建新的 Ktor 项目最快的方法之一是使用 基于 Web 的 Ktor 项目生成器。

或者，您也可以 使用 IntelliJ IDEA Ultimate 专用的 Ktor 插件 或 Ktor CLI 工具 来生成项目。

使用 Ktor 项目生成器

要使用 Ktor 项目生成器创建新项目，请按照以下步骤操作：

1. 导航到 Ktor 项目生成器。

2. 在 项目构件 字段中，输入 com.example.ktor-sample-app 作为您的项目构件名称。

3. 点击 配置 以打开设置下拉菜单：

   可用的设置如下：

   • 构建系统 ： 选择所需的

     构建系统

     了解如何将 Ktor Server 依赖项添加到现有 Gradle/Maven 项目。
     。 可以是使用 Kotlin 或 Groovy DSL 的 Gradle ，或者 Maven 。

   • Ktor 版本 ： 选择所需的 Ktor 版本。

   • 引擎 ： 选择用于运行服务器的

     引擎

     了解处理网络请求的引擎。
     。

   • 配置 ： 选择是在

     YAML 或 HOCON 文件中

     了解如何在配置文件中配置各种服务器参数。
     ，还是
     在代码中

     了解如何在代码中配置各种服务器参数。
     指定服务器参数。

   • 包含示例 ： 勾选此选项以添加插件的示例代码。

   对于本教程，您可以保留这些设置的默认值。

4. 点击 完成 以保存配置并关闭菜单。

5. 下方您会看到一组可以添加到项目中 的

   插件

   插件提供常见功能，例如序列化、内容编码、压缩等。
   。插件是 Ktor 应用程序中提供常见功能的构建块， 例如身份验证、序列化和内容编码、压缩、Cookie 支持等等。

   为了本教程的目的，您在此阶段无需添加任何插件。

6. 点击 下载 按钮生成并下载您的 Ktor 项目。

您的下载应自动开始。

现在您已经生成了新项目，请继续解压并运行您的 Ktor 项目。

使用 IntelliJ IDEA Ultimate 的 Ktor 插件

本节介绍如何使用 Intellij IDEA Ultimate 的 Ktor 插件进行项目设置。

要创建新的 Ktor 项目， 打开 IntelliJ IDEA，然后 按照以下步骤操作：

1. 在欢迎屏幕上，点击新建项目。

   或者，从主菜单中选择 文件 | 新建 | 项目。

2. 在 新建项目 向导中，从左侧列表中选择 Ktor 。

3. 在右侧窗格中，您可以指定以下设置：

   

   • 名称 ： 指定项目名称。输入 ktor-sample-app 作为您的项目名称。

   • 位置 ： 指定项目目录。

   • 网站 ： 指定用于生成包名的域。

   • 构件 ： 此字段显示生成的构件名称。

   • 引擎 ： 选择用于运行服务器的

     引擎

     了解处理网络请求的引擎。
     。

   • 包含示例 ： 勾选此选项以添加插件的示例代码。

4. 点击 高级设置 以展开 附加设置菜单：

   

   可用的设置如下：

   • 构建系统 ： 选择所需的

     构建系统

     了解如何将 Ktor Server 依赖项添加到现有 Gradle/Maven 项目。
     。 可以是使用 Kotlin 或 Groovy DSL 的 Gradle ，或者 Maven 。

   • Ktor 版本 ： 选择所需的 Ktor 版本。

   • 配置 ： 选择是在

     YAML 或 HOCON 文件中

     了解如何在配置文件中配置各种服务器参数。
     ，还是
     在代码中

     了解如何在代码中配置各种服务器参数。
     指定服务器参数。

   为了本教程的目的，您可以保留这些设置的默认值。

5. 点击 下一步 进入下一页。

   

   在此页面上，您可以选择一组

   插件

   插件提供常见功能，例如序列化、内容编码、压缩等。
   ——它们是提供 Ktor 应用程序常见功能的构建块，例如 身份验证、序列化和内容编码、压缩、Cookie 支持等等。

   为了本教程的目的，您在此阶段无需添加任何插件。

6. 点击 创建 并等待 IntelliJ IDEA 生成项目并 安装依赖项。

现在您已经创建了新项目，请继续学习如何打开、 探索并运行 该应用程序。

使用 Ktor CLI 工具

本节介绍如何使用 Ktor CLI 工具进行项目设置。

要创建新的 Ktor 项目，请打开您选择的终端并 按照以下步骤操作：

1. 使用以下命令之一安装 Ktor CLI 工具：
   macOS/LinuxWindows
2. 要在交互模式下生成新项目，请使用以下命令：
3. 输入 ktor-sample-app 作为您的项目名称：

   （可选）您还可以通过编辑项目名称下方的 位置 路径来更改项目保存的位置。

4. 按下 键继续。
5. 在下一步中，您可以搜索并向项目添加
   插件

   插件提供常见功能，例如序列化、内容编码、压缩等。
   。插件是 Ktor 应用程序中提供常见功能的构建块， 例如身份验证、序列化和内容编码、压缩、Cookie 支持等等。

   为了本教程的目的，您在此阶段无需添加任何插件。

6. 按下 生成项目。

   或者，您可以通过选择 创建项目 (CTRL+G) 并按下 键来生成项目。

解压并运行您的 Ktor 项目

本节将介绍如何从命令行解压、构建和运行项目。以下 说明假设：

1. 您已创建并下载了一个名为 ktor-sample-app 的项目。
2. 该项目已放置在您的主目录中名为 myprojects 的文件夹下。

如有必要，请修改名称和路径以匹配您自己的设置。

打开您选择的命令行工具并按照步骤操作：

1. 在终端中，导航到您下载项目的文件夹：

2. 将 ZIP 压缩包解压到同名文件夹中：

   macOSWindows

   您的目录现在将包含 ZIP 压缩包和解压后的文件夹。

3. 从当前目录进入新创建的文件夹：

4. 在 macOS/UNIX 系统上，您需要使 gradlew Gradle 辅助脚本可执行。为此， 请使用 chmod 命令：

   macOS

5. 要构建项目，请使用以下命令：

   macOSWindows

   如果您看到构建成功，则可以再次通过 Gradle 执行项目。

6. 要运行项目，请使用以下命令：

   macOSWindows

7. 要验证项目是否正在运行，请在输出中提到的 URL (http://0.0.0.0:8080) 打开浏览器。 您应该会在屏幕上看到“Hello World!”消息：

   

恭喜！您已成功启动 Ktor 项目。

请注意，命令行将无响应，因为底层进程正在忙于运行 Ktor 应用程序。您可以 按下 来终止应用程序。

在 IntelliJ IDEA 中打开、探索并运行您的 Ktor 项目

打开项目

如果您的计算机上安装了 IntelliJ IDEA，您可以轻松地从命令行 打开项目。

请确保您位于项目文件夹中，然后键入 idea 命令，后跟一个句点表示当前 文件夹：

或者，您也可以手动启动 IntelliJ IDEA 来打开项目。

如果欢迎屏幕打开，点击 打开 。否则，请从主菜单中选择 文件 | 打开 ，然后选择 ktor-sample-app 文件夹打开它。

TIP

有关管理项目的更多详细信息， 请参见 IntelliJ IDEA 文档。

探索项目

无论您选择哪种方式，项目都应如下图所示打开：

为了解释项目布局，我们已在 项目 视图中展开了结构并选中了 settings-gradle.kts 文件。

您会看到运行应用程序的代码位于 src/main/kotlin 下的包中。默认包名为 com.example ，其中包含一个名为 plugins 的子包。 这两个包中创建了两个文件，分别命名为 Application.kt 和 Routing.kt

项目名称在 settings-gradle.kts 中配置。

配置文件和其他类型的内容位于 src/main/resources 文件夹中。

一个骨架测试已在 src/test/kotlin 下的包中创建。

运行项目

要在 IntelliJ IDEA 中运行项目：

1. 通过点击右侧边栏上的 Gradle 图标 () 打开 Gradle 工具 窗口。

   

2. 在此工具窗口中，导航到 任务 | application 并双击 run 任务。

   

3. 您的 Ktor 应用程序将在 IDE 底部的 运行工具窗口中启动：

   

   之前在命令行中显示的消息现在将显示在 运行 工具窗口中。

4. 要确认项目正在运行，请在指定 URL (http://0.0.0.0:8080) 处打开您的浏览器。

   您应该会再次看到屏幕上显示“Hello World!”消息：

   

您可以通过 运行 工具窗口管理应用程序。

1. 要终止应用程序，请点击停止按钮
2. 要重新启动进程，请点击重新运行按钮

这些选项在 IntelliJ IDEA 运行 工具窗口文档中有进一步解释。

可尝试的附加任务

以下是一些您可能希望尝试的附加任务：

1. 更改默认端口。
2. 通过 YAML 更改端口。
3. 添加新的 HTTP 端点。
4. 配置静态内容。
5. 编写集成测试。
6. 注册错误处理器。

这些任务彼此独立，但复杂性逐渐增加。按照声明的顺序尝试它们是 逐步学习的最简单方法。为简单起见，并避免重复，以下说明 假设您按顺序尝试这些任务。

需要编码的地方，我们已同时指定了代码和相应的导入。IDE 可能会为您 自动添加这些导入。

更改默认端口

在项目 视图中，导航到 src/main/kotlin 文件夹，然后进入为您创建的单个包并按照步骤操作：

1. 打开 Application.kt 文件。您应该会找到类似以下的代码：

2. 在 embeddedServer() 函数中，将 port 形参 更改为您选择的另一个数字，例如“9292”。

3. 点击重新运行按钮 () 以重新启动应用程序。

4. 要验证您的应用程序是否正在新的端口号下运行，您可以在新 URL (http://0.0.0.0:9292) 打开浏览器，或者 在 IntelliJ IDEA 中创建 新的 HTTP 请求文件：

   

通过 YAML 更改端口

创建新的 Ktor 项目时，您可以选择将配置外部存储在 YAML 或 HOCON 文件中：

如果您选择将配置外部存储，那么 Application.kt 中的代码将是这样：

这些值将存储在 src/main/resources/ 目录中的配置文件中：

application.yaml (YAML)application.conf (HOCON)

在这种情况下，您无需更改任何代码即可更改端口号。只需修改 YAML 或 HOCON 文件中的值并重新启动应用程序即可。更改可以通过与上述默认端口 相同的方式进行验证。

添加新的 HTTP 端点

接下来，您将创建一个新的 HTTP 端点，它将响应 GET 请求。

在项目 工具窗口中，导航到 src/main/kotlin/com/example 文件夹并按照步骤操作：

1. 打开 Application.kt 文件并找到 configureRouting() 函数。

2. 在 IntelliJ IDEA 中，将光标放在函数名称上并按下 即可导航到 configureRouting() 函数。

   或者，您可以通过打开 Routing.kt 文件来导航到该函数。

   您应该会看到以下代码：

3. 要创建新端点，请插入以下所示的额外五行代码：

   请注意，您可以将 /test1 URL 更改为您喜欢的任何内容。

4. 为了使用 ContentType，请添加以下导入：

5. 点击重新运行按钮 () 以重新启动应用程序。

6. 在浏览器中请求新 URL (http://0.0.0.0:9292/test1)。您应该使用的 端口号取决于您是否已尝试第一个任务（更改默认端口）。您应该会看到以下输出：

   

   如果您已创建 HTTP 请求文件，您也可以在那里验证新端点：

   

   请注意，需要一行包含三个哈希符号（###）来分隔不同的请求。

配置静态内容

在项目 工具窗口中，导航到 src/main/kotlin/com/example/plugins 文件夹并按照步骤操作：

1. 打开 Routing.kt 文件。

   同样，这应该是默认内容：

   对于此任务，您是否已插入“添加新的 HTTP 端点”中指定的额外端点内容并不重要。

2. 将以下行添加到路由部分：

   此行的含义如下：

   1. 调用 staticResources() 告诉 Ktor，我们希望应用程序能够提供标准的网站内容，例如 HTML 和 JavaScript 文件。尽管这些内容可以在浏览器中执行，但从 服务器的角度来看，它被认为是静态的。
   2. URL /content 指定了用于获取此内容的路径。
   3. 路径 mycontent 是静态内容将驻留的文件夹名称。Ktor 会在 resources 目录中查找此 文件夹。

3. 添加以下导入：

4. 在 项目 工具窗口中，右键点击 src/main/resources 文件夹并选择 新建 | 目录 。

   或者，选择 src/main/resources 文件夹，按下 ，然后点击 目录 。

5. 将新目录命名为 mycontent 并按下 键。

6. 右键点击新创建的文件夹并点击 新建 | 文件 。

7. 将新文件命名为“sample.html”并按下 键。

8. 使用有效的 HTML 内容填充新创建的文件页面，例如：

9. 点击重新运行按钮 () 以重新启动应用程序。

10. 当您在 http://0.0.0.0:9292/content/sample.html 打开浏览器时，应该会显示您的示例页面内容：

    

编写集成测试

Ktor 提供了

创建集成测试

%plugin_name% 允许 Ktor 应用程序根据抛出的异常或状态码适当地响应任何故障状态。

的支持，并且您生成的项目捆绑了此功能。

要使用此功能，请按照以下步骤操作：

1. 在 src 下创建一个名为“test”的新目录，并在其下创建一个名为“kotlin”的子目录。

2. 在 src/test/kotlin 内部创建一个名为“com.example”的新包。

3. 在 src/test/kotlin/com.example 中创建一个名为“ApplicationTest.kt”的新文件。

4. 打开 ApplicationTest.kt 文件并添加以下代码：

   testApplication() 方法创建 Ktor 的新实例。此实例在测试环境中运行，而 不是像 Netty 这样的服务器中运行。

   然后，您可以使用 application() 方法来调用与 embeddedServer() 中调用的相同设置。

   最后，您可以使用内置的 client 对象和 JUnit 断言来发送示例请求并检测响应。

5. 添加以下所需的导入：

该测试可以通过 IntelliJ IDEA 中执行测试的任何标准方式运行。请注意，由于您正在运行 Ktor 的新实例，因此测试的成功或失败不取决于您的应用程序是否在 0.0.0.0 上运行。

如果您已成功完成添加新的 HTTP 端点任务， 您应该能够添加此附加测试：

需要以下附加导入：

注册错误处理器

您可以使用

StatusPages 插件

%plugin_name% 允许 Ktor 应用程序根据抛出的异常或状态码适当地响应任何故障状态。

在 Ktor 应用程序中处理错误。

此插件默认不包含在您的项目中。您本可以通过 Ktor 项目生成器中的插件部分或 IntelliJ IDEA 中的项目向导将其添加到您的项目中。由于您已经创建了项目，接下来的步骤 将教您如何手动添加和配置该插件。

实现此目标需要四个步骤：

1. 在 Gradle 构建文件中添加新的依赖项。
2. 安装插件并指定异常处理器。
3. 编写示例代码以触发处理器。
4. 重新启动并调用示例代码。

在 项目 工具窗口中，导航到项目根文件夹并按照步骤操作：

1. 打开 build.gradle.kts 文件。

2. 在 dependencies 部分添加额外的依赖项，如下所示：

   完成此操作后，您需要重新加载项目以识别此新依赖项。

3. 通过在 macOS 上按下 或在 Windows 上按下 来重新加载项目。

1. 导航到 Routing.kt 中的 configureRouting() 方法并添加以下代码行：

   这些行安装 StatusPages 插件并指定当抛出 IllegalStateException 类型的异常时要采取的操作。

2. 添加以下导入：

请注意，HTTP 错误代码通常会在响应中设置，但出于此任务的目的，输出将直接显示在浏览器中。

1. 在 configureRouting() 方法中，添加以下所示的额外行：

   您现在已添加了一个 URL 为 /error-test 的端点。当此端点被触发时，将 抛出处理器中使用的类型的异常。

1. 点击重新运行按钮 () 以重新启动应用程序。

2. 在您的浏览器中，导航到 URL http://0.0.0.0:9292/error-test。 您应该会看到如下所示的错误消息：

   

后续步骤

如果您已完成附加任务，您现在应该掌握了 Ktor 服务器的配置、Ktor 插件的集成以及新路由的实现。然而，这仅仅是开始。要深入了解 Ktor 的基础概念，请继续学习本指南中的下一个教程。

接下来，您将学习如何通过创建任务管理器应用程序来

处理请求并 生成响应

通过构建任务管理器应用程序，了解如何使用 Ktor 在 Kotlin 中进行路由、处理请求和参数的基础知识。

。