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

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

코드 예제: tutorial-server-get-started

이 튜토리얼에서는 첫 번째 Ktor 서버 프로젝트를 생성하고, 열고, 실행하는 방법을 배웁니다. 프로젝트가 실행되면 일련의 과제를 완료하여 Ktor에 익숙해질 수 있습니다.

이것은 Ktor로 서버 애플리케이션을 구축하기 위한 시작 단계인 일련의 튜토리얼 중 첫 번째입니다. 각 튜토리얼을 독립적으로 진행할 수 있지만, 다음 권장 순서를 따르는 것이 좋습니다:

1. 새로운 Ktor 프로젝트 생성, 열기 및 실행
2. 요청 처리 및 응답 생성

   Task Manager 애플리케이션을 빌드하며 Ktor와 Kotlin을 사용한 라우팅, 요청 처리 및 매개변수의 기본 사항을 알아봅니다.
3. JSON을 생성하는 RESTful API 만들기

   JSON 파일을 생성하는 RESTful API 예제를 통해 Kotlin과 Ktor를 사용하여 백엔드 서비스를 빌드하는 방법을 알아봅니다.
4. Thymeleaf 템플릿을 사용하여 웹사이트 만들기

   Ktor와 Thymeleaf 템플릿을 사용하여 Kotlin으로 웹사이트를 빌드하는 방법을 알아봅니다.
5. WebSocket 애플리케이션 만들기

   WebSocket의 기능을 활용하여 콘텐츠를 주고받는 방법을 알아봅니다.
6. Exposed를 사용하여 데이터베이스 통합

   Exposed SQL 라이브러리를 사용하여 Ktor 서비스를 데이터베이스 리포지토리에 연결하는 프로세스를 알아봅니다.

새로운 Ktor 프로젝트 생성

새로운 Ktor 프로젝트를 생성하는 가장 빠른 방법 중 하나는 웹 기반 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 서버 종속성을 추가하는 방법을 알아봅니다.
     을 선택합니다. Gradle Kotlin, Gradle Groovy, Maven, 또는 Amper 중 하나를 선택할 수 있습니다.

   • Engine: 서버를 실행하는 데 사용할

     엔진

     네트워크 요청을 처리하는 엔진에 대해 알아봅니다.
     을 선택합니다.

   • Configuration: 서버 매개변수를

     YAML 또는 HOCON 파일

     구성 파일에서 다양한 서버 매개변수를 구성하는 방법을 알아봅니다.
     에 지정할지, 아니면
     코드

     코드에서 다양한 서버 매개변수를 구성하는 방법을 알아봅니다.
     에 직접 지정할지 선택합니다.
     YAML 구성은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.

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

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

5. 아래에서 프로젝트에 추가할 수 있는

   플러그인

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

   이 튜토리얼의 목적상, 지금 단계에서는 플러그인을 추가할 필요가 없습니다.

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

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

이제 새로운 프로젝트를 생성했으므로, 이어서 Ktor 프로젝트를 압축 해제하고 실행해 보겠습니다.

IntelliJ IDEA Ultimate용 Ktor 플러그인 사용

이 섹션에서는 IntelliJ IDEA Ultimate용 Ktor 플러그인을 사용하여 프로젝트를 설정하는 방법을 설명합니다.

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

1. 시작(Welcome) 화면에서 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 서버 종속성을 추가하는 방법을 알아봅니다.
     을 선택합니다. Gradle Kotlin, Gradle Groovy, Maven, 또는 Amper 중 하나를 선택할 수 있습니다.

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

   • Configuration: 서버 매개변수를

     YAML 또는 HOCON 파일

     구성 파일에서 다양한 서버 매개변수를 구성하는 방법을 알아봅니다.
     에 지정할지, 아니면
     코드

     코드에서 다양한 서버 매개변수를 구성하는 방법을 알아봅니다.
     에 직접 지정할지 선택합니다.
     YAML 구성은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.

   이 튜토리얼의 목적상, 이러한 설정의 기본값을 그대로 두어도 됩니다.

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

   

   이 페이지에서 Ktor 애플리케이션의 공통 기능(예: 인증, 직렬화 및 콘텐츠 인코딩, 압축, 쿠키 지원 등)을 제공하는 구성 블록인

   플러그인

   플러그인은 직렬화, 콘텐츠 인코딩, 압축 등과 같은 공통 기능을 제공합니다.
   세트를 선택할 수 있습니다.

   이 튜토리얼의 목적상, 지금 단계에서는 플러그인을 추가할 필요가 없습니다.

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

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

Ktor CLI 도구 사용

이 섹션에서는 Ktor CLI 도구를 사용하여 프로젝트를 설정하는 방법을 설명합니다.

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

1. 다음 명령 중 하나를 사용하여 Ktor CLI 도구를 설치합니다:
   macOS/LinuxWindows
2. 대화형 모드(interactive mode)에서 새로운 프로젝트를 생성하려면 다음 명령을 사용합니다:
3. 프로젝트 이름으로 ktor-sample을 입력합니다:

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

4. Enter를 눌러 계속합니다.
5. 다음 단계에서는 프로젝트에 추가할
   플러그인

   플러그인은 직렬화, 콘텐츠 인코딩, 압축 등과 같은 공통 기능을 제공합니다.
   을 검색하고 추가할 수 있습니다. 플러그인은 인증, 직렬화 및 콘텐츠 인코딩, 압축, 쿠키 지원 등 Ktor 애플리케이션에서 공통 기능을 제공하는 구성 블록입니다.

   이 튜토리얼의 목적상, 지금 단계에서는 플러그인을 추가할 필요가 없습니다.

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를 실행합니다.

시작(Welcome) 화면이 나타나면 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. 오류 핸들러 등록

이 과제들은 서로 종속되어 있지는 않지만 난이도가 점차 높아집니다. 선언된 순서대로 시도하는 것이 단계적으로 학습하기 가장 쉬운 방법입니다. 단순화하고 중복을 피하기 위해 아래 설명은 과제를 순서대로 시도하는 것을 가정합니다.

코딩이 필요한 경우 코드와 해당 import를 모두 지정했습니다. IDE가 이러한 import를 자동으로 추가해 줄 수도 있습니다.

기본 포트 변경

구성 파일에서 포트 변경

구성을 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에 대한 import를 추가합니다:

4. 재실행 버튼()을 클릭하여 애플리케이션을 재시작합니다.

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

   

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

   NOTE

   서로 다른 요청을 구분하려면 세 개의 해시 기호(###)가 포함된 줄이 필요합니다.

정적 콘텐츠 구성

Project 도구 창에서 src/main/kotlin 폴더로 이동하여 다음 단계를 따르세요:

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

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

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

2. IDE가 자동으로 추가하지 않는 경우 다음 import를 추가합니다.

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 assertion을 사용하여 샘플 요청을 보내고 응답을 확인할 수 있습니다.

IntelliJ IDEA에서 테스트를 실행하는 일반적인 방법 중 하나를 사용하여 테스트를 실행할 수 있습니다. Ktor의 새로운 인스턴스를 실행하는 것이므로 테스트의 성공 또는 실패는 애플리케이션이 0.0.0.0에서 실행 중인지 여부에 의존하지 않습니다.

새로운 HTTP 엔드포인트 추가 과제를 성공적으로 완료했다면 다음 테스트를 추가해 보세요:

다음 추가 import를 추가합니다:

오류 핸들러 등록

StatusPages 플러그인

%plugin_name% 플러그인을 사용하면 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. 다음 import를 추가합니다:

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

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

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

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

2. 브라우저에서 http://0.0.0.0:9292/error-test URL로 이동합니다. 아래와 같이 오류 메시지가 표시되어야 합니다:

   

다음 단계

추가 과제의 끝까지 마쳤다면 이제 Ktor 서버 구성, Ktor 플러그인 통합 및 새로운 라우트 구현에 대한 이해를 갖추게 된 것입니다. 하지만 이것은 시작에 불과합니다. Ktor의 기본 개념을 더 깊이 탐구하려면 이 가이드의 다음 튜토리얼로 계속 진행하세요.

다음으로는

Task Manager 애플리케이션을 만들며 요청을 처리하고 응답을 생성하는 방법

Task Manager 애플리케이션을 빌드하며 Ktor와 Kotlin을 사용한 라우팅, 요청 처리 및 매개변수의 기본 사항을 알아봅니다.

을 배웁니다.