类型安全请求
所需依赖项:io.ktor:ktor-client-resources
Ktor 提供了 Resources 插件用于发出类型安全的客户端请求。 为此,你需要定义代表服务器端点的类,并使用 @Resource 关键字对其进行注解。
资源类使用 kotlinx.serialization 将其属性转换为路径和查询参数。
在服务端,Ktor 提供了类型安全路由。
添加依赖项
添加 kotlinx.serialization
Resources 插件依赖于 kotlinx.serialization。按照 kotlinx.serialization 设置指南中的说明启用 Kotlin 序列化插件。
添加 Resources 依赖项
要使用 Resources,请将 ktor-client-resources 工件添加到构建脚本中:
安装 Resources
要安装 Resources 插件,请在客户端配置块中将其传递给 install 函数:
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 路径的资源。
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() {
@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 路径发送请求:
@Resource("/articles")
class Articles()
fun main() {
runBlocking {
val client = HttpClient(CIO) {
install(Resources)
// ...
}
val getAllArticles = client.get(Articles())
}
}以下示例向在示例:用于 CRUD 操作的资源中创建的 Articles 资源发送类型化请求。
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 请求属性访问用于类型安全请求的资源实例:
onRequest { call, _ ->
val resource = call.attributes.getOrNull(RESOURCE)
}完整示例请参阅 client-type-safe-requests。
