Client Plugin

型安全なリクエスト

必要な依存関係: io.ktor:ktor-client-resources

コード例: client-type-safe-requests

Ktor は、型安全なリクエストを実装できるようにする Resources プラグインを提供しています。これを実現するには、サーバー上で利用可能なリソースを記述するクラスを作成し、そのクラスに @Resource キーワードを使用してアノテーションを付ける必要があります。@Resource アノテーションは、kotlinx.serialization ライブラリによって提供される @Serializable の動作を持つことに注意してください。

Ktor サーバーは、型安全なルーティングを実装する機能を提供しています。

依存関係の追加

kotlinx.serialization の追加

リソースクラスは @Serializable の動作を持つ必要があるため、Setup セクションの記述に従って Kotlin serialization プラグインを追加する必要があります。

Resources 依存関係の追加

Resources を使用するには、ビルドスクリプトに ktor-client-resources アーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

Ktor クライアントに必要なアーティファクトの詳細については、

クライアントの依存関係の追加

既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。

を参照してください。

Resources のインストール

Resources をインストールするには、クライアント設定ブロック内の install 関数に渡します。

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.resources.*
//...
val client = HttpClient(CIO) {
    install(Resources)
}

リソースクラスの作成

各リソースクラスには @Resource アノテーションを付ける必要があります。 以下では、単一のパスセグメントの定義、クエリパラメータやパスパラメータなど、いくつかのリソースクラスの例を見ていきます。

リソースの URL

以下の例は、/articles パスで応答するリソースを指定する Articles クラスの定義方法を示しています。

import io.ktor.resources.*

@Resource("/articles")
class Articles()

クエリパラメータを持つリソース

以下の Articles クラスは、クエリパラメータとして機能する sort 文字列プロパティを持っており、/articles?sort=new のようなクエリパラメータ付きのパスで応答するリソースを定義できます。

@Resource("/articles")
class Articles(val sort: String? = "new")

ネストされたクラスを持つリソース

クラスをネストして、複数のパスセグメントを含むリソースを作成できます。この場合、ネストされたクラスは外部クラスの型のプロパティを持つ必要があることに注意してください。 以下の例は、/articles/new パスで応答するリソースを示しています。

@Resource("/articles")
class Articles() {
    @Resource("new")
    class New(val parent: Articles = Articles())
}

パスパラメータを持つリソース

以下の例は、パスセグメントに一致し、id という名前のパラメータとしてキャプチャする、ネストされた {id} 整数パスパラメータを追加する方法を示しています。

@Resource("/articles")
class Articles() {
    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long)
}

例として、このリソースは /articles/12 への応答に使用できます。

例: CRUD 操作のためのリソース

上記の例をまとめて、CRUD 操作のための Articles リソースを作成してみましょう。

@Resource("/articles")
class Articles() {
    @Resource("new")
    class New(val parent: Articles = Articles())

    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long) {
        @Resource("edit")
        class Edit(val parent: Id)
    }
}

このリソースは、すべての記事のリスト表示、新しい記事の投稿、編集などに使用できます。次のセクションで、このリソースに対して型安全なリクエストを作成する方法を見ていきます。

完全な例はこちらにあります: client-type-safe-requests。

型安全なリクエストの作成

型指定されたリソースに対してリクエストを作成するには、リクエスト関数（request、get、post、put など）にリソースクラスのインスタンスを渡す必要があります。たとえば、以下のサンプルは /articles パスに対してリクエストを作成する方法を示しています。

@Resource("/articles")
class Articles()

fun main() {
    runBlocking {
        val client = HttpClient(CIO) {
            install(Resources)
            // ...
        }
        val getAllArticles = client.get(Articles())
    }
}

以下の例は、例: CRUD 操作のためのリソースで作成した Articles リソースに対して、型指定されたリクエストを作成する方法を示しています。

fun main() {
    defaultServer(Application::module).start()
    runBlocking {
        val client = HttpClient(CIO) {
            install(Resources)
            defaultRequest {
                host = "0.0.0.0"
                port = 8080
                url { protocol = URLProtocol.HTTP }
            }
        }

        val getAllArticles = client.get(Articles())
        val newArticle = client.get(Articles.New())
        val postArticle = client.post(Articles()) { setBody("Article content") }
        val getArticle = client.get(Articles.Id(id = 12))
        val editArticlePage = client.get(Articles.Id.Edit(Articles.Id(id = 12)))
        val putArticle = client.put(Articles.Id(id = 12)) { setBody("New article content") }
        val deleteArticle = client.delete(Articles.Id(id = 12))
}

defaultRequest 関数は、すべてのリクエストに対するデフォルトの URL を指定するために使用されます。

完全な例はこちらにあります: client-type-safe-requests。