Client Plugin

型安全なリクエスト

必須の依存関係: io.ktor:ktor-client-resources

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

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

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

依存関係を追加する

kotlinx.serializationを追加する

リソースクラスが@Serializableの振る舞いを持つべきであることを考慮すると、セットアップセクションで説明されているように、Kotlin serialization プラグインを追加する必要があります。

Resources の依存関係を追加する

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

Gradle (Kotlin)Gradle (Groovy)Maven

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 文字列プロパティがあり、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。