本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在多執行緒應用程式之間傳遞區段內容
<a name="xray-sdk-java-multithreading"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

當您在應用程式中建立新執行緒時，`AWSXRayRecorder` 不會維持目前區段或子區段[實體](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html)的參考。若您在新執行緒中使用受檢測的用戶端，軟體開發套件會嘗試寫入不存在的區段，且會導致 [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)。

若要避免在開發期間拋出異常，您可以使用 [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html) 設定記錄器，告知其改而記錄錯誤。您可以使用 [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy)) 在程式碼中設定策略，或是使用[環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)或[系統屬性](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)來設定相等選項。

其中一種處理錯誤的方法是透過在啟動執行緒時呼叫 [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) 來使用新區段，以及在關閉時呼叫 [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--)。若您要檢測並非針對回應 HTTP 請求而執行的程式碼，這種方法可以正常運作，就像在應用程式啟動時執行的程式碼。

若您使用多個執行緒來處理傳入請求，您可以將目前區段或子區段傳遞至新執行緒，並將它提供給全域記錄器。這可確保在記錄該請求的其餘資訊時，於新執行緒中記錄的資訊會與相同區段建立關聯。區段在新執行緒中可用後，您可以使用 `segment.run(() -> { ... })`方法執行可存取該區段內容的任何可執行項目。

如需範例，請參閱[在工作者執行緒中使用受檢測用戶端](scorekeep-workerthreads.md)。

## 搭配非同步程式設計使用 X-Ray
<a name="using-asynchronous-programming"></a>

 適用於 Java 的 X-Ray 開發套件可用於具有 [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) 的非同步 Java 程式。SegmentContextExecutor 實作執行器界面，這表示它可以傳遞至 [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) 的所有非同步操作。這可確保任何非同步操作都會在其內容中使用正確的區段執行。

**Example App.java 範例：將 SegmentContextExecutor 傳遞至 CompletableFuture**  

```
DynamoDbAsyncClient client = DynamoDbAsyncClient.create();

AWSXRay.beginSegment();

// ...

client.getItem(request).thenComposeAsync(response -> {
    // If we did not provide the segment context executor, this request would not be traced correctly.
    return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());
```