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 폼을 제출하여 새로운 태스크 추가

우선 기본 기능이 작동하도록 최소한의 작업을 진행한 다음, 7단계의 이터레이션을 거쳐 기능을 개선하고 확장합니다. 이 최소 기능은 모델 타입, 값 목록 및 단일 라우트를 포함하는 프로젝트로 구성됩니다.

정적 HTML 콘텐츠 표시하기

첫 번째 단계에서는 정적 HTML 콘텐츠를 반환하는 새로운 라우트를 애플리케이션에 추가합니다.

Ktor Project Generator를 사용하여 Project artifact 이름을 com.example.ktor-task-app으로 설정하고 새 프로젝트를 생성합니다.

새 프로젝트 생성에 대한 자세한 내용은 새 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()
                )
            }
        }
    }

    이렇게 하면 /tasks URL과 GET 요청 유형에 대한 새로운 라우트가 생성됩니다. GET 요청은 HTTP에서 가장 기본적인 요청 유형입니다. 사용자가 브라우저 주소 표시줄에 입력하거나 일반 HTML 링크를 클릭할 때 트리거됩니다.

    지금은 정적 콘텐츠만 반환합니다. 클라이언트에 HTML을 전송한다는 것을 알리기 위해 HTTP Content-Type 헤더를 "text/html"로 설정합니다.

  3. ContentType 객체에 접근할 수 있도록 IDE에서 다음 import 문을 자동으로 추가합니다.

    kotlin
    import io.ktor.http.ContentType
  4. IntelliJ IDEA에서 main.kt 파일의 main() 함수 옆에 있는 실행 거터 아이콘(IntelliJ IDEA 애플리케이션 실행 아이콘)을 클릭하여 애플리케이션을 시작합니다.

  5. 브라우저에서 http://0.0.0.0:8080/tasks로 이동합니다. to-do 목록이 표시되는 것을 확인할 수 있습니다.

    두 개의 항목이 있는 할 일 목록을 표시하는 브라우저 창

태스크 모델 구현하기

이제 프로젝트를 생성하고 기본 라우팅을 설정했으므로, 다음 작업을 수행하여 애플리케이션을 확장합니다.

  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를 열고 다음 코드를 추가하여 Task 목록을 정의합니다.

    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. 필요한 import 문을 추가합니다.

    kotlin
    import com.example.model.*

새로운 기능 테스트

  1. IntelliJ IDEA에서 재실행 버튼(IntelliJ IDEA 재실행 버튼 아이콘)을 클릭하여 애플리케이션을 다시 시작합니다.

  2. 브라우저에서 http://0.0.0.0:8080/tasks로 이동합니다. 태스크가 포함된 HTML 테이블이 표시되어야 합니다.

    4개의 행으로 이루어진 표를 표시하는 브라우저 창

    정상적으로 표시된다면 축하합니다! 애플리케이션의 기본 기능이 올바르게 동작하고 있습니다.

모델 리팩터링

애플리케이션의 기능을 확장하기 전에, 값 목록을 리포지토리 내에 캡슐화하여 설계를 리팩터링하겠습니다. 이렇게 하면 데이터 관리를 중앙 집중화할 수 있어 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 재실행 버튼 아이콘)을 클릭하여 애플리케이션을 다시 시작합니다.

  2. 브라우저에서 http://0.0.0.0:8080/tasks로 이동합니다. HTML 테이블이 표시된 상태로 결과는 이전과 동일해야 합니다.

    4개의 행으로 이루어진 표를 표시하는 브라우저 창

파라미터 다루기

이번 단계에서는 사용자가 우선순위별로 태스크를 볼 수 있도록 합니다. 이를 위해 애플리케이션은 다음 URL에 대한 GET 요청을 허용해야 합니다.

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

추가할 라우트는 /tasks/byPriority/{priority?}입니다. 여기서 {priority?}는 런타임에 추출해야 하는 경로 파라미터(path parameter)를 나타내며, 물음표는 파라미터가 선택 사항임을 나타내는 데 사용됩니다. 경로 파라미터 이름은 원하는 대로 지정할 수 있지만, priority가 가장 명확한 선택입니다.

요청을 처리하는 프로세스는 다음과 같이 요약할 수 있습니다.

  1. 요청에서 priority라는 경로 파라미터를 추출합니다.
  2. 이 파라미터가 없으면 400 Bad Request 상태를 반환합니다.
  3. 파라미터의 텍스트 값을 Priority 열거형(enum) 값으로 변환합니다.
  4. 변환에 실패하면 400 상태 코드가 포함된 응답을 반환합니다.
  5. 리포지토리를 사용하여 지정된 우선순위를 가진 모든 태스크를 찾습니다.
  6. 일치하는 태스크가 없으면 404 Not Found 상태를 반환합니다.
  7. 일치하는 태스크를 HTML 테이블 형식으로 반환합니다.

먼저 이 기능을 구현한 다음, 정상적으로 작동하는지 확인하는 최선의 방법을 알아보겠습니다.

새로운 라우트 추가

    Routing.kt 파일을 열고 코드에 다음 라우트를 추가합니다.

    kotlin
    routing {
        get("/tasks") {
            //...
        }
    
        // 다음 라우트 추가
        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)
            }
        }
    }

    위 코드를 통해 /tasks/byPriority/{priority?} URL에 대한 핸들러를 작성했습니다. 심볼 priority는 사용자가 전달한 경로 파라미터를 나타냅니다. 안타깝게도 서버 측에서는 이 값이 해당 Kotlin enum의 4가지 값 중 하나임을 보장할 방법이 없으므로 수동으로 확인해야 합니다.

    경로 파라미터가 없으면 서버는 클라이언트에 400 상태 코드를 반환합니다. 파라미터가 있는 경우 값을 추출하여 열거형의 멤버로 변환을 시도합니다. 이 작업이 실패하면 예외가 발생하며, 서버는 이를 포착하여 400 상태 코드를 반환합니다.

    변환에 성공하면 리포지토리를 사용하여 일치하는 Task를 찾습니다. 지정된 우선순위의 태스크가 없으면 서버는 404 상태 코드를 반환하고, 태스크가 있으면 일치하는 항목을 HTML 테이블에 담아 다시 전송합니다.

새로운 라우트 테스트

    브라우저에서 여러 URL을 요청하여 이 기능을 테스트할 수 있습니다.

  1. IntelliJ IDEA에서 재실행 버튼(IntelliJ IDEA 재실행 버튼 아이콘)을 클릭하여 애플리케이션을 다시 시작합니다.

  2. 보통(Medium) 우선순위 태스크를 모두 조회하려면 http://0.0.0.0:8080/tasks/byPriority/Medium으로 이동합니다.

    Medium 우선순위 태스크 표를 표시하는 브라우저 창
  3. 그러나 에러가 발생하는 경우 브라우저를 통한 테스트에는 한계가 있습니다. 개발자 도구 확장을 사용하지 않는 한 브라우저는 실패한 응답의 세부 정보를 보여주지 않습니다. 더 간단한 대안은 Postman과 같은 전문 도구를 사용하는 것입니다.

  4. Postman에서 동일한 URL인 http://0.0.0.0:8080/tasks/byPriority/Medium 으로 GET 요청을 보냅니다.

    응답 세부 정보를 보여주는 Postman의 GET 요청

    여기에는 서버의 원시 출력과 함께 요청 및 응답의 모든 세부 정보가 표시됩니다.

  5. Vital 태스크 요청 시 404 상태 코드가 반환되는지 확인하려면, http://0.0.0.0:8080/tasks/byPriority/Vital 로 새 GET 요청을 전송합니다. 그러면 Response 패널의 오른쪽 상단에 상태 코드가 표시됩니다.

    상태 코드를 보여주는 Postman의 GET 요청
  6. 잘못된 우선순위를 지정했을 때 400 상태 코드가 반환되는지 확인하려면, 유효하지 않은 프로퍼티 값으로 다른 GET 요청을 생성합니다.

    Bad Request 상태 코드를 보여주는 Postman의 GET 요청

단위 테스트 추가하기

지금까지 두 개의 라우트(모든 태스크를 조회하는 라우트와 우선순위별로 태스크를 조회하는 라우트)를 추가했습니다. 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와 같은 웹 서버 대신 테스트 환경 내부에서 실행됩니다. Project Generator가 작성한 모듈이 로드되고, 이어서 라우팅 함수가 호출됩니다. 그런 다음 내장된 client 객체를 사용하여 애플리케이션에 요청을 보내고, 반환된 응답을 검증할 수 있습니다.

    테스트는 IDE 내부에서 실행하거나 CI/CD 파이프라인의 일부로 실행할 수 있습니다.

  3. IntelliJ IDEA 내에서 테스트를 실행하려면 각 테스트 함수 옆에 있는 거터 아이콘(IntelliJ IDEA 거터 아이콘)을 클릭합니다.

    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 {
            // 다음 라인 추가
            staticResources("/task-ui", "task-ui")
    
            get("/tasks") {
                // ...
            }
    
            get("/tasks/byPriority/{priority?}") {
                //...
            }
        }
    }

    그러면 IDE가 다음 import 문을 자동으로 추가합니다.

    kotlin
    import io.ktor.server.http.content.staticResources
  3. 애플리케이션을 다시 시작합니다.

  4. 브라우저에서 http://0.0.0.0:8080/task-ui/task-form.html로 이동합니다. HTML 폼이 표시되어야 합니다.

    HTML 폼을 표시하는 브라우저 창

폼 핸들러 추가

    Routing.kt 파일에서 .configureRouting() 함수에 다음 라우트를 추가합니다.

    kotlin
    fun Application.configureRouting() {
        routing {
            //...
    
            // 다음 라우트 추가
            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)
                }
            }
        }
    }

    새 라우트는 GET 요청이 아닌 POST 요청에 매핑됩니다. 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을 클릭합니다.

    샘플 데이터가 입력된 HTML 폼을 표시하는 브라우저 창

    폼을 제출해도 새 페이지로 이동하지 않아야 합니다.

  4. URL http://0.0.0.0:8080/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 {
                // 코드는 동일하게 유지
            }

            get("/byPriority/{priority?}") {
                // 코드는 동일하게 유지
            }

            post {
                // 코드는 동일하게 유지
            }
        }
    }
}

애플리케이션이 여러 하위 라우트가 생길 정도로 커진다면 각각을 별도의 헬퍼 함수로 분리하는 것이 적절할 것입니다. 하지만 현재로서는 그럴 필요가 없습니다.

라우트가 잘 정리되어 있을수록 확장이 더 쉬워집니다. 예를 들어 이름별로 태스크를 찾는 라우트를 다음과 같이 추가할 수 있습니다.

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

        route("/tasks") {
            get {
                // 코드는 동일하게 유지
            }
            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?}") {
                // 코드는 동일하게 유지
            }

            post {
                // 코드는 동일하게 유지
            }
        }
    }
}

다음 단계

지금까지 기본적인 라우팅 및 요청 처리 기능을 구현했습니다. 또한 유효성 검증, 에러 처리, 단위 테스트에 대해서도 알아보았습니다. 이러한 모든 주제는 이후 튜토리얼에서 더 자세히 다룰 예정입니다.

다음 튜토리얼Kotlin과 Ktor를 사용하여 백엔드 서비스를 구축하는 방법을 배우며, JSON을 생성하는 RESTful API 예제를 다룹니다.로 이동하여 태스크 관리자용 JSON 파일을 생성하는 RESTful API를 빌드하는 방법을 알아보세요.