型別安全請求
必要相依性: 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 構件新增至您的組建指令碼中:
implementation(ktorLibs.client.resources)implementation ktorLibs.client.resources<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-resources-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝 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。
