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

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

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

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

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

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

   通过构建一个任务管理器应用程序，学习 Ktor 中关于路由、处理请求以及形参的基础知识。
   。
3. 创建生成 JSON 的 RESTful API

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

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

   学习如何利用 WebSocket 的力量发送和接收内容。
   。
6. 使用 Exposed 集成数据库

   学习使用 Exposed SQL 库将 Ktor 服务连接到数据库仓库的过程。
   。

创建新的 Ktor 项目

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

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

使用 Ktor 项目生成器

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

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

2. 在 Project artifact 字段中，输入 com.example.ktor-sample 作为项目标识的名称。

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

   提供以下设置：

   • Build System： 选择所需的

     构建系统

     学习如何向现有的 Gradle/Maven 项目中添加 Ktor Server 依赖项。
     。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

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

     引擎

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

   • Configuration： 选择是

     在 YAML 或 HOCON 文件中

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

     学习如何在代码中配置各种服务器参数。
     指定服务器参数。
     目前基于 Maven 的 Ktor 项目不支持 YAML 配置。

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

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

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

   插件

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

   就本教程而言，您目前不需要添加任何插件。

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

下载应会自动开始。

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

使用 IntelliJ IDEA Ultimate 的 Ktor 插件

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

要创建一个新的 Ktor 项目，请 打开 IntelliJ IDEA 并按照以下步骤操作：

1. 在欢迎屏幕上，点击 New Project。

   或者，从主菜单中选择 File | New | Project。

2. 在 New Project 向导中，从左侧列表中选择 Ktor。

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

   

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

   • Location：为您的项目指定一个目录。

   • Website： 指定用于生成软件包名称的域名。

   • Artifact： 此字段显示生成的项目标识名称。

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

     引擎

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

   • Include samples： 保持启用此选项以添加插件的示例代码。

4. 点击 Advanced Settings 以展开额外设置菜单：

   

   提供以下设置：

   • Build System： 选择所需的

     构建系统

     学习如何向现有的 Gradle/Maven 项目中添加 Ktor Server 依赖项。
     。 可以是 Gradle Kotlin、 Gradle Groovy、 Maven 或 Amper。

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

   • Configuration： 选择是

     在 YAML 或 HOCON 文件中

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

     学习如何在代码中配置各种服务器参数。
     指定服务器参数。
     目前基于 Maven 的 Ktor 项目不支持 YAML 配置。

   就本教程而言，您可以保留这些设置的默认值。

5. 点击 Next 进入下一页。

   

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

   插件

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

   就本教程而言，您目前不需要添加任何插件。

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

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

使用 Ktor CLI 工具

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

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

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

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

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

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

   就本教程而言，您目前不需要添加任何插件。

6. 按 CTRL+G 生成项目。

   或者，您可以通过选择 CREATE PROJECT (CTRL+G) 并按 Enter 来生成项目。

解压缩并运行您的 Ktor 项目

在本节中，您将学习如何从命令行解压缩、构建和运行项目。以下步骤假设：

1. 您已创建并下载了一个名为 ktor-sample 的 Gradle 项目。
2. 该项目位于主目录中名为 myprojects 的文件夹内。

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

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

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

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

   macOSWindows

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

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

4. 在 macOS 和 UNIX 系统上，您必须使 Gradle 辅助脚本具有可执行权限，以便系统将其识别为可运行命令。为此，请使用 chmod 命令：

   macOS

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

   macOSWindows

   构建成功后，继续执行下一步以运行项目。

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

   macOSWindows

7. 要验证项目是否正在运行，请在浏览器中打开终端输出显示的 URL（http://0.0.0.0:8080）。 您应该在浏览器中看到显示的消息 "Hello World!"：

   

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

NOTE

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

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

打开项目

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

确保您位于项目文件夹中，然后输入 idea 命令，后跟一个点（代表当前文件夹）：

或者，要手动打开项目，请启动 IntelliJ IDEA。

如果显示欢迎屏幕，请点击 Open。否则，前往主菜单中的 File | Open 并选择 ktor-sample 文件夹以将其打开。

TIP

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

探索项目

打开项目后，您可以看到以下结构：

要查看完整布局，请点击每个文件夹旁边的展开箭头，展开 Project 视图中的文件夹。

应用程序源代码位于 src/main/kotlin 目录下。默认创建了两个文件，分别名为 Application.kt 和 Routing.kt。

项目的名称在 settings.gradle.kts 文件中配置：

配置文件以及其他类型的内容存放在 src/main/resources 文件夹内。

运行项目

要在 IntelliJ IDEA 内部运行项目：

1. 点击右侧侧边栏上的 Gradle 图标（）打开 Gradle 工具窗口。

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

   

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

   

   之前在命令行上显示的相同消息现在将在 Run 工具窗口中可见。

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

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

   

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

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

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

尝试其他任务

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

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

这些任务彼此不依赖，但复杂程度逐渐增加。按声明的顺序尝试它们是递进学习最简单的方法。为简单起见并避免重复，下面的描述假设您按顺序尝试任务。

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

更改默认端口

在配置文件中更改端口

如果您选择将配置存储在外部的 YAML 或 HOCON 文件中，请在 Project 视图中导航到 src/main/resources 文件夹并按照以下步骤操作：

1. 打开您的配置文件（ application.yaml 或 application.conf ）。它应该如下所示：
   application.yaml (YAML)application.conf (HOCON)
2. 将文件中的 port 值更改为您选择的另一个数字，例如 9292。

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

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

   

在代码中更改端口

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

如果您选择了在代码中存储配置的选项，请在 Project 视图中导航到 src/main/kotlin 文件夹并按照以下步骤操作：

1. 打开 main.kt 文件。您应该会发现类似以下内容的代码：

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

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

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

   

添加新的 HTTP 端点

在 Project 工具窗口中，导航到 src/main/kotlin 文件夹并按照以下步骤操作：

1. 打开 Routing.kt 文件。您应该看到以下代码：

2. 要创建新端点，请按照下文所示插入额外的路由：

   NOTE

   请注意，您可以根据需要将 /test1 URL 更改为任何您喜欢的名称。

3. IDE 会自动添加 ContentType 的导入：

4. 点击重新运行按钮（）以重新启动应用程序。

5. 在浏览器中请求新的 URL（http://0.0.0.0:9292/test1）。端口号取决于您是否完成了 更改默认端口 任务。您应该看到如下所示的输出：

   

   如果您创建了 HTTP 请求文件，也可以在其中验证新端点：

   NOTE

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

配置静态内容

在 Project 工具窗口中，导航到 src/main/kotlin 文件夹并按照以下步骤操作：

1. 打开 Routing.kt 文件并在路由部分添加以下路由：

   这一行的含义如下：

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

2. 如果 IDE 没有自动添加，请添加以下导入。

3. 在 Project 工具窗口中，右键点击 src/main/resources 文件夹并选择 New | Directory。

   或者，选择 src/main/resources 文件夹，按 ⌘Cmd+N (macOS) 或 Ctrl+N (Windows/Linux) 并点击 Directory。

4. 将新目录命名为 mycontent 并按 ↩Enter。

5. 右键点击新创建的文件夹并点击 New | File。

6. 将新文件命名为 sample.html 并按 ↩Enter。

7. 在新创建的文件中填充有效的 HTML，例如：

8. 点击重新运行按钮（）以重新启动应用程序。

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

   

编写集成测试

Ktor 支持

创建集成测试

了解如何使用特殊的测试引擎测试服务器应用程序。

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

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

1. 导航至 src/test/kotlin 文件夹。

2. 打开 ServerTest.kt 文件。您应该看到以下代码：

   testApplication() 函数创建一个新的 Ktor 实例。该实例运行在测试环境中，而不是像 Netty 这样的服务器中。

   然后您可以使用 configure() 函数来调用与 embeddedServer() 中调用的相同的设置。

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

您可以使用在 IntelliJ IDEA 中执行测试的任何标准方式运行测试。请注意，因为您正在运行一个新的 Ktor 实例，所以测试的成功或失败并不取决于您的应用程序是否正在 0.0.0.0 运行。

如果您已成功完成了 添加新的 HTTP 端点，请添加此额外测试：

添加以下额外的导入：

注册错误处理程序

您可以使用

StatusPages 插件

StatusPages 允许 Ktor 应用程序根据抛出的异常或状态码适当地响应任何失败状态。

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

TIP

默认情况下，您的项目中不包含此插件。您可以在使用 Ktor 项目生成器或 IntelliJ IDEA 中的项目向导创建项目时，通过 Plugins 部分将其添加到您的项目中。

在接下来的步骤中，您将学习如何手动添加和配置该插件。实现此目标共有四个步骤：

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

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

1. 打开 build.gradle.kts 文件并按下文所示添加新依赖项：

2. 通过按 Shift+⌘Cmd+I (macOS) 或 Ctrl+Shift+O (Windows/Linux) 重新加载项目。

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 中关于路由、处理请求以及形参的基础知识。

。