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 路径必须以尾随斜杠结尾。否则，根据 RFC 3986 URL 解析规则，请求路径将替换基础路径的最后一个片段 —— 例如，path("v1") 被视为文件，并在附加请求路径时被丢弃，而 path("v1/") 则作为目录前缀保留。

URL 参数

url 函数还允许您分别指定 URL 组件，例如：

• HTTP 方案；
• 主机名；
• 基础 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。