型安全なルーティング
必要な依存関係: 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 アーティファクトを追加します。
implementation(ktorLibs.server.resources)implementation ktorLibs.server.resources<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-resources-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Resources のインストール
アプリケーションに Resources プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 次の例は、Resources をインストールする方法を示しています。
embeddedServer()関数の呼び出し内。Applicationクラスで明示的に定義されたmodule()拡張関数内。
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)
}import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
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(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 パスに応答します。
@Resource("/articles")
class Articles()
fun Application.module() {
install(Resources)
routing {
get<Articles> { articles ->
// すべての記事を取得 ...
call.respondText("List of articles: $articles")
}
}
}以下の例は、例: CRUD操作用のリソース で作成した Articles リソースに対してルートハンドラーを定義する方法を示しています。ルートハンドラー内では、パラメータとして Article にアクセスし、そのプロパティ値を取得できる点に注意してください。
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 リソース用のリンクを作成します。
val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))祖父母にあたる Articles リソースがデフォルト値 new を持つ sort クエリパラメータを定義しているため、link 変数には以下が含まれます。
/articles/123/edit?sort=newホストとプロトコルを指定するURLを生成するには、href メソッドに URLBuilder を渡すことができます。 この例に示すように、URLBuilder を使用して追加のクエリパラメータを指定することもできます。
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レスポンスに追加する方法を示しています。
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。
