Skip to content

使用 Ktor 和 Kotlin 处理 HTTP 请求并生成响应

在本教程中,你将通过构建一个任务管理器应用程序,学习在 Kotlin 中使用 Ktor 处理路由、请求和形参的基础知识。

学完本教程后,你将掌握以下内容:

  1. 处理 GET 和 POST 请求。
  2. 从请求中提取信息。
  3. 在转换数据时处理错误。
  4. 使用单元测试来验证路由。

先决条件

这是“Ktor Server 入门”指南的第二个教程。你可以独立完成本教程,但我们强烈建议你先完成上一篇教程,了解如何创建、打开并运行新的 Ktor 项目了解如何使用 Ktor 打开、运行和测试服务器应用程序。。

对 HTTP 请求类型、请求头和状态码有基本的了解也会有所帮助。

我们建议你安装 IntelliJ IDEA,但你也可以使用自选的其他 IDE。

任务管理器应用程序

在本教程中,你将逐步构建一个具有以下功能的任务管理器应用程序:

  1. 以 HTML 表格的形式查看所有可用任务。
  2. 按优先级和名称查看任务(同样以 HTML 呈现)。
  3. 通过提交 HTML 表单来添加额外任务。

你将先以最简可行的方式实现一些基本功能,然后在接下来的七个迭代中不断改进和扩展该功能。该最简功能由一个包含若干模型类型、一个值列表以及单个路由的项目组成。

显示静态 HTML 内容

在第一个迭代中,你将向应用程序添加一个返回静态 HTML 内容的新路由。

使用 Ktor Project Generator,创建一个新项目,并将 com.example.ktor-task-app 指定为 Project artifact 名称。

有关创建新项目的更多信息,请参阅创建、打开并运行新的 Ktor 项目了解如何使用 Ktor 打开、运行和测试服务器应用程序。。如果你最近刚完成了该教程,可以随意复用在那里创建的项目。
  1. 打开 src/main/kotlin 文件夹中的 Routing.kt 文件。
  2. 将现有的 Application.configureRouting() 函数替换为以下实现:

    kotlin
    fun Application.configureRouting() {
        routing {
            get("/tasks") {
                call.respondText(
                    contentType = ContentType.parse("text/html"),
                        text = """
                    <h3>TODO:</h3>
                    <ol>
                        <li>A table of all the tasks</li>
                        <li>A form to submit new tasks</li>
                    </ol>
                    """.trimIndent()
                )
            }
        }
    }

    这样,你就为 URL /tasks 和 GET 请求类型创建了一个新路由。GET 请求是 HTTP 中最基本的请求类型。当用户在浏览器地址栏中输入内容或点击普通的 HTML 链接时,都会触发此类请求。

    目前,你只需返回静态内容即可。为了通知客户端你将发送 HTML,需要将 HTTP 的 Content-Type 请求头设置为 "text/html"。

  3. IDE 会自动添加以下导入语句以便访问 ContentType 对象:

    kotlin
    import io.ktor.http.ContentType
  4. 在 IntelliJ IDEA 中,点击 main.kt 文件中 main() 函数旁边的运行装订区域图标(IntelliJ IDEA run application icon)来启动应用程序。

  5. 在浏览器中导航到 http://0.0.0.0:8080/tasks。你应该会看到显示的待办事项列表:

    A browser window displaying a to-do list with two items

实现任务模型

创建项目并设置好基本路由后,接下来你将通过以下步骤来扩展应用程序:

  1. 创建表示任务的模型类型。
  2. 声明包含示例值的任务列表。
  3. 修改路由和请求处理程序以返回此列表。
  4. 使用浏览器测试新功能是否正常工作。

创建模型类型

  1. 在 src/main/kotlin 内,创建一个名为 model 的新子包。

  2. 在 model 目录内,创建一个新的 Task.kt 文件。

  3. 打开 Task.kt 文件,添加以下表示优先级的 enum 以及表示任务的 class:

    kotlin
    package com.example.model
    
    enum class Priority {
        Low, Medium, High, Vital
    }
    
    data class Task(
        val name: String,
        val description: String,
        val priority: Priority
    )
  4. 你将使用 HTML 表格将任务信息发送给客户端。在同一个 Task.kt 文件中,添加以下扩展函数:

    kotlin
    fun Task.taskAsRow() = """
        <tr>
            <td>$name</td><td>$description</td><td>$priority</td>
        </tr>
        """.trimIndent()
    
    fun List<Task>.tasksAsTable() = this.joinToString(
        prefix = "<table rules=\"all\">",
        postfix = "</table>",
        separator = "\n",
        transform = Task::taskAsRow
    )
    • Task.taskAsRow() 函数使 Task 对象能够呈现为表格行。
    • List<Task>.tasksAsTable() 函数允许将任务列表呈现为表格。

创建示例值

  1. 在你的 model 目录内,创建一个新的 TaskRepository.kt 文件。

  2. 打开 TaskRepository.kt 并添加以下代码来定义任务列表:

    kotlin
    package com.example.model
    
        private val tasks = mutableListOf(
            Task("cleaning", "Clean the house", Priority.Low),
            Task("gardening", "Mow the lawn", Priority.Medium),
            Task("shopping", "Buy the groceries", Priority.High),
            Task("painting", "Paint the fence", Priority.Medium)
        )

添加新路由

  1. 打开 Routing.kt 文件,并将现有的 Application.configureRouting() 函数替换为以下实现:

    kotlin
    fun Application.configureRouting() {
        routing {
            get("/tasks") {
                call.respondText(
                    contentType = ContentType.parse("text/html"),
                    text = tasks.tasksAsTable()
                )
            }
        }
    }

    此时你向客户端提供的不再是静态内容,而是一个任务列表。由于列表无法直接通过网络发送,因此必须将其转换为客户端能够理解的格式。在此示例中,任务被转换为了 HTML 表格。

  2. 添加所需的导入语句:

    kotlin
    import com.example.model.*

测试新功能

  1. 在 IntelliJ IDEA 中,点击重新运行按钮(IntelliJ IDEA rerun button icon)以重启应用程序。

  2. 在浏览器中导航到 http://0.0.0.0:8080/tasks。页面应显示包含任务的 HTML 表格:

    A browser window displaying a table with four rows

    如果显示正常,祝贺你!应用程序的基本功能已正常运行。

重构模型

在继续扩展应用程序的功能之前,你将通过把值列表封装在仓库(Repository)中来重构设计。这将使你能够集中管理数据,从而将精力集中在 Ktor 专属的代码上。

  1. 返回 TaskRepository.kt 文件,并将现有的任务列表替换为以下代码:

    kotlin
    package com.example.model
    
    object TaskRepository {
    
        private val tasks = mutableListOf(
            Task("cleaning", "Clean the house", Priority.Low),
            Task("gardening", "Mow the lawn", Priority.Medium),
            Task("shopping", "Buy the groceries", Priority.High),
            Task("painting", "Paint the fence", Priority.Medium)
        )
        fun allTasks(): List<Task> = tasks.toList()
    
        fun tasksByPriority(priority: Priority) = tasks.filter {
            it.priority == priority
        }
    
        fun taskByName(name: String) = tasks.find {
            it.name.equals(name, ignoreCase = true)
        }
    
        fun addTask(task: Task) {
            if(taskByName(task.name) != null) {
                throw IllegalStateException("Cannot duplicate task names!")
            }
            tasks.add(task)
        }
    }

    这基于列表实现了一个基本的任务数据存储。出于演示目的,任务添加的顺序将被保留,但通过抛出异常来禁止重复项。

    在随后的教程中,你将学习如何实现通过 Exposed 库连接到关系型数据库的仓库。

    现在,你将在路由内部使用该仓库。

  2. 打开 Routing.kt 文件,并将现有的 Application.configureRouting() 函数替换为以下实现:

    kotlin
    fun Application.configureRouting() {
        routing {
            get("/tasks") {
                val tasks = TaskRepository.allTasks()
                call.respondText(
                    contentType = ContentType.parse("text/html"),
                    text = tasks.tasksAsTable()
                )
            }
        }
    }

    当请求到达时,将使用仓库获取当前的任务列表。然后,构建一个包含这些任务的 HTTP 响应。

测试重构后的代码

  1. 在 IntelliJ IDEA 中,点击重新运行按钮(IntelliJ IDEA rerun button icon)以重启应用程序。

  2. 在浏览器中导航到 http://0.0.0.0:8080/tasks。输出应保持不变,仍旧显示 HTML 表格:

    A browser window displaying a table with four rows

处理形参

在本次迭代中,你将允许用户按优先级查看任务。为此,你的应用程序必须允许对以下 URL 的 GET 请求:

  1. /tasks/byPriority/Low
  2. /tasks/byPriority/Medium
  3. /tasks/byPriority/High
  4. /tasks/byPriority/Vital

你需要添加的路由是 /tasks/byPriority/{priority?} ,其中 {priority?} 表示你需要在运行时提取的路径形参,问号用于表示该形参是可选的。路径形参可以命名为你喜欢的任何名称,但 priority 显然是最合适不过的选择。

处理该请求的过程可概括如下:

  1. 从请求中提取名为 priority 的路径形参。
  2. 如果该形参不存在,则返回 400 Bad Request 状态。
  3. 将该形参的文本值转换为 Priority 枚举值。
  4. 如果转换失败,则返回带有 400 状态码的响应。
  5. 使用仓库查找具有指定优先级的所有任务。
  6. 如果没有匹配的任务,则返回 404 Not Found 状态。
  7. 返回格式化为 HTML 表格的匹配任务。

你将首先实现此功能,然后寻找验证其是否正常工作的最佳方式。

添加新路由

    打开 Routing.kt 文件,并将以下路由添加到你的代码中:

    kotlin
    routing {
        get("/tasks") {
            //...
        }
    
        //add the following route
        get("/tasks/byPriority/{priority?}") {
            val priorityAsText = call.parameters["priority"]
            if (priorityAsText == null) {
                call.respond(HttpStatusCode.BadRequest)
                return@get
            }
    
            try {
                val priority = Priority.valueOf(priorityAsText)
                val tasks = TaskRepository.tasksByPriority(priority)
    
                if (tasks.isEmpty()) {
                    call.respond(HttpStatusCode.NotFound)
                    return@get
                }
    
                call.respondText(
                    contentType = ContentType.parse("text/html"),
                    text = tasks.tasksAsTable()
                )
            } catch(ex: IllegalArgumentException) {
                call.respond(HttpStatusCode.BadRequest)
            }
        }
    }

    通过上述代码,你编写了一个针对 URL /tasks/byPriority/{priority?} 的处理程序。符号 priority 表示用户添加的路径形参。遗憾的是,在服务器端无法保证该值一定是对应 Kotlin 枚举中的四个值之一,因此必须手动进行检查。

    如果路径形参不存在,服务器会向客户端返回 400 状态码。否则,它会提取该形参的值,并尝试将其转换为枚举成员。如果转换失败,则会抛出异常,服务器会捕获该异常并返回 400 状态码。

    假定转换成功,就会使用仓库查找匹配的 Tasks。如果不存在具有指定优先级的任务,服务器将返回 404 状态码,否则它会将匹配项放入 HTML 表格中返回。

测试新路由

    你可以通过在浏览器中请求不同的 URL 来测试该功能。

  1. 在 IntelliJ IDEA 中,点击重新运行按钮(IntelliJ IDEA rerun button icon)以重启应用程序。

  2. 要检索所有中等优先级的任务,请导航到 http://0.0.0.0:8080/tasks/byPriority/Medium:

    A browser window displaying a table with Medium priority tasks
  3. 遗憾的是,在发生错误时,你通过浏览器能做的测试非常有限。除非使用开发者扩展,否则浏览器不会显示失败响应的详细信息。更简单的替代方案是使用专业工具,例如 Postman。

  4. 在 Postman 中,针对相同的 URL http://0.0.0.0:8080/tasks/byPriority/Medium 发送一个 GET 请求。

    A GET request in Postman showing the response details

    这将显示来自服务器的原始输出,以及请求和响应的所有详细信息。

  5. 要检查在请求至关重要的任务(Vital)时是否返回 404 状态码,请发送一个新的 GET 请求到 http://0.0.0.0:8080/tasks/byPriority/Vital 。随后你将看到状态码显示在 Response 面板的右上角。

    A GET request in Postman showing the status code
  6. 要验证在指定无效优先级时是否会返回 400 状态码,请使用无效属性创建另一个 GET 请求:

    A GET request in Postman with a Bad Request status code

添加单元测试

到目前为止,你已经添加了两个路由——一个用于检索所有任务,另一个用于按优先级检索任务。像 Postman 这样的工具虽然能让你对这些路由进行全面测试,但它们需要手动检查,并且是在 Ktor 外部运行的。

这在原型设计和小型应用程序中是可以接受的。然而,这种方式无法扩展到可能需要频繁运行数千个测试的大型应用程序。更好的解决方案是实现测试的全自动化。

Ktor 提供了自带的测试框架了解如何使用专用的测试引擎测试您的服务器应用程序。以支持路由的自动化验证。接下来,你将为应用程序的现有功能编写一些测试。

  1. 导航到 src/test/kotlin 文件夹并打开 ServerTest.kt 文件。

  2. 将以下代码添加到 ServerTest.kt 文件中:

    kotlin
    package com.example
    
    import io.ktor.client.request.get
    import io.ktor.client.request.header
    import io.ktor.client.request.post
    import io.ktor.client.request.setBody
    import io.ktor.client.statement.bodyAsText
    import io.ktor.http.ContentType
    import io.ktor.http.HttpHeaders
    import io.ktor.http.HttpStatusCode
    import io.ktor.http.formUrlEncode
    import io.ktor.server.testing.testApplication
    import kotlin.test.*
    
    class ServerTest {
        @Test
        fun tasksCanBeFoundByPriority() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Medium")
            val body = response.bodyAsText()
    
            assertEquals(HttpStatusCode.OK, response.status)
            assertContains(body, "Mow the lawn")
            assertContains(body, "Paint the fence")
        }
    
        @Test
        fun invalidPriorityProduces400() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Invalid")
            assertEquals(HttpStatusCode.BadRequest, response.status)
        }
    
        @Test
        fun unusedPriorityProduces404() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Vital")
            assertEquals(HttpStatusCode.NotFound, response.status)
        }
    }

    在其中的每个测试中,都会创建一个新的 Ktor 实例。它运行在测试环境中,而不是像 Netty 这样的 Web 服务器中。Project Generator 为你编写的模块将被加载,随后调用路由函数。接着,你可以使用内置的 client 对象向应用程序发送请求,并验证返回的响应。

    这些测试可以在 IDE 内运行,也可以作为 CI/CD 流水线的一部分运行。

  3. 要在 IntelliJ IDEA 中运行测试,请点击每个测试函数旁边的装订区域图标(IntelliJ IDEA gutter icon)。

    有关如何在 IntelliJ IDEA 中运行单元测试的更多详情,请参阅 IntelliJ IDEA 文档。

处理 POST 请求

你可以按照上述流程创建任意数量的 GET 请求附加路由。这允许用户根据所需的任何搜索条件获取任务。但是用户可能还希望能够创建新任务。

在这种情况下,合适的 HTTP 请求类型是 POST。POST 请求通常在用户填写并提交 HTML 表单时触发。

与 GET 请求不同,POST 请求具有 body,其中包含表单上存在的所有输入的名称和值。该信息经过编码以分隔来自不同输入的数据并转义非法字符。你无需担心该过程的细节,因为浏览器和 Ktor 会为我们处理好这些。

接下来,你将按照以下步骤扩展现有应用程序以允许创建新任务:

  1. 创建包含 HTML 表单的静态内容文件夹。
  2. 使 Ktor 识别该文件夹,以便能够提供其内容。
  3. 添加新的请求处理程序来处理表单提交。
  4. 测试已完成的功能。

创建静态内容

  1. 在 src/main/resources 内,创建一个名为 task-ui 的新目录。 这将作为存放静态内容的文件夹。

  2. 在 task-ui 文件夹内,创建一个新的 task-form.html 文件。

  3. 打开新创建的 task-form.html 文件并向其中添加以下内容:

    html
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Adding a new task</title>
    </head>
    <body>
    <h1>Adding a new task</h1>
    <form method="post" action="/tasks">
        <div>
            <label for="name">Name: </label>
            <input type="text" id="name" name="name" size="10">
        </div>
        <div>
            <label for="description">Description: </label>
            <input type="text" id="description" name="description" size="20">
        </div>
        <div>
            <label for="priority">Priority: </label>
            <select id="priority" name="priority">
                <option name="Low">Low</option>
                <option name="Medium">Medium</option>
                <option name="High">High</option>
                <option name="Vital">Vital</option>
            </select>
        </div>
        <input type="submit">
    </form>
    </body>
    </html>

向 Ktor 注册文件夹

  1. 导航到 src/main/kotlin 内的 Routing.kt 文件。

  2. 在 Application.configureRouting() 函数中添加以下对 staticResources() 的调用:

    kotlin
    fun Application.configureRouting() {
        routing {
            // Add the following line
            staticResources("/task-ui", "task-ui")
    
            get("/tasks") {
                // ...
            }
    
            get("/tasks/byPriority/{priority?}") {
                //...
            }
        }
    }

    IDE 随后应自动添加以下导入语句:

    kotlin
    import io.ktor.server.http.content.staticResources
  3. 重启应用程序。

  4. 在浏览器中导航到 http://0.0.0.0:8080/task-ui/task-form.html。HTML 表单应该会显示出来:

    A browser window displaying an HTML form

为表单添加处理程序

    在 Routing.kt 文件中, 向 .configureRouting() 函数中添加以下附加路由:

    kotlin
    fun Application.configureRouting() {
        routing {
            //...
    
            //add the following route
            post("/tasks") {
                val formContent = call.receiveParameters()
    
                val params = Triple(
                    formContent["name"] ?: "",
                    formContent["description"] ?: "",
                    formContent["priority"] ?: ""
                )
    
                if (params.toList().any { it.isEmpty() }) {
                    call.respond(HttpStatusCode.BadRequest)
                    return@post
                }
    
                try {
                    val priority = Priority.valueOf(params.third)
                    TaskRepository.addTask(
                        Task(
                            params.first,
                            params.second,
                            priority
                        )
                    )
    
                    call.respond(HttpStatusCode.NoContent)
                } catch (ex: IllegalArgumentException) {
                    call.respond(HttpStatusCode.BadRequest)
                } catch (ex: IllegalStateException) {
                    call.respond(HttpStatusCode.BadRequest)
                }
            }
        }
    }

    新路由映射到 POST 请求而不是 GET 请求。Ktor 通过调用 .receiveParameters() 来处理请求体。这会返回请求体中存在的形参集合。

    共有三个形参,因此你可以将关联的值存储在 Triple 中。如果某个形参不存在,则存储空字符串作为替代。

    如果任何值为空,服务器将返回带有 400 状态码的响应。然后,它将尝试把第三个形参转换为 Priority,如果成功,则将该信息作为新的 Task 添加到仓库中。这两项操作都可能会引发异常,在这种情况下同样会返回 400 状态码。

    否则,如果一切顺利,服务器将向客户端返回 204 No Content 状态码。这表示请求已成功,但无需返回新的信息。

测试已完成的功能

  1. 重启应用程序。

  2. 在浏览器中导航到 http://0.0.0.0:8080/task-ui/task-form.html。

  3. 用示例数据填写表单,然后点击 Submit。

    A browser window displaying an HTML form with sample data

    提交表单后,页面不应跳转到新页面。

  4. 导航到 URL http://0.0.0.0:8080/tasks。你应该能看到新任务已成功添加。

    A browser window displaying an HTML table with tasks
  5. 为了验证该功能,请将以下测试添加到 ServerTest.kt 文件中:

    kotlin
    package com.example
    
    import io.ktor.client.request.get
    import io.ktor.client.request.header
    import io.ktor.client.request.post
    import io.ktor.client.request.setBody
    import io.ktor.client.statement.bodyAsText
    import io.ktor.http.ContentType
    import io.ktor.http.HttpHeaders
    import io.ktor.http.HttpStatusCode
    import io.ktor.http.formUrlEncode
    import io.ktor.server.testing.testApplication
    import kotlin.test.*
    
    class ServerTest {
        @Test
        fun tasksCanBeFoundByPriority() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Medium")
            val body = response.bodyAsText()
    
            assertEquals(HttpStatusCode.OK, response.status)
            assertContains(body, "Mow the lawn")
            assertContains(body, "Paint the fence")
        }
    
        @Test
        fun invalidPriorityProduces400() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Invalid")
            assertEquals(HttpStatusCode.BadRequest, response.status)
        }
    
        @Test
        fun unusedPriorityProduces404() = testApplication {
            configure()
    
            val response = client.get("/tasks/byPriority/Vital")
            assertEquals(HttpStatusCode.NotFound, response.status)
        }
    
        @Test
        fun newTasksCanBeAdded() = testApplication {
            configure()
    
            val response1 = client.post("/tasks") {
                header(
                    HttpHeaders.ContentType,
                    ContentType.Application.FormUrlEncoded.toString()
                )
                setBody(
                    listOf(
                        "name" to "swimming",
                        "description" to "Go to the beach",
                        "priority" to "Low"
                    ).formUrlEncode()
                )
            }
            assertEquals(HttpStatusCode.NoContent, response1.status)
    
            val response2 = client.get("/tasks")
            assertEquals(HttpStatusCode.OK, response2.status)
            val body = response2.bodyAsText()
    
            assertContains(body, "swimming")
            assertContains(body, "Go to the beach")
        }
    }

    在此测试中,向服务器发送了两个请求:用于创建新任务的 POST 请求,以及用于确认新任务已添加的 GET 请求。发起第一个请求时,使用 setBody() 函数在请求体中插入内容。测试框架在集合上提供了 .formUrlEncode() 扩展函数,它对按浏览器方式格式化数据的过程进行了抽象封装。

重构路由

如果你检查目前的路由配置,会发现所有路由都以 /tasks 开头。你可以通过将它们放入专属的子路由中来消除这种重复:

kotlin
fun Application.configureRouting() {
    routing {
        staticResources("/task-ui", "task-ui")

        route("/tasks") {
            get {
                //Code remains the same
            }

            get("/byPriority/{priority?}") {
                //Code remains the same
            }

            post {
                //Code remains the same
            }
        }
    }
}

如果你的应用程序发展到拥有多个子路由的阶段,那么将每个子路由放入各自的帮助函数中是比较合适的。不过目前尚不需要这样做。

路由组织得越好,扩展起来就越容易。例如,你可以添加一个按名称查找任务的路由:

kotlin
fun Application.configureRouting() {
    routing {
        staticResources("/task-ui", "task-ui")

        route("/tasks") {
            get {
                // Code remains the same
            }
            get("/byName/{taskName}") {
                val name = call.parameters["taskName"]
                if (name == null) {
                    call.respond(HttpStatusCode.BadRequest)
                    return@get
                }

                val task = TaskRepository.taskByName(name)
                if (task == null) {
                    call.respond(HttpStatusCode.NotFound)
                    return@get
                }

                call.respondText(
                    contentType = ContentType.parse("text/html"),
                    text = listOf(task).tasksAsTable()
                )
            }

            get("/byPriority/{priority?}") {
                // Code remains the same
            }

            post {
                // Code remains the same
            }
        }
    }
}

后续步骤

现在,你已经实现了基本的路由和请求处理功能。此外,你还了解了验证、错误处理和单元测试。所有这些主题都将在后续的教程中进一步展开。

继续阅读下一篇教程了解如何使用 Kotlin 和 Ktor 构建后端服务,并包含一个生成 JSON 文件的 RESTful API 示例。,了解如何为生成 JSON 文件的任务管理器创建 RESTful API。