Skip to content
Client Plugin

型安全なリクエスト

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

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

Ktor は、型安全なクライアントリクエストを行うための Resources プラグインを提供しています。 これを実現するには、サーバーエンドポイントを表すクラスを定義し、それに @Resource キーワードでアノテーションを付与します。

リソースクラスは kotlinx.serialization を使用して、プロパティをパスパラメータおよびクエリパラメータに変換します。

サーバー側では、Ktor は型安全なルーティングを提供しています。

依存関係の追加 ​

kotlinx.serialization の追加 ​

Resources プラグインは kotlinx.serialization に依存しています。kotlinx.serialization セットアップガイドの説明に従って、Kotlin シリアライゼーションプラグインを有効にしてください。

Resources の依存関係の追加 ​

Resources を使用するには、ビルドスクリプトに ktor-client-resources アーティファクトを追加します:

kotlin
implementation(ktorLibs.client.resources)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
groovy
implementation ktorLibs.client.resources
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-resources-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor クライアントで必要なアーティファクトの詳細については、クライアントの依存関係の追加既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。を参照してください。

Resources のインストール ​

Resources プラグインをインストールするには、クライアント設定ブロックで install 関数に渡します:

kotlin
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 クラスを定義する方法を示しています。

kotlin
import io.ktor.resources.*

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

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

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

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

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

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

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

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

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

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

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

例: CRUD 操作用のリソース ​

以下の例では、CRUD 操作用の Articles リソースを作成します:

kotlin
@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 パスにリクエストを送信します:

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

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

以下の例では、例: CRUD 操作用のリソース で作成した Articles リソースに対して型付けされたリクエストを送信します。

kotlin
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 を指定します。

クライアントプラグインや計装(インストルメンテーション)を開発する際、RESOURCE リクエスト属性を介して型安全なリクエストに使用されたリソースインスタンスにアクセスできます:

kotlin
onRequest { call, _ ->
  val resource = call.attributes.getOrNull(RESOURCE)
}

完全なサンプルコードについては、client-type-safe-requests を参照してください。