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。