Client Plugin

類型安全的請求

必要的依賴項：io.ktor:ktor-client-resources

程式碼範例： client-type-safe-requests

Ktor 提供 Resources 外掛程式，讓您能實作類型安全的請求。為此，您需要建立一個類別來描述伺服器上可用的資源，然後使用 @Resource 關鍵字註解此類別。請注意，@Resource 註解具有 kotlinx.serialization 函式庫提供的 @Serializable 行為。

Ktor 伺服器提供了實作類型安全路由的能力。

新增依賴項

新增 kotlinx.serialization

考量到資源類別應具備 @Serializable 行為，您需要按照 Setup 章節所述新增 Kotlin 序列化外掛程式。

新增 Resources 依賴項

若要使用 Resources，您需要在建置腳本中包含 ktor-client-resources 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

您可以從

新增用戶端依賴項

學習如何將用戶端依賴項新增至現有專案。

了解更多關於 Ktor 用戶端所需的構件。

安裝 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。

您可以在此處找到完整的範例：client-type-safe-requests。