新規 Ktor プロジェクトの作成、オープン、実行
このチュートリアルでは、最初の Ktor サーバープロジェクトを作成、オープンし、実行する方法を学びます。起動して実行できるようになったら、Ktor に慣れるための一連のタスクを完了できます。
これは、Ktor を使用したサーバーアプリケーションの構築を始めるための一連のチュートリアルの最初のステップです。各チュートリアルは個別に進めることもできますが、推奨される順序に従って進めることを強くお勧めします。
- 新規 Ktor プロジェクトの作成、オープン、実行。
- リクエストの処理とレスポンスの生成タスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。。
- JSON を生成する RESTful API の作成Kotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。。
- Thymeleaf テンプレートを使用した Web サイトの作成Ktor と Thymeleaf テンプレートを使用して、Kotlin で Web サイトを構築する方法を学びます。。
- WebSocket アプリケーションの作成WebSocketの力を活用してコンテンツを送受信する方法を学びます。。
- Exposed によるデータベースの統合Exposed SQL ライブラリを使用して Ktor サービスをデータベースリポジトリに接続するプロセスを学びます。。
新規 Ktor プロジェクトの作成
新しい Ktor プロジェクトを作成する最も速い方法の 1 つは、Web ベースの Ktor プロジェクトジェネレーターを使用することです。
あるいは、IntelliJ IDEA Ultimate 向けの専用 Ktor プラグインまたは Ktor CLI ツールを使用してプロジェクトを生成することもできます。
Ktor プロジェクトジェネレーターの使用
Ktor プロジェクトジェネレーターを使用して新しいプロジェクトを作成するには、以下の手順に従います。
Ktor プロジェクトジェネレーターにアクセスします。
Project artifact フィールドに、プロジェクトのアーティファクト名として com.example.ktor-sample を入力します。

Configure をクリックして設定のドロップダウンメニューを開きます。

以下の設定が利用可能です。
Build System : 希望するビルドシステム既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。を選択します。 Gradle Kotlin、 Gradle Groovy、 Maven、または Amper から選択できます。
Engine : サーバーの実行に使用するエンジンネットワークリクエストを処理するエンジンについて学びます。を選択します。
Configuration : サーバーパラメータを YAML または HOCON ファイルで構成ファイルでさまざまなサーバーパラメータを設定する方法について説明します。指定するか、コード内でコード内でさまざまなサーバーパラメータを設定する方法を学びます。指定するかを選択します。
現在、Maven ベースの Ktor プロジェクトでは YAML 設定はサポートされていません。
このチュートリアルでは、これらの設定をデフォルト値のままにしておいて構いません。
Done をクリックして設定を保存し、メニューを閉じます。
下部には、プロジェクトに追加できる一連のプラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。が表示されます。プラグインは、認証、シリアライズやコンテンツエンコーディング、圧縮、Cookie サポートなど、Ktor アプリケーションで一般的な機能を提供する構成要素です。
このチュートリアルでは、現段階でプラグインを追加する必要はありません。
Download ボタンをクリックして、Ktor プロジェクトを生成してダウンロードします。

ダウンロードが自動的に開始されます。
新しいプロジェクトを生成したら、次は Ktor プロジェクトの展開と実行 に進みましょう。
IntelliJ IDEA Ultimate 向け Ktor プラグインの使用
このセクションでは、IntelliJ IDEA Ultimate 向けの Ktor プラグインを使用したプロジェクトのセットアップについて説明します。
新しい Ktor プロジェクトを作成するには、IntelliJ IDEA を開き、以下の手順に従います。
ウェルカム画面で New Project をクリックします。
または、メインメニューから File | New | Project を選択します。
New Project ウィザードで、左側のリストから Ktor を選択します。
右側のペインで、以下の設定を指定できます。

Name: プロジェクト名を指定します。プロジェクト名として ktor-sample を入力します。
Location: プロジェクト用のディレクトリを指定します。
Website : パッケージ名の生成に使用されるドメインを指定します。
Artifact : このフィールドには生成されたアーティファクト名が表示されます。
Engine : サーバーの実行に使用するエンジンネットワークリクエストを処理するエンジンについて学びます。を選択します。
Include samples : プラグインのサンプルコードを追加するには、このオプションを有効のままにしておきます。
Advanced Settings をクリックして、追加設定メニューを展開します。

以下の設定が利用可能です。
Build System : 希望するビルドシステム既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。を選択します。 Gradle Kotlin、 Gradle Groovy、 Maven、または Amper から選択できます。
Ktor version : 必要な Ktor バージョンを選択します。
Configuration : サーバーパラメータを YAML または HOCON ファイルで構成ファイルでさまざまなサーバーパラメータを設定する方法について説明します。指定するか、コード内でコード内でさまざまなサーバーパラメータを設定する方法を学びます。指定するかを選択します。
現在、Maven ベースの Ktor プロジェクトでは YAML 設定はサポートされていません。
このチュートリアルでは、これらの設定をデフォルト値のままにしておいて構いません。
Next をクリックして次のページに進みます。

このページでは、認証、シリアライズやコンテンツエンコーディング、圧縮、Cookie サポートなど、Ktor アプリケーションの一般的な機能を提供する構成要素である一連のプラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。を選択できます。
このチュートリアルでは、現段階でプラグインを追加する必要はありません。
Create をクリックし、IntelliJ IDEA がプロジェクトを生成して依存関係をインストールするまで待ちます。
新しいプロジェクトを作成したら、次はアプリケーションの開き方、確認方法、実行方法を学びましょう。
Ktor CLI ツールの使用
このセクションでは、Ktor CLI ツールを使用したプロジェクトのセットアップについて説明します。
新しい Ktor プロジェクトを作成するには、任意のターミナルを開き、以下の手順に従います。
- 以下のいずれかのコマンドを使用して Ktor CLI ツールをインストールします。 console
brew install ktorconsolewinget install JetBrains.KtorCLI - 対話モードで新しいプロジェクトを生成するには、次のコマンドを使用します。 console
ktor new - プロジェクトの名前として ktor-sample を入力します。

(オプション) プロジェクト名の下にある Location のパスを編集して、プロジェクトが保存される場所を変更することもできます。
- Enter を押して次に進みます。
- 次のステップでは、プロジェクトにプラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。を検索して追加できます。プラグインは、認証、シリアライズやコンテンツエンコーディング、圧縮、Cookie サポートなど、Ktor アプリケーションで一般的な機能を提供する構成要素です。

このチュートリアルでは、現段階でプラグインを追加する必要はありません。
- Ctrl+G を押してプロジェクトを生成します。
あるいは、 CREATE PROJECT (CTRL+G) を選択して Enter を押すことでもプロジェクトを生成できます。
Ktor プロジェクトの展開と実行
このセクションでは、コマンドラインからプロジェクトを展開、ビルド、実行する方法を学びます。以下の手順では、以下を前提としています。
- ktor-sample という名前の Gradle プロジェクトを作成してダウンロード済みであること。
- このプロジェクトが、ホームディレクトリ内の myprojects というフォルダーにあること。
必要に応じて、ご自身の環境に合わせて名前やパスを変更してください。
任意のコマンドラインツールを開き、以下の手順に従います。
ターミナルウィンドウで、プロジェクトをダウンロードしたフォルダーに移動します。
consolecd ~/myprojects同名のフォルダーに ZIP アーカイブを展開します。
consoleunzip ktor-sample.zip -d ktor-sampleconsoletar -xf ktor-sample.zipこれで、ディレクトリには ZIP アーカイブと展開されたフォルダーが含まれるようになります。
ディレクトリから、新しく作成されたフォルダーに移動します。
consolecd ktor-samplemacOS および UNIX システムでは、システムが実行可能コマンドとして認識できるように、Gradle ヘルパースクリプトを実行可能にする必要があります。これを行うには、
chmodコマンドを使用します。consolechmod +x ./gradlewプロジェクトをビルドするには、次のコマンドを使用します。
console./gradlew buildconsolegradlew buildビルドが成功したら、次のステップに進んでプロジェクトを実行します。
プロジェクトを実行するには、次のコマンドを使用します。
console./gradlew runconsolegradlew runプロジェクトが実行されていることを確認するには、ターミナル出力に表示されている URL(http://0.0.0.0:8080)をブラウザで開きます。 ブラウザに「Hello World!」というメッセージが表示されるはずです。

おめでとうございます!Ktor プロジェクトが正常に起動しました。
IntelliJ IDEA での Ktor プロジェクトのオープン、確認、実行
プロジェクトを開く
IntelliJ IDEA がインストールされている場合は、コマンドラインから簡単にプロジェクトを開くことができます。
プロジェクトフォルダー内にいることを確認し、idea コマンドの後に現在のフォルダーを表すピリオド(.)を入力します。
idea .または、手動でプロジェクトを開く場合は、IntelliJ IDEA を起動します。
ウェルカム画面が開いた場合は、 Open をクリックします。それ以外の場合は、メインメニューの File | Open に移動し、 ktor-sample フォルダーを選択して開きます。
プロジェクトの構造を確認する
プロジェクトを開くと、以下のような構造が表示されます。

全体の構造を確認するには、各フォルダーの横にある展開矢印をクリックして、Project ビュー内のフォルダーを展開します。
アプリケーションのソースコードは src/main/kotlin 配下にあります。デフォルトでは、 Application.kt と Routing.kt という 2 つのファイルが作成されます。

プロジェクトの名前は settings.gradle.kts ファイルで設定されています。
rootProject.name = "ktor-sample"設定ファイルやその他のコンテンツは、 src/main/resources フォルダー内に配置されます。

プロジェクトの実行
右側のサイドバーにある Gradle アイコン(
)をクリックして、Gradle ツールウィンドウを開きます。
このツールウィンドウ内で Tasks | application に移動し、 run タスクをダブルクリックします。

Ktor アプリケーションが IDE の下部にある Run ツールウィンドウで起動します。

以前にコマンドラインに表示されていたものと同じメッセージが、 Run ツールウィンドウに表示されます。
プロジェクトが実行中であることを確認するには、指定された URL (http://0.0.0.0:8080)をブラウザで開きます。
再び画面に「Hello World!」というメッセージが表示されるはずです。

IntelliJ IDEA 内からプロジェクトを実行するには:
アプリケーションは Run ツールウィンドウから管理できます。
- アプリケーションを終了するには、停止ボタン
をクリックします。
- プロセスを再起動するには、再実行ボタン
をクリックします。
これらのオプションについて詳しくは、IntelliJ IDEA Run ツールウィンドウのドキュメントで説明されています。
追加で試せるタスク
試してみたい追加のタスクをいくつか紹介します。
これらのタスクは相互に依存しているわけではありませんが、難易度が徐々に上がっていきます。宣言された順序で試すことが、段階的に学習するための最も簡単な方法です。分かりやすくし重複を避けるため、以下の説明はタスクを順番に試していることを前提としています。
コーディングが必要な箇所では、コードと対応するインポートの両方を指定しています。IDE がこれらのインポートを自動的に追加する場合もあります。
デフォルトポートの変更
設定ファイルでポートを変更する
設定を外部の YAML または HOCON ファイルに保存することを選択した場合は、 Project ビューで src/main/resources フォルダーに移動し、以下の手順に従います。
- 設定ファイル( application.yaml または application.conf )を開きます。以下のようになっているはずです。 yaml
ktor: deployment: port: 8080 application: modules: - com.example.RoutingKt.configureRoutinggenericktor { deployment { port = 8080 port = ${?PORT} } application { modules = [ com.example.RoutingKt.configureRouting ] } } - ファイル内の
portの値を、9292など任意の別の数値に変更します。 再実行ボタン(
)をクリックして、アプリケーションを再起動します。
アプリケーションが新しいポート番号で実行されていることを確認するには、ブラウザで新しい URL(http://0.0.0.0:9292)を開くか、IntelliJ IDEA で新しい HTTP Request ファイルを作成します。

コード内でポートを変更する
新しい Ktor プロジェクトを作成するときに、設定をコード内に保存するか、外部の YAML または HOCON ファイル内に保存するかを選択できます。
設定をコード内に保存するオプションを選択した場合は、 Project ビューで src/main/kotlin フォルダーに移動し、以下の手順に従います。
main.kt ファイルを開きます。次のようなコードが見つかるはずです。
kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 8080, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }embeddedServer()関数内で、portパラメータを9292など任意の別の数値に変更します。kotlinfun main(args: Array<String>) { embeddedServer( factory = io.ktor.server.netty.Netty, port = 9292, host = "0.0.0.0", module = Application::rootModule ).start(wait = true) }再実行ボタン(
)をクリックして、アプリケーションを再起動します。
アプリケーションが新しいポート番号で実行されていることを確認するには、ブラウザで新しい URL(http://0.0.0.0:9292)を開くか、IntelliJ IDEA で新しい HTTP Request ファイルを作成します。

新しい HTTP エンドポイントの追加
Project ツールウィンドウで、 src/main/kotlin フォルダーに移動し、以下の手順に従います。
Routing.kt ファイルを開きます。次のようなコードが表示されます。
kotlinfun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }新しいエンドポイントを作成するには、以下のように追加のルートを挿入します。
kotlinfun Application.configureRouting() { routing { // ... get("/test1") { val text = "<h1>Hello From Ktor</h1>" val type = ContentType.parse("text/html") call.respondText(text, type) } } }URL/test1は好みの任意のものに変更できることに注意してください。IDE が
ContentTypeのインポートを自動的に追加します。kotlinimport io.ktor.http.ContentType再実行ボタン(
)をクリックして、アプリケーションを再起動します。
ブラウザで新しい URL(http://0.0.0.0:9292/test1)をリクエストします。ポート番号は、デフォルトポートの変更 タスクを完了したかどうかによって異なります。以下のような出力が表示されるはずです。

HTTP リクエストファイルを作成している場合は、そこから新しいエンドポイントを確認することもできます。
httpGET http://0.0.0.0:9292 ### GET http://0.0.0.0:9292/test1異なるリクエストを区切るには、3 つのハッシュ記号(###)を含む行が必要であることに注意してください。
静的コンテンツの設定
Project ツールウィンドウで、 src/main/kotlin フォルダーに移動し、以下の手順に従います。
Routing.kt ファイルを開き、routing セクションに以下のルートを追加します。
kotlinfun Application.configureRouting() { routing { staticResources("/content", "mycontent") // ... } }この行の意味は以下のとおりです。
staticResources()を呼び出すと、アプリケーションが HTML や JavaScript ファイルなどの標準的な Web サイトコンテンツを提供できるようになります。このコンテンツはブラウザ内で実行できますが、サーバーの観点からは静的であるとみなされます。- URL
/contentは、このコンテンツを取得するために使用されるパスを指定します。 - パス
mycontentは、静的コンテンツが配置されるフォルダーの名前です。Ktor はresourcesディレクトリ内でこのフォルダーを検索します。
IDE が自動的に追加しない場合は、次のインポートを追加します。
kotlinimport io.ktor.server.http.content.staticResourcesProject ツールウィンドウで、src/main/resources フォルダーを右クリックし、 New | Directory を選択します。
または、src/main/resources フォルダーを選択して ⌘Cmd+N(macOS)または Ctrl+N(Windows/Linux)を押し、 Directory をクリックします。
新しいディレクトリに
mycontentと名前を付け、 ↩Enter を押します。新しく作成したフォルダーを右クリックし、 New | File をクリックします。
新しいファイルに sample.html と名前を付け、 ↩Enter を押します。
新しく作成したファイルページに、有効な 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>再実行ボタン(
)をクリックして、アプリケーションを再起動します。
ブラウザで http://0.0.0.0:9292/content/sample.html を開くと、サンプルページの内容が表示されます。

統合テストの記述
Ktor は統合テストの作成特別なテストエンジンを使用してサーバーアプリケーションをテストする方法を学びます。をサポートしており、生成されたプロジェクトにはこの機能が最初から組み込まれています。
これを利用するには、以下の手順に従います。
src/test/kotlin フォルダーに移動します。
ServerTest.kt ファイルを開きます。以下のようなコードが表示されるはずです。
kotlinclass 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 アサーションを使用して、サンプルのリクエストを送信し、レスポンスを確認できます。
IntelliJ IDEA でテストを実行する標準的な方法のいずれかを使用して、テストを実行できます。Ktor の新しいインスタンスを実行しているため、テストの成否はアプリケーションが 0.0.0.0 で実行されているかどうかには依存しないことに注意してください。
新しい HTTP エンドポイントの追加が正常に完了している場合は、次のテストを追加します。
@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 io.ktor.http.contentType
import io.ktor.client.statement.bodyAsTextエラーハンドラーの登録
Ktor アプリケーションのエラーは、StatusPages プラグインStatusPages により、Ktor アプリケーションはスローされた例外やステータスコードに基づいて、あらゆる障害状態に適切に応答できるようになります。を使用して処理できます。
次のステップでは、プラグインを手動で追加および設定する方法を学びます。これを行うには 4 つのステップがあります。
新しい依存関係の追加
build.gradle.kts ファイルを開き、以下のように新しい依存関係を追加します。
kotlindependencies { 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) }Shift+⌘Cmd+I(macOS)または Ctrl+Shift+O(Windows/Linux)を押して、プロジェクトをリロードします。
Project ツールウィンドウで、プロジェクトのルートフォルダーに移動し、以下の手順に従います。
プラグインのインストールと例外ハンドラーの指定
Routing.kt の
.configureRouting()メソッドに移動し、以下のコード行を追加します。kotlinfun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { // ... } }これらの行は
StatusPagesプラグインをインストールし、IllegalStateException型の例外がスローされたときに実行するアクションを指定します。次のインポートを追加します。
kotlinimport io.ktor.server.plugins.statuspages.StatusPages
通常、レスポンスには HTTP エラーコードが設定されますが、このタスクの目的上、出力はブラウザに直接表示されます。
ハンドラーをトリガーするサンプルコードの記述
.configureRouting()メソッド内で、以下のように追加のルートを追加します。kotlinfun 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") } } }これで、URL
/error-testを持つエンドポイントが追加されました。このエンドポイントがトリガーされると、ハンドラーで使用されている型の例外がスローされます。
再起動してサンプルコードを呼び出す
再実行ボタン(
)をクリックして、アプリケーションを再起動します。
ブラウザで、URL http://0.0.0.0:9292/error-test にアクセスします。以下のようにエラーメッセージが表示されるはずです。

次のステップ
追加のタスクを最後まで終えたなら、Ktor サーバーの設定、Ktor プラグインの統合、および新しいルートの実装について理解できたはずです。しかし、これはほんの始まりに過ぎません。Ktor の基本概念についてさらに深く掘り下げるには、このガイドの次のチュートリアルに進んでください。
次回は、タスクマネージャーアプリケーションの作成を通じて、リクエストを処理しレスポンスを生成する方法タスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。を学びます。
