Skip to content
Server Plugin

型安全なルーティング

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

コード例: resource-routing

Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

Ktorは、型安全なルーティングを実装できる Resources プラグインを提供しています。これを行うには、型付きルートとして機能するクラスを作成し、そのクラスに @Resource キーワードでアノテーションを付加する必要があります。なお、@Resource アノテーションは kotlinx.serialization ライブラリによって提供される @Serializable の振る舞いを持ちます。

Ktorクライアントは、サーバーに対して型付きリクエストを送信する機能を提供します。

依存関係の追加 ​

kotlinx.serialization の追加 ​

リソースクラスは @Serializable の振る舞いを持つ必要があるため、Setup セクションで説明されているようにKotlinシリアライゼーションプラグインを追加する必要があります。

Resources 依存関係の追加 ​

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

kotlin
implementation(ktorLibs.server.resources)
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.resources
上記のコードスニペットでは、Ktorの依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-resources-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Resources のインストール ​

アプリケーションに Resources プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 次の例は、Resources をインストールする方法を示しています。

  • embeddedServer() 関数の呼び出し内。
  • Application クラスで明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.resources.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Resources)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
    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(val sort: String? = "new") {
    @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)
    }
}

このリソースは、すべての記事の一覧表示、新しい記事の投稿、編集などに使用できます。次のセクションで、このリソースに対するルートハンドラーの定義方法を見ていきます。

完全な例はこちらで確認できます: resource-routing。

ルートハンドラーの定義 ​

型付きリソースに対するルートハンドラーを定義するには、動詞関数(get、post、put など)にリソースクラスを渡す必要があります。 例えば、以下のルートハンドラーは /articles パスに応答します。

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

fun Application.module() {
    install(Resources)
    routing {
        get<Articles> { articles ->
            // すべての記事を取得 ...
            call.respondText("List of articles: $articles")
        }
    }
}

以下の例は、例: CRUD操作用のリソース で作成した Articles リソースに対してルートハンドラーを定義する方法を示しています。ルートハンドラー内では、パラメータとして Article にアクセスし、そのプロパティ値を取得できる点に注意してください。

kotlin
fun Application.module() {
    install(Resources)
    routing {
        get<Articles> { article ->
            // すべての記事を取得 ...
            call.respondText("List of articles sorted starting from ${article.sort}")
        }
        get<Articles.New> {
            // 新しい記事を作成するためのフィールドを持つページを表示 ...
            call.respondText("Create a new article")
        }
        post<Articles> {
            // 記事を保存 ...
            call.respondText("An article is saved", status = HttpStatusCode.Created)
        }
        get<Articles.Id> { article ->
            // idが ${article.id} の記事を表示 ...
            call.respondText("An article with id ${article.id}", status = HttpStatusCode.OK)
        }
        get<Articles.Id.Edit> { article ->
            // 記事を編集するためのフィールドを持つページを表示 ...
            call.respondText("Edit an article with id ${article.parent.id}", status = HttpStatusCode.OK)
        }
        put<Articles.Id> { article ->
            // 記事を更新 ...
            call.respondText("An article with id ${article.id} updated", status = HttpStatusCode.OK)
        }
        delete<Articles.Id> { article ->
            // 記事を削除 ...
            call.respondText("An article with id ${article.id} deleted", status = HttpStatusCode.OK)
        }
    }
}

各エンドポイントでのリクエスト処理に関するヒントをいくつか紹介します。

  • get<Articles>

    このルートハンドラーは、sort クエリパラメータに従ってソートされたすべての記事を返すことが想定されています。 例えば、これはすべての記事を含むHTMLページやJSONオブジェクトになります。

  • get<Articles.New>

    このエンドポイントは、新しい記事を作成するためのフィールドを含むWebフォームを応答として返します。

  • post<Articles>

    post<Articles> エンドポイントは、Webフォームを使用して送信されたパラメータを受け取ることが想定されています。 Ktorでは、ContentNegotiation プラグインを使用してJSONデータをオブジェクトとして受け取ることもできます。

  • get<Articles.Id>

    このルートハンドラーは、指定された識別子を持つ記事を返すことが想定されています。 これは記事を表示するHTMLページや、記事データを含むJSONオブジェクトになります。

  • get<Articles.Id.Edit>

    このエンドポイントは、既存の記事を編集するためのフィールドを含むWebフォームを応答として返します。

  • put<Articles.Id>

    post<Articles> エンドポイントと同様に、put ハンドラーはWebフォームを使用して送信されたフォームパラメータを受け取ります。

  • delete<Articles.Id>

    このルートハンドラーは、指定された識別子を持つ記事を削除します。

完全な例はこちらで確認できます: resource-routing。

リソース定義はルーティングに使用するだけでなく、リンクの構築にも使用できます。 これは_リバースルーティング_(reverse routing)と呼ばれることもあります。 リソースからのリンクの構築は、HTML DSL で作成されたHTMLドキュメントにリンクを追加する必要がある場合や、リダイレクトレスポンスを生成する必要がある場合に役立ちます。

Resources プラグインは Application をオーバーロードされた href メソッドで拡張し、Resource からリンクを生成できるようにします。例えば、以下のコードスニペットは上記で定義した Edit リソース用のリンクを作成します。

kotlin
val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))

祖父母にあたる Articles リソースがデフォルト値 new を持つ sort クエリパラメータを定義しているため、link 変数には以下が含まれます。

/articles/123/edit?sort=new

ホストとプロトコルを指定するURLを生成するには、href メソッドに URLBuilder を渡すことができます。 この例に示すように、URLBuilder を使用して追加のクエリパラメータを指定することもできます。

kotlin
val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
href(Articles(sort = null), urlBuilder)
val link: String = urlBuilder.buildString()

その結果、link 変数には以下が含まれます。

https://ktor.io/articles?token=123

以下の例は、リソースから構築されたリンクをHTMLレスポンスに追加する方法を示しています。

kotlin
get {
    call.respondHtml {
        body {
            this@module.apply {
                p {
                    val link: String = href(Articles())
                    a(link) { +"Get all articles" }
                }
                p {
                    val link: String = href(Articles.New())
                    a(link) { +"Create a new article" }
                }
                p {
                    val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))
                    a(link) { +"Edit an exising article" }
                }
                p {
                    val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
                    href(Articles(sort = null), urlBuilder)
                    val link: String = urlBuilder.buildString()
                    i { a(link) { +link } }
                }
            }
        }
    }
}

完全な例はこちらで確認できます: resource-routing。