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 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 CallId

要將 CallId 外掛程式安裝到應用程式，請將其傳遞給指定

模組

模組允許您透過將路由分組來建構應用程式。

中的 install 函式。 下方的程式碼片段展示了如何安裝 CallId ...

• ... 在 embeddedServer 函式呼叫內部。
• ... 在明確定義的 module 內部，它是 Application 類別的擴充函式。

embeddedServermodule

配置 CallId

由 CallIdConfig 類別提供的 CallId 外掛程式配置，允許您產生呼叫 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