新しいKtorプロジェクトの作成、オープン、実行
新しいKtorプロジェクトの作成、オープン、実行
このチュートリアルでは、最初のKtorサーバープロジェクトを作成、オープン、および実行する方法を学びます。プロジェクトが起動して実行されたら、一連のタスクを完了してKtorに慣れることができます。
これは、Ktorを使用したサーバーアプリケーション構築を開始するための一連のチュートリアルの最初のステップです。各チュートリアルは独立して行うことができますが、以下の推奨される順序に従うことを強くお勧めします。
- 新しいKtorプロジェクトの作成、オープン、実行。
- リクエストの処理とレスポンスの生成。タスク管理アプリケーションを構築することで、Ktorを使用したKotlinでのルーティング、リクエスト処理、およびパラメータの基本を学びます。
- JSONを生成するRESTful APIの作成。JSONファイルを生成するRESTful APIの例を特徴とする、KotlinとKtorを使用したバックエンドサービスの構築方法を学びます。
- Thymeleafテンプレートを使用したウェブサイトの作成。KtorとThymeleafテンプレートを使用してKotlinでウェブサイトを構築する方法を学びます。
- WebSocketアプリケーションの作成。WebSocketのパワーを活用してコンテンツを送信および受信する方法を学びます。
- Exposedを使用したデータベースの統合。Exposed SQLライブラリを使用して、Ktorサービスをデータベースリポジトリに接続するプロセスを学びます。
新しいKtorプロジェクトの作成
新しいKtorプロジェクトを作成する最も速い方法の1つは、ウェブベースのKtorプロジェクトジェネレーターを使用することです。
あるいは、IntelliJ IDEA Ultimate専用のKtorプラグインまたはKtor CLIツールを使用してプロジェクトを生成することもできます。
Ktorプロジェクトジェネレーターの使用
Ktorプロジェクトジェネレーターで新しいプロジェクトを作成するには、以下の手順に従ってください。
Ktorプロジェクトジェネレーターにアクセスします。
Project artifactフィールドに、プロジェクトアーティファクトの名前として com.example.ktor-sample と入力します。
Configureをクリックして、設定ドロップダウンメニューを開きます。
以下の設定が利用可能です：
Build System： 希望する
ビルドシステムを選択します。 これはGradle Kotlin、Gradle Groovy、Maven、またはAmperにすることができます。既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。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 Kotlin、Gradle Groovy、Maven、またはAmperにすることができます。既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。Ktor version： 必要なKtorバージョンを選択します。
Configuration： サーバーパラメータを
YAMLまたはHOCONファイルで指定するか、構成ファイルでさまざまなサーバーパラメータを構成する方法を学びます。コード内で指定するかを選択します。コード内でさまざまなサーバーパラメータを構成する方法を学びます。現在、Mavenベース의 KtorプロジェクトではYAML構成はサポートされていません。
このチュートリアルでは、これらの設定はデフォルト値のままで構いません。
Nextをクリックして次のページに進みます。
このページでは、一連の
プラグイン（認証、シリアル化とコンテンツエンコーディング、圧縮、Cookieのサポートなど、Ktorアプリケーションの一般的な機能を提供する構成要素）を選択できます。プラグインは、シリアル化、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。このチュートリアルでは、現段階でプラグインを追加する必要はありません。
Createをクリックし、IntelliJ IDEAがプロジェクトを生成して依存関係をインストールするまで待ちます。
新しいプロジェクトを作成したので、続けてアプリケーションのオープン、探索、および実行方法を学習してください。
Ktor CLIツールの使用
このセクションでは、Ktor CLIツールを使用したプロジェクトのセットアップについて説明します。
新しいKtorプロジェクトを作成するには、お好みのターミナルを開き、以下の手順に従ってください。
- 以下のいずれかのコマンドを使用して、Ktor CLIツールをインストールします。 consoleconsole
- 対話モードで新しいプロジェクトを生成するには、次のコマンドを使用します。 console
- プロジェクト名としてktor-sampleと入力します。
（オプション）プロジェクト名の下のLocationパスを編集することで、プロジェクトが保存される場所を変更することもできます。
Enter を押して続行します。- 次のステップでは、プロジェクトにプラグインを検索して追加できます。プラグインは、認証、シリアル化とコンテンツエンコーディング、圧縮、Cookieのサポートなど、Ktorアプリケーションで一般的な機能を提供する構成要素です。プラグインは、シリアル化、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。
このチュートリアルでは、現段階でプラグインを追加する必要はありません。
CTRL+G を押してプロジェクトを生成します。あるいは、CREATE PROJECT (CTRL+G)を選択して
Enter を押すことでもプロジェクトを生成できます。
Ktorプロジェクトの展開と実行
このセクションでは、コマンドラインからプロジェクトを展開、ビルド、および実行する方法を学びます。以下の手順は、次のような状況を想定しています。
- ktor-sampleという名前のGradleプロジェクトを作成し、ダウンロードした。
- このプロジェクトは、ホームディレクトリのmyprojectsというフォルダに配置されている。
必要に応じて、自身のセットアップに合わせて名前とパスを変更してください。
お好みのコマンドラインツールを開き、以下の手順に従います。
ターミナルウィンドウで、プロジェクトをダウンロードしたフォルダに移動します。
consoleZIPアーカイブを同名のフォルダに展開します。
consoleconsoleディレクトリには、ZIPアーカイブと展開されたフォルダが含まれるようになります。
ディレクトリから、新しく作成されたフォルダに移動します。
consolemacOSおよびUNIXシステムでは、システムが実行可能なコマンドとして認識できるように、Gradleヘルパースクリプトを実行可能にする必要があります。これを行うには、
chmodコマンドを使用します。consoleプロジェクトをビルドするには、次のコマンドを使用します。
consoleconsoleビルドが成功したら、次のステップに進んでプロジェクトを実行します。
プロジェクトを実行するには、次のコマンドを使用します。
consoleconsoleプロジェクトが実行されていることを確認するには、ターミナル出力に表示されているURL（http://0.0.0.0:8080）をブラウザで開きます。 ブラウザに「Hello World!」というメッセージが表示されるはずです。
おめでとうございます！Ktorプロジェクトの起動に成功しました。
NOTE
基盤となるプロセスがKtorアプリケーションの実行でビジー状態であるため、コマンドラインが応答しなくなることに注意してください。IntelliJ IDEAでのKtorプロジェクトのオープン、探索、および実行
プロジェクトをオープンする
IntelliJ IDEAがインストールされている場合は、コマンドラインから簡単にプロジェクトを開くことができます。
プロジェクトフォルダ内にいることを確認し、ideaコマンドに続けて、現在のフォルダを表すピリオドを入力します。
または、手動でプロジェクトを開くには、IntelliJ IDEAを起動します。
ウェルカム画面が開いた場合は、Openをクリックします。そうでない場合は、メインメニューのFile | Openに移動し、ktor-sampleフォルダを選択して開きます。
TIP
プロジェクトの管理に関する詳細は、IntelliJ IDEAのドキュメントを参照してください。プロジェクトを探索する
プロジェクトを開くと、次のような構造が表示されます。
完全なレイアウトを表示するには、各フォルダの横にある展開矢印をクリックして、Projectビューのフォルダを展開します。
アプリケーションのソースコードは、src/main/kotlinの下にあります。デフォルトで、Application.ktとRouting.ktという2つのファイルが作成されます。
プロジェクト名はsettings.gradle.ktsファイルで構成されています。
構成ファイルやその他の種類のコンテンツは、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実行ツールウィンドウのドキュメントを参照してください。
試してみるべき追加タスク
試してみることをお勧めする追加タスクをいくつか紹介します：
これらのタスクは互いに依存していませんが、徐々に難易度が上がっていきます。宣言された順序で試すことが、段階的に学習するための最も簡単な方法です。簡単にするため、また重複を避けるため、以下の説明はタスクを順番に試していることを前提としています。
コーディングが必要な箇所については、コードと対応するインポートの両方を指定しています。IDEがこれらのインポートを自動的に追加してくれる場合もあります。
デフォルトポートの変更
構成ファイルでのポート変更
構成を外部のYAMLまたはHOCONファイルに保存することを選択した場合、Projectビューでsrc/main/resourcesフォルダに移動し、以下の手順に従います。
- 構成ファイル（application.yamlまたはapplication.conf）を開きます。次のようになっているはずです： yamlgeneric
- ファイル内の
portの値を、9292など、任意の見慣れない番号に変更します。 再実行ボタン（
）をクリックして、アプリケーションを再起動します。アプリケーションが新しいポート番号で実行されていることを確認するには、新しいURL（http://0.0.0.0:9292）をブラウザで開くか、IntelliJ IDEAで新しいHTTPリクエストファイルを作成します。
コード内でのポート変更
新しいKtorプロジェクトを作成する際、構成をコード内に保存するか、外部のYAMLまたはHOCONファイルに保存するかを選択できます。
構成をコード内に保存することを選択した場合、Projectビューでsrc/main/kotlinフォルダに移動し、以下の手順に従います。
main.ktファイルを開きます。次のようなコードが見つかるはずです。
kotlinembeddedServer()関数内で、portパラメータを9292など、任意の別の番号に変更します。kotlin再実行ボタン（
）をクリックして、アプリケーションを再起動します。アプリケーションが新しいポート番号で実行されていることを確認するには、新しいURL（http://0.0.0.0:9292）をブラウザで開くか、IntelliJ IDEAで新しいHTTPリクエストファイルを作成します。
新しいHTTPエンドポイントの追加
Projectツールウィンドウで、src/main/kotlinフォルダに移動し、以下の手順に従います。
Routing.ktファイルを開きます。次のようなコードが表示されるはずです：
Kotlin新しいエンドポイントを作成するには、次のように追加のルートを挿入します。
kotlinNOTE
/test1というURLは、好きなものに変更できることに注意してください。IDEは自動的に
ContentTypeのインポートを追加します。kotlin再実行ボタン（
）をクリックして、アプリケーションを再起動します。ブラウザで新しいURL（http://0.0.0.0:9292/test1）をリクエストします。ポート番号は、デフォルトポートの変更タスクを完了したかどうかによって異なります。以下のような出力が表示されるはずです。
HTTPリクエストファイルを作成した場合は、そこでも新しいエンドポイントを確認できます。
httpNOTE
異なるリクエストを区切るには、3つのハッシュ（###）を含む行が必要であることに注意してください。
静的コンテンツの構成
Projectツールウィンドウで、src/main/kotlinフォルダに移動し、以下の手順に従います。
Routing.ktファイルを開き、ルーティングセクションに次のルートを追加します。
kotlinこの行の意味は次のとおりです：
staticResources()を呼び出すことで、アプリケーションがHTMLやJavaScriptファイルなどの標準的なウェブサイトコンテンツを提供できるようになります。このコンテンツはブラウザ内で実行できますが、サーバーの観点からは静的であると見なされます。- URL
/contentは、このコンテンツを取得するために使用されるパスを指定します。 - パス
mycontentは、静的コンテンツを配置するフォルダの名前です。Ktorは、このフォルダをresourcesディレクトリ内で探します。
IDEが自動的に追加しない場合は、次のインポートを追加してください。
kotlinProjectツールウィンドウで、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再実行ボタン（
）をクリックして、アプリケーションを再起動します。ブラウザでhttp://0.0.0.0:9292/content/sample.htmlを開くと、サンプルページの内容が表示されるはずです。
統合テストの作成
Ktorは
これを利用するには、以下の手順に従ってください。
src/test/kotlinフォルダに移動します。
ServerTest.ktファイルを開きます。次のコードが表示されるはずです：
kotlintestApplication()関数は、Ktorの新しいインスタンスを作成します。このインスタンスは、Nettyなどのサーバーではなく、テスト環境内で実行されます。次に、
configure()関数を使用して、embeddedServer()から呼び出されるのと同じセットアップを呼び出すことができます。最後に、組み込みの
clientオブジェクトとJUnitアサーションを使用して、サンプルリクエストを送信し、レスポンスを確認できます。
IntelliJ IDEAでテストを実行する標準的な方法のいずれかでテストを実行できます。Ktorの新しいインスタンスを実行しているため、テストの成否はアプリケーションが0.0.0.0で実行されているかどうかには依存しないことに注意してください。
新しいHTTPエンドポイントの追加に成功した場合は、この追加のテストを追加してください：
以下の追加のインポートを追加します：
エラーハンドラーの登録
TIP
このプラグインは、デフォルトではプロジェクトに含まれていません。Ktorプロジェクトジェネレーター、またはIntelliJ IDEAのプロジェクトウィザードでプロジェクトを作成する際に、Pluginsセクションから追加できます。次のステップでは、プラグインを手動で追加および構成する方法を学びます。これを達成するための4つのステップがあります：
- Gradleビルドファイルに新しい依存関係を追加する。
- プラグインをインストールし、例外ハンドラーを指定する。
- ハンドラーをトリガーするためのサンプルコードを作成する。
- サンプルコードを再起動して呼び出す。
build.gradle.ktsファイルを開き、次のように新しい依存関係を追加します：
kotlinShift+⌘Cmd+I （macOS）またはCtrl+Shift+O （Windows/Linux）を押して、プロジェクトをリロードします。
Projectツールウィンドウで、プロジェクトのルートフォルダに移動し、以下の手順に従います。
Routing.ktの
.configureRouting()メソッドに移動し、次のコード行を追加します：kotlinこれらの行は、
StatusPagesプラグインをインストールし、IllegalStateException型の例外がスローされたときにどのようなアクションを実行するかを指定します。以下のインポートを追加します：
kotlin
通常、レスポンスにはHTTPエラーコードが設定されますが、このタスクの目的上、出力はブラウザに直接表示されます。
.configureRouting()メソッド内にとどまり、次のように追加のルートを追加します：kotlinこれで、URL
/error-testを持つエンドポイントが追加されました。このエンドポイントがトリガーされると、ハンドラーで使用されている型の例外がスローされます。
再実行ボタン（
）をクリックして、アプリケーションを再起動します。ブラウザで、URL http://0.0.0.0:9292/error-testにアクセスします。次のようにエラーメッセージが表示されるはずです：
次のステップ
追加タスクの最後まで到達したなら、Ktorサーバーの構成、Ktorプラグインの統合、および新しいルートの実装について理解できたはずです。しかし、これはほんの始まりに過ぎません。Ktorの基礎的な概念をさらに深く掘り下げるには、このガイドの次のチュートリアルに進んでください。
次は、