Client Plugin

在 Ktor Client 中跟踪请求

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

代码示例： client-call-id

CallId 插件允许您使用唯一的调用 ID 端到端地跟踪客户端请求。这在微服务架构中特别有用，可以持续跟踪调用，无论请求经过多少个服务。

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

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

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

添加依赖项

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

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() 函数生成一个新的 ID。随后，通过 addToHeader() 函数将第一个非 null 的调用 ID 应用于请求标头。

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

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

通过这种方式，Ktor 服务器将检索请求中指定标头的 ID，并将其应用于调用的 callId 属性。

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