Client Plugin

在 Ktor 客户端中追踪请求

所需依赖项: io.ktor:ktor-client-call-id

代码示例: client-call-id

CallId 插件允许你通过使用唯一的调用 ID 来端到端地追踪客户端请求。它在微服务架构中尤其有用，可以帮助追踪调用，无论请求经过多少服务。

调用作用域在其协程上下文中可能已经包含一个调用 ID。默认情况下，该插件使用当前上下文检索调用 ID，并使用 HttpHeaders.XRequestId 请求头将其添加到特定调用的上下文中。

此外，如果某个作用域没有调用 ID，你可以配置该插件以生成并应用一个新的调用 ID。

在服务端，Ktor 提供了 CallId 插件来追踪客户端请求。

添加依赖项

要使用 CallId，你需要在构建脚本中包含 ktor-client-call-id artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

安装 CallId

要将 CallId 插件安装到应用程序中， 请将其传递给指定

模块

模块允许你通过对路由进行分组来组织应用程序。

中的 install 函数。 下面的代码片段展示了如何安装 CallId ...

• ... 在 embeddedServer 函数调用内部。
• ... 在显式定义的 module 内部，后者是 Application 类的扩展函数。

embeddedServermodule

配置 CallId

CallId 插件配置由 CallIdConfig 类提供， 允许你生成调用 ID 并将其添加到调用上下文。

生成调用 ID

通过以下方式之一为特定请求生成调用 ID：

• useCoroutineContext 属性（默认启用）会添加一个生成器，该生成器使用当前的 CoroutineContext 来检索调用 ID。要禁用此功能，请将 useCoroutineContext 设置为 false：

install(CallId) {
    useCoroutineContext = false
}

在 Ktor 服务端，使用 CallId 插件将调用 ID 添加到 CoroutineContext。

• generate() 函数允许你为出站请求生成一个调用 ID。如果未能生成调用 ID，它将返回 null。

install(CallId) {
    generate { "call-id-client-2" }
}

你可以使用多种方法来生成调用 ID。这样，第一个非 null 值将被应用。

添加调用 ID

检索到调用 ID 后，你可以使用以下可用选项将其添加到请求中：

• intercept() 函数允许你使用 CallIdInterceptor 将调用 ID 添加到请求中。

install(ClientCallId) {
    intercept { request, callId ->
        request.header(HttpHeaders.XRequestId, callId)
    }
}

• addToHeader() 函数将调用 ID 添加到指定的请求头。它接受一个请求头作为参数，默认值为 HttpHeaders.XRequestId。

install(CallId) {
    addToHeader(HttpHeaders.XRequestId)
}

示例

在以下示例中，Ktor 客户端的 CallId 插件被配置为生成新的调用 ID 并将其添加到请求头：

val client = HttpClient(CIO) {
    install(CallId) {
        generate { "call-id-client" }
        addToHeader(HttpHeaders.XRequestId)
    }
}

该插件使用协程上下文获取调用 ID，并利用 generate() 函数生成一个新的。然后，第一个非 null 调用 ID 将通过 addToHeader() 函数应用到请求头。

在 Ktor 服务端，调用 ID 可以使用 服务器 CallId 插件中的 retrieve 函数从请求头中检索。

install(CallId) {
    retrieveFromHeader(HttpHeaders.XRequestId)
}

这样，Ktor 服务端会检索请求的指定请求头中的 ID，并将其应用到调用的 callId 属性。

有关完整示例，请参见 client-call-id。