本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 搭配 Spring 和適用於 Java 的 X-Ray 開發套件的 AOP
**注意**
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)。
本主題說明如何使用 X-Ray SDK 和 Spring Framework 來檢測您的應用程式，而無需變更其核心邏輯。這表示現在有一種非侵入性的方式來檢測從遠端執行的應用程式 AWS。
**啟用 Spring 中的 AOP**
1. [設定 Spring](#xray-sdk-java-aop-spring-configuration)
1. [將追蹤篩選條件新增至您的應用程式](#xray-sdk-java-aop-filters-spring)
1. [對您的程式碼做註釋或實作界面](#xray-sdk-java-aop-annotate-or-implement)
1. [啟用應用程式中的 X-Ray](#xray-sdk-java-aop-activate-xray)
## 設定 Spring
您可以使用 Maven 或 Gradle 將 Spring 設定為使用 AOP 檢測您的應用程式。
如果您使用 Maven 來建置應用程式，請在 `pom.xml` 檔案中，新增以下相依性。
```
com.amazonaws
aws-xray-recorder-sdk-spring
2.11.0
```
若是 Gradle，請在 `build.gradle` 檔案中，新增以下依存性。
```
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0'
```
## 設定 Spring Boot
除了上一節所述的 Spring 相依性之外，如果您使用的是 Spring Boot，如果尚未在 classpath 上新增下列相依性。
Maven：
```
org.springframework.boot
spring-boot-starter-aop
2.5.2
```
Gradle：
```
compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2'
```
## 將追蹤篩選條件新增至您的應用程式
將 `Filter`新增至您的 `WebConfig` 類別。以字串形式將區段名稱傳遞給 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 建構函數。如需追蹤篩選條件和檢測傳入請求的詳細資訊，請參閱[使用適用於 Java 的 X-Ray 開發套件追蹤傳入請求](xray-sdk-java-filters.md)。
**Example src/main/java/myapp/WebConfig.java - Spring**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## 雅加達支援
Spring 6 使用 [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) 而非 Javax 做為其 Enterprise Edition。為了支援這個新的命名空間，X-Ray 建立了一組平行的類別，這些類別存在於自己的雅加達命名空間中。
對於篩選條件類別，請將 取代`javax`為 `jakarta`。設定區段命名策略時，請在命名策略類別名稱`jakarta`之前新增 ，如下列範例所示：
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import jakarta.servlet.Filter;
import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy;
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep"));
}
}
```
## 對您的程式碼做註釋或實作界面
您的類別必須以註釋標註`@XRayEnabled`，或實作`XRayTraced`界面。這會通知 AOP 系統，針對 X-Ray 檢測包裝受影響的類別函數。
## 在應用程式中啟用 X-Ray
若要在您的應用程式中啟用 X-Ray 追蹤，您的程式碼必須透過覆寫下列方法`BaseAbstractXRayInterceptor`來擴展抽象類別。
+ `generateMetadata`- 此函數允許自訂連接至目前函數追蹤的中繼資料。根據預設，執行函數的類別名稱會記錄到中繼資料中。如果您需要其他資訊，可以新增更多資料。
+ `xrayEnabledClasses`- 此函數為空，應保持為空。可做為 pointcut 的主機，指示攔截程式有哪些包裝方法。指定哪些類別要使用 `@XRayEnabled` 做註釋以便追蹤，藉此定義 pointcut。以下 pointcut 陳述式會通知攔截程式包裝所有含 `@XRayEnabled` 註釋的控制器 Bean。
```
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
```
如果您的專案使用 Spring Data JPA，請考慮從 延伸，`AbstractXRayInterceptor`而非 `BaseAbstractXRayInterceptor`。
## 範例
下列程式碼延伸抽象類別 `BaseAbstractXRayInterceptor`。
```
@Aspect
@Component
public class XRayInspector extends BaseAbstractXRayInterceptor {
@Override
protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception {
return super.generateMetadata(proceedingJoinPoint, subsegment);
}
@Override
@Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)")
public void xrayEnabledClasses() {}
}
```
下列程式碼為將由 X-Ray 檢測的類別。
```
@Service
@XRayEnabled
public class MyServiceImpl implements MyService {
private final MyEntityRepository myEntityRepository;
@Autowired
public MyServiceImpl(MyEntityRepository myEntityRepository) {
this.myEntityRepository = myEntityRepository;
}
@Transactional(readOnly = true)
public List getMyEntities(){
try(Stream entityStream = this.myEntityRepository.streamAll()){
return entityStream.sorted().collect(Collectors.toList());
}
}
}
```
如果您已正確設定應用程式，則應該會看到應用程式的完整呼叫堆疊 (從控制器到服務呼叫)，如以下主控台的螢幕擷取畫面所示。
![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/aop-spring-console.png)