Skip to content

새 Ktor 프로젝트 생성, 열기 및 실행

이 튜토리얼에서는 첫 Ktor 서버 프로젝트를 생성, 열기 및 실행하는 방법을 배웁니다. 실행 환경을 구성하고 나면, Ktor에 익숙해지기 위한 일련의 작업들을 완료해 볼 수 있습니다.

이 문서는 Ktor를 사용한 서버 애플리케이션 구축을 시작하기 위한 일련의 튜토리얼 중 첫 번째입니다. 각 튜토리얼을 독립적으로 진행할 수도 있지만, 권장하는 순서대로 따라 진행하는 것을 강력히 추천합니다:

  1. 새 Ktor 프로젝트 생성, 열기 및 실행
  2. 요청 처리 및 응답 생성태스크 관리자(Task Manager) 애플리케이션을 빌드하며 Kotlin 및 Ktor를 통한 라우팅, 요청 처리, 파라미터 기초를 학습합니다..
  3. JSON을 생성하는 RESTful API 생성Kotlin과 Ktor를 사용하여 백엔드 서비스를 구축하는 방법을 배우며, JSON을 생성하는 RESTful API 예제를 다룹니다..
  4. Thymeleaf 템플릿을 사용하여 웹사이트 생성Kotlin, Ktor 및 Thymeleaf 템플릿을 사용하여 웹사이트를 구축하는 방법을 알아봅니다..
  5. WebSocket 애플리케이션 생성WebSocket을 활용하여 콘텐츠를 주고받는 방법을 알아봅니다..
  6. Exposed를 사용한 데이터베이스 연동Exposed SQL 라이브러리를 사용하여 Ktor 서비스를 데이터베이스 리포지토리에 연결하는 프로세스를 알아봅니다..

새 Ktor 프로젝트 생성

새 Ktor 프로젝트를 생성하는 가장 빠른 방법 중 하나는 웹 기반 Ktor 프로젝트 생성기(Ktor project generator)를 사용하는 것입니다.

또는 IntelliJ IDEA Ultimate 전용 Ktor 플러그인이나 Ktor CLI 도구를 사용하여 프로젝트를 생성할 수도 있습니다.

Ktor 프로젝트 생성기 사용

Ktor 프로젝트 생성기로 새 프로젝트를 생성하려면 다음 단계를 따르세요:

  1. Ktor 프로젝트 생성기로 이동합니다.

  2. Project artifact 필드에 프로젝트 아티팩트 이름으로 com.example.ktor-sample 을 입력합니다. Ktor project generator with Project Artifact Name com.example.ktor-sample

  3. Configure를 클릭하여 설정 드롭다운 메뉴를 엽니다: expanded view of Ktor project settings

    다음과 같은 설정을 사용할 수 있습니다:

    • Build System : 원하는 빌드 시스템기존 Gradle/Maven 프로젝트에 Ktor 서버 의존성을 추가하는 방법을 알아봅니다.을 선택합니다. Gradle Kotlin, Gradle Groovy, Maven 또는 Amper 중 하나를 선택할 수 있습니다.

    • Engine : 서버 실행에 사용할 엔진네트워크 요청을 처리하는 엔진에 대해 알아봅니다.을 선택합니다.

    • Configuration : 서버 매개변수를 YAML 또는 HOCON 파일설정 파일에서 다양한 서버 파라미터를 구성하는 방법을 알아봅니다.에 지정할지, 아니면 코드코드로 다양한 서버 파라미터를 설정하는 방법을 알아봅니다.에 지정할지 선택합니다.

      YAML 구성은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.

    이 튜토리얼에서는 이러한 설정을 기본값 그대로 유지해도 됩니다.

  4. Done을 클릭하여 구성을 저장하고 메뉴를 닫습니다.

  5. 아래에서 프로젝트에 추가할 수 있는 일련의 플러그인플러그인은 직렬화, 콘텐츠 인코딩, 압축 등과 같은 공통 기능을 제공합니다.을 확인할 수 있습니다. 플러그인은 Ktor 애플리케이션에서 인증, 직렬화 및 콘텐츠 인코딩, 압축, 쿠키 지원 등과 같은 일반적인 기능을 제공하는 빌딩 블록입니다.

    이 튜토리얼에서는 현재 단계에서 플러그인을 추가할 필요가 없습니다.

  6. Download 버튼을 클릭하여 Ktor 프로젝트를 생성하고 다운로드합니다. Ktor project generator download button

  7. 다운로드가 자동으로 시작됩니다.

새 프로젝트가 생성되었으므로, 이제 Ktor 프로젝트를 압축 해제하고 실행해 보세요.

IntelliJ IDEA Ultimate용 Ktor 플러그인 사용

이 섹션에서는 IntelliJ IDEA Ultimate용 Ktor 플러그인을 사용한 프로젝트 설정에 대해 설명합니다.

새 Ktor 프로젝트를 생성하려면 IntelliJ IDEA를 실행하고 다음 단계를 따르세요:

  1. 시작 화면에서 New Project를 클릭합니다.

    이미 프로젝트가 열려 있다면 메인 메뉴에서 File | New | Project를 선택합니다.

  2. New Project 마법사 왼쪽 목록에서 Ktor 를 선택합니다.

  3. 오른쪽 창에서 다음 설정을 지정할 수 있습니다:

    Ktor Project Settings
    • Name: 프로젝트 이름을 지정합니다. 프로젝트 이름으로 ktor-sample 을 입력합니다.

    • Location: 프로젝트를 저장할 디렉터리를 지정합니다.

    • Website : 패키지 이름을 생성하는 데 사용할 도메인을 지정합니다.

    • Artifact : 생성된 아티팩트 이름이 표시됩니다.

    • Engine : 서버 실행에 사용할 엔진네트워크 요청을 처리하는 엔진에 대해 알아봅니다.을 선택합니다.

    • Include samples : 플러그인용 샘플 코드를 추가하려면 이 옵션을 활성화된 상태로 둡니다.

  4. Advanced Settings 를 클릭하여 추가 설정 메뉴를 펼칩니다:

    Ktor Project Advanced Settings

    다음과 같은 설정을 사용할 수 있습니다:

    • Build System : 원하는 빌드 시스템기존 Gradle/Maven 프로젝트에 Ktor 서버 의존성을 추가하는 방법을 알아봅니다.을 선택합니다. Gradle Kotlin, Gradle Groovy, Maven 또는 Amper 중 하나를 선택할 수 있습니다.

    • Ktor version : 필요한 Ktor 버전을 선택합니다.

    • Configuration : 서버 매개변수를 YAML 또는 HOCON 파일설정 파일에서 다양한 서버 파라미터를 구성하는 방법을 알아봅니다.에 지정할지, 아니면 코드코드로 다양한 서버 파라미터를 설정하는 방법을 알아봅니다.에 지정할지 선택합니다.

      YAML 구성은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.

    이 튜토리얼에서는 이러한 설정을 기본값 그대로 유지해도 됩니다.

  5. Next 를 클릭하여 다음 페이지로 이동합니다.

    Ktor plugins

    이 페이지에서는 인증, 직렬화 및 콘텐츠 인코딩, 압축, 쿠키 지원 등 Ktor 애플리케이션의 일반적인 기능을 제공하는 빌딩 블록인 플러그인플러그인은 직렬화, 콘텐츠 인코딩, 압축 등과 같은 공통 기능을 제공합니다. 세트를 선택할 수 있습니다.

    이 튜토리얼에서는 현재 단계에서 플러그인을 추가할 필요가 없습니다.

  6. Create 를 클릭하고 IntelliJ IDEA가 프로젝트를 생성하고 의존성을 설치할 때까지 기다립니다.

새 프로젝트 생성을 완료했으므로, 이제 애플리케이션을 열고, 탐색하고, 실행하는 방법을 계속해서 알아봅니다.

Ktor CLI 도구 사용

이 섹션에서는 Ktor CLI 도구를 사용한 프로젝트 설정에 대해 설명합니다.

새 Ktor 프로젝트를 생성하려면 원하는 터미널을 열고 다음 단계를 따르세요:

  1. 다음 명령 중 하나를 사용하여 Ktor CLI 도구를 설치합니다:
    console
    brew install ktor
    console
    winget install JetBrains.KtorCLI
  2. 대화형 모드로 새 프로젝트를 생성하려면 다음 명령을 사용합니다:
    console
    ktor new
  3. 프로젝트 이름으로 ktor-sample 을 입력합니다: Using the Ktor CLI tool in interactive mode

    (선택 사항) 프로젝트 이름 아래의 Location 경로를 편집하여 프로젝트가 저장될 위치를 변경할 수도 있습니다.

  4. Enter 를 눌러 계속 진행합니다.
  5. 다음 단계에서는 프로젝트에 플러그인플러그인은 직렬화, 콘텐츠 인코딩, 압축 등과 같은 공통 기능을 제공합니다.을 검색하여 추가할 수 있습니다. 플러그인은 인증, 직렬화 및 콘텐츠 인코딩, 압축, 쿠키 지원 등 Ktor 애플리케이션의 일반적인 기능을 제공하는 빌딩 블록입니다. Add plugins to a project using the Ktor CLI tool

    이 튜토리얼에서는 현재 단계에서 플러그인을 추가할 필요가 없습니다.

  6. CTRL+G 를 눌러 프로젝트를 생성합니다.

    또는 CREATE PROJECT (CTRL+G) 를 선택하고 Enter 를 눌러 프로젝트를 생성할 수도 있습니다.

Ktor 프로젝트 압축 해제 및 실행

이 섹션에서는 명령줄에서 프로젝트를 압축 해제하고 빌드 및 실행하는 방법을 알아봅니다. 아래 단계는 다음을 가정합니다:

  1. 이름이 ktor-sample 인 Gradle 프로젝트를 생성하고 다운로드했습니다.
  2. 이 프로젝트는 홈 디렉터리의 myprojects 라는 폴더에 위치해 있습니다.

필요한 경우 본인의 환경에 맞게 이름과 경로를 변경하세요.

원하는 명령줄 도구를 열고 다음 단계를 따릅니다:

  1. 터미널 창에서 프로젝트를 다운로드한 폴더로 이동합니다:

    console
    cd ~/myprojects
  2. 동일한 이름의 폴더에 ZIP 아카이브의 압축을 풉니다:

    console
    unzip ktor-sample.zip -d ktor-sample
    console
    tar -xf ktor-sample.zip

    이제 디렉터리에 ZIP 아카이브와 압축이 해제된 폴더가 포함됩니다.

  3. 해당 디렉터리에서 새로 생성된 폴더로 이동합니다:

    console
    cd ktor-sample
  4. macOS 및 UNIX 시스템에서는 시스템이 실행 가능한 명령으로 인식하도록 Gradle 헬퍼 스크립트에 실행 권한을 부여해야 합니다. 이를 위해 chmod 명령을 사용합니다:

    console
    chmod +x ./gradlew
  5. 프로젝트를 빌드하려면 다음 명령을 사용합니다:

    console
    ./gradlew build
    console
    gradlew build

    빌드가 성공하면 다음 단계로 넘어가 프로젝트를 실행합니다.

  6. 프로젝트를 실행하려면 다음 명령을 사용합니다:

    console
    ./gradlew run
    console
    gradlew run
  7. 프로젝트가 실행 중인지 확인하려면 터미널 출력에 표시된 URL(http://0.0.0.0:8080)로 브라우저를 엽니다. 브라우저에 "Hello World!"라는 메시지가 표시되는 것을 확인할 수 있습니다:

    Output of the generated ktor project

축하합니다! Ktor 프로젝트를 성공적으로 시작했습니다.

백그라운드 프로세스가 Ktor 애플리케이션을 실행하느라 사용 중이므로 명령줄에 응답이 없을 수 있습니다. 애플리케이션을 종료하려면 CTRL+C 를 누르면 됩니다.

IntelliJ IDEA에서 Ktor 프로젝트 열기, 탐색 및 실행

프로젝트 열기

IntelliJ IDEA가 설치되어 있다면 명령줄에서 쉽게 프로젝트를 열 수 있습니다.

프로젝트 폴더에 위치해 있는지 확인한 후 idea 명령과 현재 폴더를 나타내는 점(.)을 입력합니다:

bash
idea .

또는 수동으로 프로젝트를 열려면 IntelliJ IDEA를 직접 실행합니다.

시작 화면이 열리면 Open 을 클릭합니다. 그렇지 않은 경우 메인 메뉴에서 File | Open 으로 이동하여 ktor-sample 폴더를 선택해 엽니다.

프로젝트 관리에 대한 자세한 내용은 IntelliJ IDEA 문서를 참조하세요.

프로젝트 탐색

프로젝트를 열면 다음과 같은 구조를 볼 수 있습니다:

Generated Ktor project view in IDE

전체 구조를 보려면 각 폴더 옆의 펼치기 화살표를 클릭하여 Project 뷰에서 폴더를 펼칩니다.

애플리케이션 소스 코드는 src/main/kotlin 아래에 위치합니다. 기본적으로 Application.kt 및 Routing.kt 라는 두 개의 파일이 생성됩니다.

Ktor project src folder structure

프로젝트 이름은 settings.gradle.kts 파일에 구성되어 있습니다:

kotlin
rootProject.name = "ktor-sample"

구성 파일 및 기타 유형의 콘텐츠는 src/main/resources 폴더 내에 있습니다.

Ktor project resources folder structure

프로젝트 실행

    IntelliJ IDEA 내에서 프로젝트를 실행하려면:

  1. 오른쪽 사이드바에서 Gradle 아이콘(intelliJ IDEA gradle icon)을 클릭하여 Gradle 도구 창을 엽니다.

  2. 이 도구 창 내에서 Tasks | application 으로 이동한 후 run 태스크를 더블 클릭합니다.

    Gradle tab in IntelliJ IDEA
  3. IDE 하단의 Run 도구 창에서 Ktor 애플리케이션이 시작됩니다:

    Project running in the terminal

    이전에 명령줄에 표시되었던 것과 동일한 메시지가 이제 Run 도구 창에 표시됩니다.

  4. 프로젝트가 실행 중인지 확인하려면 지정된 URL(http://0.0.0.0:8080)로 브라우저를 엽니다.

    화면에 다시 한 번 "Hello World!" 메시지가 표시되는 것을 볼 수 있습니다:

    Hello World in Browser Screen

Run 도구 창을 통해 애플리케이션을 관리할 수 있습니다.

  1. 애플리케이션을 중지하려면 정지 버튼 intelliJ IDEA terminate icon을 클릭합니다.
  2. 프로세스를 재시작하려면 다시 실행(rerun) 버튼 intelliJ IDEA rerun icon을 클릭합니다.

이러한 옵션에 대한 자세한 설명은 IntelliJ IDEA Run 도구 창 문서를 참조하세요.

추가 과제 실습하기

직접 시도해 볼 수 있는 몇 가지 추가 과제는 다음과 같습니다:

  1. 기본 포트 변경
  2. 새 HTTP 엔드포인트 추가
  3. 정적 콘텐츠 구성
  4. 통합 테스트 작성
  5. 오류 핸들러 등록

이 과제들은 서로 의존하지는 않지만 난이도가 점진적으로 높아집니다. 명시된 순서대로 진행하는 것이 단계적으로 학습하기에 가장 좋습니다. 단순화 및 내용 중복을 피하기 위해, 아래의 설명은 과제를 순서대로 진행하고 있다고 가정합니다.

코딩이 필요한 부분에는 코드와 해당 import 문을 모두 명시해 두었습니다. IDE가 이러한 import 문을 자동으로 추가해 줄 수도 있습니다.

기본 포트 변경

구성 파일에서 포트 변경

구성을 YAML 또는 HOCON 파일 내에 외부로 저장하도록 선택한 경우, Project 뷰에서 src/main/resources 폴더로 이동한 후 다음 단계를 따릅니다:

  1. 구성 파일( application.yaml 또는 application.conf )을 엽니다. 다음과 같이 표시됩니다:
    yaml
    ktor:
      deployment:
        port: 8080
      application:
        modules:
          - com.example.RoutingKt.configureRouting
    generic
    ktor {
      deployment {
        port = 8080
        port = ${?PORT}
      }
      application {
        modules = [
          com.example.RoutingKt.configureRouting
        ]
      }
    }
  2. 파일에서 port 값을 9292 등 원하는 다른 번호로 변경합니다.
  3. 다시 실행 버튼(intelliJ IDEA rerun button icon)을 클릭하여 애플리케이션을 재시작합니다.

  4. 애플리케이션이 새 포트 번호에서 실행 중인지 확인하려면 새 URL(http://0.0.0.0:9292)로 브라우저를 열거나 IntelliJ IDEA에서 새 HTTP Request 파일을 생성할 수 있습니다:

    Testing port change with an HTTP request file in IntelliJ IDEA

코드에서 포트 변경

새 Ktor 프로젝트를 생성할 때 구성을 코드에 저장할지, 아니면 YAML 또는 HOCON 파일 내에 외부로 저장할지 선택할 수 있습니다.

구성을 코드에 저장하는 옵션을 선택한 경우, Project 뷰에서 src/main/kotlin 폴더로 이동한 후 다음 단계를 따릅니다:

  1. main.kt 파일을 엽니다. 다음과 유사한 코드를 확인할 수 있습니다:

    kotlin
    fun main(args: Array<String>) {
        embeddedServer(
            factory = io.ktor.server.netty.Netty,
            port = 8080,
            host = "0.0.0.0",
            module = Application::rootModule
        ).start(wait = true)
    }
  2. embeddedServer() 함수에서 port 매개변수를 9292 등 원하는 다른 번호로 변경합니다.

    kotlin
    fun main(args: Array<String>) {
        embeddedServer(
            factory = io.ktor.server.netty.Netty,
            port = 9292,
            host = "0.0.0.0",
            module = Application::rootModule
        ).start(wait = true)
    }
  3. 다시 실행 버튼(IntelliJ IDEA rerun button icon)을 클릭하여 애플리케이션을 재시작합니다.

  4. 애플리케이션이 새 포트 번호에서 실행 중인지 확인하려면 새 URL(http://0.0.0.0:9292)로 브라우저를 열거나, IntelliJ IDEA에서 새 HTTP Request 파일을 생성할 수 있습니다:

    Testing port change with an HTTP request file in IntelliJ IDEA

새 HTTP 엔드포인트 추가

Project 도구 창에서 src/main/kotlin 폴더로 이동한 후 다음 단계를 따릅니다:

  1. Routing.kt 파일을 엽니다. 다음과 같은 코드가 표시됩니다:

    kotlin
    fun Application.configureRouting() {
        routing {
            get("/") {
                call.respondText("Hello World!")
            }
        }
    }
  2. 새 엔드포인트를 생성하려면 아래와 같이 추가 라우트를 삽입합니다:

    kotlin
    fun Application.configureRouting() {
        routing {
            // ...
    
            get("/test1") {
                val text = "<h1>Hello From Ktor</h1>"
                val type = ContentType.parse("text/html")
                call.respondText(text, type)
            }
        }
    }
    /test1 URL은 원하는 어떤 경로로든 변경할 수 있습니다.
  3. IDE에서 자동으로 ContentType import 문을 추가합니다:

    kotlin
    import io.ktor.http.ContentType
  4. 다시 실행 버튼(intelliJ IDEA rerun button icon)을 클릭하여 애플리케이션을 재시작합니다.

  5. 브라우저에서 새 URL(http://0.0.0.0:9292/test1)을 요청합니다. 포트 번호는 기본 포트 변경 작업을 완료했는지 여부에 따라 달라집니다. 아래와 같은 출력이 표시되어야 합니다:

    A browser screen displaying Hello from Ktor

    HTTP 요청 파일을 생성했다면 거기서도 새 엔드포인트를 확인할 수 있습니다:

    http
    GET http://0.0.0.0:9292
    
    ###
    
    GET http://0.0.0.0:9292/test1
    서로 다른 요청을 구분하려면 세 개의 해시(###)가 포함된 줄이 필요합니다.

정적 콘텐츠 구성

Project 도구 창에서 src/main/kotlin 폴더로 이동한 후 다음 단계를 따릅니다:

  1. Routing.kt 파일을 열고 라우팅 섹션에 다음 라우트를 추가합니다:

    kotlin
    fun Application.configureRouting() {
        routing {
            staticResources("/content", "mycontent")
            // ...
        }
    }

    이 줄의 의미는 다음과 같습니다:

    1. staticResources()를 호출하면 애플리케이션이 HTML 및 JavaScript 파일과 같은 표준 웹사이트 콘텐츠를 제공할 수 있게 됩니다. 이러한 콘텐츠는 브라우저 내에서 실행될 수 있지만, 서버 입장에서는 정적(static)인 것으로 간주됩니다.
    2. URL /content는 이 콘텐츠를 가져오는 데 사용되는 경로를 지정합니다.
    3. 경로 mycontent는 정적 콘텐츠가 위치할 폴더의 이름입니다. Ktor는 resources 디렉터리 내에서 이 폴더를 찾습니다.
  2. IDE에서 자동으로 추가하지 않는 경우 다음 import 문을 추가합니다.

    kotlin
    import io.ktor.server.http.content.staticResources
  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로 채웁니다:

    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>
  8. 다시 실행 버튼(IntelliJ IDEA rerun button icon)을 클릭하여 애플리케이션을 재시작합니다.

  9. 브라우저에서 http://0.0.0.0:9292/content/sample.html을 열면 샘플 페이지의 내용이 표시됩니다:

    Output of a static page in a browser

통합 테스트 작성

Ktor는 통합 테스트 작성특별한 테스트 엔진을 사용하여 서버 애플리케이션을 테스트하는 방법을 알아봅니다.을 지원하며, 생성된 프로젝트에는 이 기능이 이미 기본 포함되어 있습니다.

이를 사용하려면 다음 단계를 따릅니다:

  1. src/test/kotlin 폴더로 이동합니다.

  2. ServerTest.kt 파일을 엽니다. 아래와 같은 코드가 표시됩니다:

    kotlin
    class ServerTest {
    
        @Test
        fun `test root endpoint`() = testApplication {
            // loads default configuration
            configure()
            // verify server root returns 200
            assertEquals(HttpStatusCode.OK, client.get("/").status)
        }
    
    }

    testApplication() 함수는 Ktor의 새 인스턴스를 만듭니다. 이 인스턴스는 Netty와 같은 서버 대신 테스트 환경 내부에서 실행됩니다.

    그런 다음 configure() 함수를 사용하여 embeddedServer()에서 호출되는 것과 동일한 설정을 호출할 수 있습니다.

    마지막으로 기본 내장된 client 객체와 JUnit assertion을 사용하여 샘플 요청을 보내고 응답을 확인할 수 있습니다.

IntelliJ IDEA에서 테스트를 실행하는 표준 방법 중 어떤 것으로든 테스트를 실행할 수 있습니다. Ktor의 새 인스턴스를 실행하는 것이므로, 테스트의 성공 여부는 애플리케이션이 0.0.0.0에서 실행 중인지 여부와 상관없습니다.

새 HTTP 엔드포인트 추가를 성공적으로 완료했다면, 다음 테스트를 추가합니다:

kotlin
@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 문을 추가합니다:

kotlin
import io.ktor.http.contentType
import io.ktor.client.statement.bodyAsText

오류 핸들러 등록

StatusPages 플러그인StatusPages 플러그인을 사용하면 Ktor 애플리케이션이 발생한 예외나 상태 코드를 기반으로 모든 실패 상태에 적절히 응답할 수 있습니다.을 사용하여 Ktor 애플리케이션에서 오류를 처리할 수 있습니다.

이 플러그인은 기본적으로 프로젝트에 포함되어 있지 않습니다. Ktor 프로젝트 생성기 또는 IntelliJ IDEA의 Project Wizard에서 프로젝트를 생성할 때 Plugins 섹션을 통해 프로젝트에 추가할 수 있습니다.

다음 단계에서는 플러그인을 수동으로 추가하고 구성하는 방법을 알아봅니다. 네 단계로 진행됩니다:

  1. Gradle 빌드 파일에 새 의존성을 추가합니다.
  2. 플러그인을 설치하고 예외 처리기를 지정합니다.
  3. 처리기(handler)를 트리거할 샘플 코드를 작성합니다.
  4. 재시작하고 샘플 코드를 호출합니다.

새 의존성 추가

    Project 도구 창에서 프로젝트 루트 폴더로 이동한 후 다음 단계를 따릅니다:

  1. build.gradle.kts 파일을 열고 아래와 같이 새 의존성을 추가합니다:

    kotlin
    dependencies {
        implementation(ktorLibs.server.config.yaml)
        implementation(ktorLibs.server.core)
        implementation(ktorLibs.server.netty)
        // Add new dependency
        implementation(ktorLibs.server.statusPages)
        implementation(libs.logback.classic)
    
        testImplementation(libs.kotlin.test)
        testImplementation(ktorLibs.server.testHost)
    }
  2. Shift+⌘Cmd+I (macOS) 또는 Ctrl+Shift+O (Windows/Linux)를 눌러 프로젝트를 다시 로드합니다.

플러그인 설치 및 예외 처리기 지정

  1. Routing.kt의 .configureRouting() 메서드로 이동하여 다음 코드 라인을 추가합니다:

    kotlin
    fun Application.configureRouting() {
        install(StatusPages) {
            exception<IllegalStateException> { call, cause ->
                call.respondText("App in illegal state as ${cause.message}")
            }
        }
        routing {
            // ...
        }
    }

    이 코드는 StatusPages 플러그인을 설치하고 IllegalStateException 유형의 예외가 발생했을 때 수행할 작업을 지정합니다.

  2. 다음 import 문을 추가합니다:

    kotlin
    import io.ktor.server.plugins.statuspages.StatusPages

일반적으로는 응답에 HTTP 오류 코드가 설정되지만, 이 실습의 목적을 위해 출력이 브라우저에 직접 표시되도록 구성합니다.

처리기를 트리거할 샘플 코드 작성

  1. .configureRouting() 메서드 내에서 아래와 같이 추가 라우트를 추가합니다:

    kotlin
    fun 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")
            }
        }
    }

    이제 /error-test라는 URL을 가진 엔드포인트를 추가했습니다. 이 엔드포인트가 트리거되면 처리기에서 사용된 유형의 예외가 발생합니다.

재시작 및 샘플 코드 호출

  1. 다시 실행 버튼(intelliJ IDEA rerun button icon)을 클릭하여 애플리케이션을 재시작합니다.

  2. 브라우저에서 http://0.0.0.0:9292/error-test URL로 이동합니다. 아래와 같이 오류 메시지가 표시되는 것을 볼 수 있습니다:

    A browser screen with message `App in illegal state as Too Busy`

다음 단계

추가 과제를 모두 마쳤다면 Ktor 서버 구성, Ktor 플러그인 연동, 새 라우트 구현에 대한 기본 개념을 파악한 것입니다. 하지만 이는 시작에 불과합니다. Ktor의 핵심 개념을 더 깊이 살펴보려면 이 가이드의 다음 튜토리얼을 계속 진행해 보세요.

다음으로 작업 관리자(Task Manager) 애플리케이션을 만들어 요청을 처리하고 응답을 생성하는 방법태스크 관리자(Task Manager) 애플리케이션을 빌드하며 Kotlin 및 Ktor를 통한 라우팅, 요청 처리, 파라미터 기초를 학습합니다.을 배웁니다.