Client Plugin

預設請求

程式碼範例： client-default-request

DefaultRequest 外掛程式可讓您為所有請求配置預設參數：指定基礎 URL、添加標頭、配置查詢參數等。

添加相依性

DefaultRequest 僅需要 ktor-client-core 構件，不需要任何特定的相依性。

安裝 DefaultRequest

若要安裝 DefaultRequest，請將其傳遞給用戶端配置區塊內的 install 函式：

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(DefaultRequest)
}

或呼叫 defaultRequest() 函式並配置所需的請求參數：

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    defaultRequest {
        // this: DefaultRequestBuilder
    }
}

替換現有配置

如果 DefaultRequest 外掛程式已經安裝，您可以使用以下任一方式替換其現有配置：

• 使用 defaultRequest() 函式的 replace 參數：

val client = HttpClient(CIO) {
    defaultRequest(replace = true) {
        // this: DefaultRequestBuilder
    }
}

• 使用泛型 installOrReplace() 函式：

val client = HttpClient(CIO) {
    installOrReplace(DefaultRequest) {
        // this: DefaultRequestBuilder
    }
}

配置 DefaultRequest

基礎 URL

DefaultRequest 可讓您配置 URL 的基礎部分，該部分會與請求 URL 合併。 例如，下方的 url 函式為所有請求指定了基礎 URL：

defaultRequest {
    url("https://ktor.io/docs/")
}

如果您使用具有上述配置的用戶端發出以下請求，...

val response: HttpResponse = client.get("welcome.html")

... 產生的 URL 將如下所示：https://ktor.io/docs/welcome.html。 若要了解基礎 URL 與請求 URL 如何合併，請參閱 DefaultRequest。

基礎 URL 路徑必須以結尾斜線（trailing slash）結束。否則，根據 RFC 3986 的 URL 解析規則，請求路徑會替換基礎路徑的最後一個區段 —— 例如，path("v1") 會被視為檔案，並在附加請求路徑時被捨棄，而 path("v1/") 則會保留為目錄前綴。

URL 參數

url 函式還允許您個別指定 URL 元件，例如：

• HTTP 配置方案（scheme）；
• 主機名稱；
• 基礎 URL 路徑；
• 查詢參數。

url {
    protocol = URLProtocol.HTTPS
    host = "ktor.io"
    path("docs/")
    parameters.append("token", "abc123")
}

標頭

若要向每個請求添加特定的標頭，請使用 header 函式：

defaultRequest {
    header("X-Custom-Header", "Hello")
}

若要避免標頭重複，您可以使用 appendIfNameAbsent、appendIfNameAndValueAbsent 和 contains 函式：

defaultRequest {
    headers.appendIfNameAbsent("X-Custom-Header", "Hello")
}

Unix 網域通訊端

Unix 網域通訊端僅在 CIO 引擎中支援。

您可以使用 Unix 網域通訊端建置個別請求，但也可以使用通訊端參數配置預設請求。

若要執行此操作，請將帶有通訊端路徑的 unixSocket 呼叫傳遞給 defaultRequest 函式，例如：

val client = HttpClient(CIO)

// 向 Unix 網域通訊端發送單個請求
val response: HttpResponse = client.get("/") {
    unixSocket("/tmp/test-unix-socket-ktor.sock")
}

// 為該用戶端的所有請求設定通訊端
val clientDefault = HttpClient(CIO) {
    defaultRequest {
        unixSocket("/tmp/test-unix-socket-ktor.sock")
    }    
}

val response: HttpResponse = clientDefault.get("/")

範例

下方的範例使用了以下 DefaultRequest 配置：

• url 函式定義了 HTTP 配置方案、主機、基礎 URL 路徑和一個查詢參數。
• header 函式為所有請求添加了一個自訂標頭。

val client = HttpClient(CIO) {
    defaultRequest {
        url {
            protocol = URLProtocol.HTTPS
            host = "ktor.io"
            path("docs/")
            parameters.append("token", "abc123")
        }
        header("X-Custom-Header", "Hello")
    }
}

下方由該用戶端發出的請求僅指定了路徑的後半部分，並會自動套用為 DefaultRequest 配置的參數：

val response: HttpResponse = client.get("welcome.html")
println(response.status)

您可以在此處找到完整的範例：client-default-request。