Skip to content
Server Plugin

类型安全路由

必需依赖项: io.ktor:ktor-server-resources

代码示例: resource-routing

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持: ✅

Ktor 提供了 Resources 插件,允许您实现类型安全的路由。为此,您需要创建一个充当类型化路由的类,然后使用 @Resource 关键字对其进行注解。请注意,@Resource 注解具有由 kotlinx.serialization 库提供的 @Serializable 行为。

Ktor 客户端提供了向服务器发起类型化请求的能力。

添加依赖项 ​

添加 kotlinx.serialization ​

鉴于资源类应具有 @Serializable 行为,您需要按照设置部分中的说明添加 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。

除了将资源定义用于路由之外,它们还可以用于构建链接。 这有时被称为_反向路由_。 如果您需要将这些链接添加到使用 HTML DSL 创建的 HTML 文档中,或者需要生成重定向响应,那么从资源构建链接可能会很有帮助。

Resources 插件通过重载的 href 方法扩展了 Application,该方法允许您从 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。