自訂用戶端外掛程式
程式碼範例: client-custom-plugin
從 v2.2.0 開始,Ktor 提供了一個用於建立自訂用戶端外掛程式的新 API。一般而言,此 API 不需要理解 Ktor 內部概念(如管線、階段等)。 相反地,您可以透過一組處理常式(例如 onRequest、onResponse 等)存取處理請求與回應的不同階段。
建立並安裝您的第一個外掛程式
在本節中,我們將示範如何建立並安裝您的第一個外掛程式,該外掛程式會為每個請求新增自訂標頭:
若要建立外掛程式,請呼叫 createClientPlugin 函式並傳入外掛程式名稱作為引數:
kotlinpackage com.example.plugins import io.ktor.client.plugins.api.* val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") { // 配置外掛程式 ... }此函式會傳回將用於安裝外掛程式的
ClientPlugin執行個體。若要為每個請求附加自訂標頭,您可以使用
onRequest處理常式,該常式提供對請求參數的存取:kotlinpackage com.example.plugins import io.ktor.client.plugins.api.* val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") { onRequest { request, _ -> request.headers.append("X-Custom-Header", "Default value") } }若要安裝外掛程式,請在用戶端的配置區塊內將建立的
ClientPlugin執行個體傳遞給install函式:kotlinimport com.example.plugins.* val client = HttpClient(CIO) { install(CustomHeaderPlugin) }
您可以在此處找到完整範例:CustomHeader.kt。 在接下來的章節中,我們將探討如何提供外掛程式配置以及如何處理請求和回應。
提供外掛程式配置
上一節示範了如何建立一個為每個回應附加預定義自訂標頭的外掛程式。讓我們讓這個外掛程式更有用,並提供一個配置來傳入任意的自訂標頭名稱與值:
首先,您需要定義一個配置類別:
kotlinclass CustomHeaderPluginConfig { var headerName: String = "X-Custom-Header" var headerValue: String = "Default value" }若要在外掛程式中使用此配置,請將配置類別的參照傳遞給
createClientPlugin:kotlinimport io.ktor.client.plugins.api.* val CustomHeaderConfigurablePlugin = createClientPlugin("CustomHeaderConfigurablePlugin", ::CustomHeaderPluginConfig) { val headerName = pluginConfig.headerName val headerValue = pluginConfig.headerValue onRequest { request, _ -> request.headers.append(headerName, headerValue) } }鑑於外掛程式配置欄位是可變的,建議將它們儲存在區域變數中。
最後,您可以依照以下方式安裝並配置該外掛程式:
kotlinval client = HttpClient(CIO) { install(CustomHeaderConfigurablePlugin) { headerName = "X-Custom-Header" headerValue = "Hello, world!" } }
您可以在此處找到完整範例:CustomHeaderConfigurable.kt。
處理請求與回應
自訂外掛程式使用一組專用的處理常式提供對處理請求與回應不同階段的存取,例如:
onRequest與onResponse分別允許您處理請求與回應。transformRequestBody與transformResponseBody可用於對請求和回應主體套用必要的轉換。
此外還有 on(...) 處理常式,允許您呼叫特定掛鉤,這在處理呼叫的其他階段時可能非常有用。 下表依執行順序列出所有處理常式:
| 處理常式 | 說明 |
onRequest | 此處理常式會針對每個 HTTP 請求了解如何發送請求並指定各種請求參數:請求 URL、HTTP 方法、標頭以及請求主體。執行,並允許您修改它。 範例:自訂標頭 |
transformRequestBody | 允許您轉換請求主體。 在此處理常式中,您需要將主體序列化為 OutgoingContent (例如 範例:資料轉換 |
onResponse | 此處理常式會針對每個傳入的 HTTP 回應了解如何發送請求並指定各種請求參數:請求 URL、HTTP 方法、標頭以及請求主體。執行,並允許您以各種方式檢查它:記錄回應、儲存 Cookie 等。 |
transformResponseBody | 允許您轉換回應主體。 此處理常式會在每次呼叫 範例:資料轉換 |
onClose | 允許您清理此外掛程式配置的資源。 當用戶端被關閉時會呼叫此處理常式。 |
| 處理常式 | 說明 |
on(SetupRequest) | SetupRequest 掛鉤在請求處理中最先執行。 |
onRequest | 此處理常式會針對每個 HTTP 請求了解如何發送請求並指定各種請求參數:請求 URL、HTTP 方法、標頭以及請求主體。執行,並允許您修改它。 範例:自訂標頭 |
transformRequestBody | 允許您轉換請求主體。 在此處理常式中,您需要將主體序列化為 OutgoingContent (例如 範例:資料轉換 |
on(Send) |
範例:身分驗證 |
on(SendingRequest) |
console |
onResponse | 此處理常式會針對每個傳入的 HTTP 回應了解如何發送請求並指定各種請求參數:請求 URL、HTTP 方法、標頭以及請求主體。執行,並允許您以各種方式檢查它:記錄回應、儲存 Cookie 等。 |
transformResponseBody | 允許您轉換回應主體。 此處理常式會在每次呼叫 範例:資料轉換 |
onClose | 允許您清理此外掛程式配置的資源。 當用戶端被關閉時會呼叫此處理常式。 |
共用呼叫狀態
自訂外掛程式允許您共用與呼叫相關的任何值, 以便您可以在處理此呼叫的任何處理常式內存取該值。 此值作為具有唯一索引鍵的屬性儲存在 call.attributes 集合中。 以下範例示範如何使用屬性計算傳送請求與接收回應之間的時間:
import io.ktor.client.plugins.api.*
import io.ktor.util.*
val ResponseTimePlugin = createClientPlugin("ResponseTimePlugin") {
val onCallTimeKey = AttributeKey<Long>("onCallTimeKey")
on(SendingRequest) { request, content ->
val onCallTime = System.currentTimeMillis()
request.attributes.put(onCallTimeKey, onCallTime)
}
onResponse { response ->
val onCallTime = response.call.attributes[onCallTimeKey]
val onCallReceiveTime = System.currentTimeMillis()
println("Read response delay (ms): ${onCallReceiveTime - onCallTime}")
}
}您可以在此處找到完整範例:ResponseTime.kt。
存取用戶端配置
您可以使用傳回 HttpClient 執行個體的 client 屬性來存取用戶端配置。 以下範例示範如何取得用戶端所使用的代理伺服器位址:
import io.ktor.client.plugins.api.*
val SimplePlugin = createClientPlugin("SimplePlugin") {
val proxyAddress = client.engineConfig.proxy?.address()
println("Proxy address: $proxyAddress")
}範例
以下程式碼範例展示了數個自訂外掛程式的範例。 您可以在此處找到最終專案:client-custom-plugin。
自訂標頭
展示如何建立一個為每個請求新增自訂標頭的外掛程式:
package com.example.plugins
import io.ktor.client.plugins.api.*
val CustomHeaderConfigurablePlugin = createClientPlugin("CustomHeaderConfigurablePlugin", ::CustomHeaderPluginConfig) {
val headerName = pluginConfig.headerName
val headerValue = pluginConfig.headerValue
onRequest { request, _ ->
request.headers.append(headerName, headerValue)
}
}
class CustomHeaderPluginConfig {
var headerName: String = "X-Custom-Header"
var headerValue: String = "Default value"
}記錄標頭
示範如何建立一個記錄請求與回應標頭的外掛程式:
package com.example.plugins
import io.ktor.client.plugins.api.*
val LoggingHeadersPlugin = createClientPlugin("LoggingHeadersPlugin") {
on(SendingRequest) { request, content ->
println("Request headers:")
request.headers.entries().forEach { entry ->
printHeader(entry)
}
}
onResponse { response ->
println("Response headers:")
response.headers.entries().forEach { entry ->
printHeader(entry)
}
}
}
private fun printHeader(entry: Map.Entry<String, List<String>>) {
var headerString = entry.key + ": "
entry.value.forEach { headerValue ->
headerString += "${headerValue};"
}
println("-> $headerString")
}回應時間
展示如何建立一個測量傳送請求到接收回應之間時間的外掛程式:
package com.example.plugins
import io.ktor.client.plugins.api.*
import io.ktor.util.*
val ResponseTimePlugin = createClientPlugin("ResponseTimePlugin") {
val onCallTimeKey = AttributeKey<Long>("onCallTimeKey")
on(SendingRequest) { request, content ->
val onCallTime = System.currentTimeMillis()
request.attributes.put(onCallTimeKey, onCallTime)
}
onResponse { response ->
val onCallTime = response.call.attributes[onCallTimeKey]
val onCallReceiveTime = System.currentTimeMillis()
println("Read response delay (ms): ${onCallReceiveTime - onCallTime}")
}
}資料轉換
展示如何使用 transformRequestBody 與 transformResponseBody 掛鉤轉換請求和回應主體:
package com.example.plugins
import com.example.model.*
import io.ktor.client.plugins.api.*
import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.utils.io.*
val DataTransformationPlugin = createClientPlugin("DataTransformationPlugin") {
transformRequestBody { request, content, bodyType ->
if (bodyType?.type == User::class) {
val user = content as User
TextContent(text="${user.name};${user.age}", contentType = ContentType.Text.Plain)
} else {
null
}
}
transformResponseBody { response, content, requestedType ->
if (requestedType.type == User::class) {
val receivedContent = content.readLine()!!.split(";")
User(receivedContent[0], receivedContent[1].toInt())
} else {
content
}
}
}package com.example
import com.example.model.*
import com.example.plugins.*
import com.example.server.*
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.*
fun main() {
startServer()
runBlocking {
val client = HttpClient(CIO) {
install(DataTransformationPlugin)
}
val bodyAsText = client.post("http://0.0.0.0:8080/post-data") {
setBody(User("John", 42))
}.bodyAsText()
val user = client.get("http://0.0.0.0:8080/get-data").body<User>()
println("Userinfo: $bodyAsText")
println("Username: ${user.name}, age: ${user.age}")
}
}package com.example.model
data class User(val name: String, val age: Int)您可以在此處找到完整範例:client-custom-plugin-data-transformation。
身分驗證
一個展示如何使用 on(Send) 掛鉤的 Ktor 專案範例:當從伺服器收到未授權的回應時,在 Authorization 標頭中加入 Bearer 權杖:
package com.example.plugins
import io.ktor.client.plugins.api.*
import io.ktor.http.*
val AuthPlugin = createClientPlugin("AuthPlugin", ::AuthPluginConfig) {
val token = pluginConfig.token
on(Send) { request ->
val originalCall = proceed(request)
originalCall.response.run { // this: HttpResponse
if(status == HttpStatusCode.Unauthorized && headers["WWW-Authenticate"]!!.contains("Bearer")) {
request.headers.append("Authorization", "Bearer $token")
proceed(request)
} else {
originalCall
}
}
}
}
class AuthPluginConfig {
var token: String = ""
}package com.example
import com.example.plugins.*
import com.example.server.*
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.*
fun main() {
startServer()
runBlocking {
val client = HttpClient(CIO) {
install(AuthPlugin) {
token = "abc123"
}
}
val response = client.get("http://0.0.0.0:8080/")
println(response.bodyAsText())
}
}您可以在此處找到完整範例:client-custom-plugin-auth。
