默认请求
代码示例: 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 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 域套接字构建单个请求, 但也可以使用套接字形参配置默认请求。
为此,请向 defaultRequest 函数传递包含套接字路径的 unixSocket 调用, 例如:
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 scheme、主机、基础 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。
