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 版本目錄 (version catalog) 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.resources
上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 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。