新しいKtorプロジェクトの作成、オープン、実行
このチュートリアルでは、初めてのKtorサーバープロジェクトを作成、オープン、実行する方法を学びます。一度実行できるようになれば、Ktorに慣れるための一連のタスクを試すことができます。
これは、Ktorでサーバーアプリケーションの構築を開始するためのチュートリアルシリーズの最初のものです。各チュートリアルは独立して行うこともできますが、推奨される順序に従うことを強くお勧めします。
- 新しいKtorプロジェクトを作成、オープン、実行します。
- リクエストを処理し、レスポンスを生成する。タスクマネージャーアプリケーションを構築することで、KtorとKotlinにおけるルーティング、リクエスト処理、およびパラメーターの基本を学びます。
- JSONを生成するRESTful APIを作成する。KotlinとKtorを使用してバックエンドサービスを構築する方法を、JSONファイルを生成するRESTful APIの例を交えて学びます。
- 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-appを入力します。
Configureをクリックして、設定ドロップダウンメニューを開きます:
以下の設定が利用可能です:
Build System : 希望する
ビルドシステムを選択します。これは、 KotlinまたはGroovy DSLを使用したGradle、またはMavenのいずれかです。既存のGradle/MavenプロジェクトにKtor Serverの依存関係を追加する方法を学びます。Ktor version : 必要なKtorのバージョンを選択します。
Engine : サーバーを実行するために使用する
エンジンを選択します。ネットワークリクエストを処理するエンジンについて学びます。Configuration : サーバーパラメーターを
YAMLまたはHOCONファイルで指定するか、設定ファイルでさまざまなサーバーパラメーターを設定する方法を学びます。コードで指定するかを選択します。コードでさまざまなサーバーパラメーターを設定する方法を学びます。Include samples : このオプションを有効にしたままにして、プラグインのサンプルコードを追加します。
このチュートリアルでは、これらの設定をデフォルト値のままにしておくことができます。
Doneをクリックして、設定を保存し、メニューを閉じます。
以下に、プロジェクトに追加できる
プラグインのセットがあります。プラグインは、Ktorアプリケーションで認証、シリアル化とコンテンツエンコーディング、圧縮、Cookieサポートなどの一般的な機能を提供するビルディングブロックです。プラグインは、シリアル化、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。このチュートリアルでは、この段階でプラグインを追加する必要はありません。
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-appをプロジェクト名として入力します。
Location : プロジェクトのディレクトリを指定します。
Website : パッケージ名を生成するために使用するドメインを指定します。
Artifact : このフィールドには、生成されたアーティファクト名が表示されます。
Engine : サーバーを実行するために使用する
エンジンを選択します。ネットワークリクエストを処理するエンジンについて学びます。Include samples : このオプションを有効にしたままにして、プラグインのサンプルコードを追加します。
Advanced Settingsをクリックして、追加設定メニューを展開します:
以下の設定が利用可能です:
Build System : 希望する
ビルドシステムを選択します。これは、 KotlinまたはGroovy DSLを使用したGradle、またはMavenのいずれかです。既存のGradle/MavenプロジェクトにKtor Serverの依存関係を追加する方法を学びます。Ktor version : 必要なKtorのバージョンを選択します。
Configuration : サーバーパラメーターを
YAMLまたはHOCONファイルで指定するか、設定ファイルでさまざまなサーバーパラメーターを設定する方法を学びます。コードで指定するかを選択します。コードでさまざまなサーバーパラメーターを設定する方法を学びます。
このチュートリアルでは、これらの設定をデフォルト値のままにしておくことができます。
Nextをクリックして、次のページに進みます。
このページでは、
プラグインのセットを選択できます。これらは、認証、シリアル化とコンテンツエンコーディング、圧縮、Cookieサポートなど、Ktorアプリケーションの一般的な機能を提供するビルディングブロックです。プラグインは、シリアル化、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。このチュートリアルでは、この段階でプラグインを追加する必要はありません。
Createをクリックし、IntelliJ IDEAがプロジェクトを生成し、依存関係をインストールするまで待ちます。
新しいプロジェクトを作成したので、次にアプリケーションをオープンし、探索し、実行する方法を学びます。
Ktor CLIツールを使用する
このセクションでは、Ktor CLIツールを使用したプロジェクトのセットアップについて説明します。
新しいKtorプロジェクトを作成するには、任意のターミナルを開き、以下の手順に従います:
- 以下のいずれかのコマンドを使用してKtor CLIツールをインストールします: consoleconsole
- インタラクティブモードで新しいプロジェクトを生成するには、以下のコマンドを使用します: console
- プロジェクト名としてktor-sample-appを入力します:
(オプション) プロジェクト名を下にあるLocationパスを編集することで、プロジェクトが保存される場所を変更することもできます。
- 続行するにはを押します。
- 次のステップでは、プロジェクトにプラグインを検索して追加できます。プラグインは、認証、シリアル化とコンテンツエンコーディング、圧縮、Cookieサポートなど、Ktorアプリケーションの一般的な機能を提供するビルディングブロックです。プラグインは、シリアル化、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。
このチュートリアルでは、この段階でプラグインを追加する必要はありません。
- プロジェクトを生成するにはを押します。
または、CREATE PROJECT (CTRL+G)を選択してを押すことでプロジェクトを生成することもできます。
Ktorプロジェクトを解凍して実行する
このセクションでは、コマンドラインからプロジェクトを解凍、ビルド、実行する方法を学びます。以下の説明では、以下を前提としています:
- ktor-sample-appというプロジェクトを作成し、ダウンロードしていること。
- これがホームディレクトリのmyprojectsというフォルダに配置されていること。
必要に応じて、ご自身のセットアップに合わせて名前とパスを変更してください。
任意のコマンドラインツールを開き、以下の手順に従います:
ターミナルで、プロジェクトをダウンロードしたフォルダに移動します:
consoleZIPアーカイブを同名のフォルダに解凍します:
consoleconsoleこれで、ディレクトリにはZIPアーカイブと解凍されたフォルダが含まれます。
そのディレクトリから、新しく作成されたフォルダに移動します:
consolemacOS/UNIXシステムでは、gradlew Gradleヘルパースクリプトを実行可能にする必要があります。それには、
chmodコマンドを使用します:consoleプロジェクトをビルドするには、以下のコマンドを使用します:
consoleconsoleビルドが成功したことを確認したら、再度Gradle経由でプロジェクトを実行できます。
プロジェクトを実行するには、以下のコマンドを使用します:
consoleconsoleプロジェクトが実行されていることを確認するには、出力に記載されているURL (http://0.0.0.0:8080) でブラウザを開きます。「Hello World!」というメッセージが画面に表示されるはずです:
おめでとうございます！Ktorプロジェクトの起動に成功しました。
Ktorアプリケーションを実行している基盤プロセスがビジー状態のため、コマンドラインは応答しなくなります。アプリケーションを終了するにはを押すことができます。
IntelliJ IDEAでKtorプロジェクトを開き、探索し、実行する
プロジェクトを開く
IntelliJ IDEAがインストールされている場合、コマンドラインから簡単にプロジェクトを開くことができます。
プロジェクトフォルダにいることを確認してから、現在のフォルダを表すピリオドに続けてideaコマンドを入力します:
または、プロジェクトを手動で開くにはIntelliJ IDEAを起動します。
ウェルカム画面が開いた場合は、Openをクリックします。それ以外の場合は、メインメニューのFile | New | Projectに移動し、ktor-sample-appフォルダを選択して開きます。
TIP
プロジェクトの管理に関する詳細については、IntelliJ IDEAドキュメントを参照してください。プロジェクトを探索する
どちらのオプションを選択しても、プロジェクトは以下のように開くはずです:
プロジェクトのレイアウトを説明するために、Projectビューで構造を展開し、ファイルsettings-gradle.ktsを選択しました。
アプリケーションを実行するコードはsrc/main/kotlinの下のパッケージに存在することがわかります。デフォルトのパッケージはcom.exampleという名前で、pluginsというサブパッケージを含んでいます。 これらのパッケージ内にApplication.ktとRouting.ktという2つのファイルが作成されています。
プロジェクト名はsettings-gradle.ktsで設定されます。
設定ファイルやその他の種類のコンテンツは、src/main/resourcesフォルダ内にあります。
スケルトンテストは、src/test/kotlinの下のパッケージに作成されています。
プロジェクトを実行する
右側のサイドバーにある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はこれらのインポートを自動的に追加する場合があります。
デフォルトポートを変更する
Projectビューで、src/main/kotlinフォルダに移動し、作成された単一のパッケージに入って、以下の手順に従います:
Application.ktファイルを開きます。以下のコードと同様のコードが見つかるはずです:
kotlinembeddedServer()関数で、portパラメーターを「9292」など、選択した別の番号に変更します。kotlin再実行ボタン (
) をクリックして、アプリケーションを再起動します。アプリケーションが新しいポート番号で実行されていることを確認するには、新しいURL (http://0.0.0.0:9292) でブラウザを開くか、IntelliJ IDEAで新しいHTTPリクエストファイルを作成します:
YAML経由でポートを変更する
新しいKtorプロジェクトを作成する際、設定をYAMLまたはHOCONファイルのいずれかで外部に保存するオプションがあります:
設定を外部に保存することを選択した場合、Application.ktのコードは次のようになります:
これらは、src/main/resources/内の設定ファイルに保存される値です:
この場合、ポート番号を変更するためにコードを修正する必要はありません。YAMLまたはHOCONファイル内の値を変更し、アプリケーションを再起動するだけです。変更は、上記のデフォルトポートの場合と同じ方法で確認できます。
新しいHTTPエンドポイントを追加する
次に、GETリクエストに応答する新しいHTTPエンドポイントを作成します。
Projectツールウィンドウで、src/main/kotlin/com/exampleフォルダに移動し、以下の手順に従います:
Application.ktファイルを開き、
configureRouting()関数を見つけます。IntelliJ IDEAで、関数名にキャレットを置いてを押すことで、
configureRouting()関数に移動します。または、
Routing.ktファイルを開くことで関数に移動することもできます。表示されるコードは次のとおりです:
Kotlin新しいエンドポイントを作成するには、以下の5行のコードを追加します:
kotlin/test1のURLは自由に変更できることに注意してください。ContentTypeを使用するために、以下のインポートを追加します:kotlin再実行ボタン (
) をクリックして、アプリケーションを再起動します。ブラウザで新しいURL (http://0.0.0.0:9292/test1) をリクエストします。使用するポート番号は、最初のタスク(デフォルトポートの変更)を試したかどうかによって異なります。以下に表示される出力が表示されるはずです:
HTTPリクエストファイルを作成した場合は、そこでも新しいエンドポイントを確認できます:
3つのハッシュ (###) を含む行は、異なるリクエストを区切るために必要であることに注意してください。
静的コンテンツを設定する
Projectツールウィンドウで、src/main/kotlin/com/example/pluginsフォルダに移動し、以下の手順に従います:
Routing.ktファイルを開きます。これもデフォルトのコンテンツであるはずです:
kotlinこのタスクでは、新しいHTTPエンドポイントの追加で指定された追加エンドポイントのコンテンツを挿入したかどうかは関係ありません。
ルーティングセクションに以下の行を追加します:
kotlinこの行の意味は以下のとおりです:
staticResources()を呼び出すと、Ktorは、アプリケーションがHTMLやJavaScriptファイルなどの標準的なウェブサイトコンテンツを提供できるようにしたいことを伝えます。このコンテンツはブラウザ内で実行される場合がありますが、サーバーの観点からは静的であると見なされます。- URL
/contentは、このコンテンツを取得するために使用すべきパスを指定します。 - パス
mycontentは、静的コンテンツが配置されるフォルダの名前です。Ktorはresourcesディレクトリ内でこのフォルダを探します。
以下のインポートを追加します:
kotlinProjectツールウィンドウで、
src/main/resourcesフォルダを右クリックし、New | Directoryを選択します。または、
src/main/resourcesフォルダを選択し、を押してDirectoryをクリックします。新しいディレクトリに
mycontentという名前を付け、を押します。新しく作成したフォルダを右クリックし、New | Fileをクリックします。
新しいファイルに「sample.html」という名前を付け、を押します。
新しく作成したファイルページに、例えば次のような有効なHTMLを入力します:
html再実行ボタン (
) をクリックして、アプリケーションを再起動します。http://0.0.0.0:9292/content/sample.htmlでブラウザを開くと、サンプルページの内容が表示されるはずです:
統合テストを記述する
Ktorは
これを利用するには、以下の手順に従います:
srcの下に「test」という新しいディレクトリを作成し、その中に「kotlin」というサブディレクトリを作成します。
src/test/kotlin内に「com.example」という新しいパッケージを作成します。
src/test/kotlin/com.example内に「ApplicationTest.kt」という新しいファイルを作成します。
ApplicationTest.ktファイルを開き、以下のコードを追加します:kotlintestApplication()メソッドは、Ktorの新しいインスタンスを作成します。このインスタンスは、Nettyなどのサーバーとは異なり、テスト環境内で実行されます。次に、
application()メソッドを使用して、embeddedServer()から呼び出されるのと同じセットアップを呼び出すことができます。最後に、組み込みの
clientオブジェクトとJUnitアサーションを使用して、サンプルリクエストを送信し、レスポンスを確認できます。以下の必要なインポートを追加します:
kotlin
テストは、IntelliJ IDEAでテストを実行する標準的な方法のいずれかで実行できます。Ktorの新しいインスタンスを実行しているため、テストの成功または失敗は、アプリケーションが0.0.0.0で実行されているかどうかには依存しないことに注意してください。
新しいHTTPエンドポイントの追加を正常に完了した場合、この追加テストを追加できるはずです:
以下の追加インポートが必要です:
エラーハンドラーを登録する
このプラグインは、デフォルトではプロジェクトに含まれていません。KtorプロジェクトジェネレーターのPluginsセクション、またはIntelliJ IDEAのプロジェクトウィザードを介してプロジェクトに追加することもできました。すでにプロジェクトを作成しているため、次のステップでは、プラグインを手動で追加および設定する方法を学びます。
これを行うには4つのステップがあります:
build.gradle.ktsファイルを開きます。依存関係セクションに、以下に示す追加の依存関係を追加します:
kotlinこれを行った後、新しい依存関係を認識させるためにプロジェクトをリロードする必要があります。
macOSでは、Windowsではを押してプロジェクトをリロードします。
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の基本的な概念をさらに深く掘り下げるには、このガイドの次のチュートリアルに進んでください。
次に、