迁移至@aws-sdk/client-xray时，captureHTTPsGlobal等方法的替代方案

我目前代码使用aws-xray-sdk，计划迁移到AWS SDK for JavaScript v3的@aws-sdk/client-xray。现有如下旧版代码，想知道新版XRay客户端下的替代实现方式，另外我还用到了S3、SES和SQS服务：

旧版代码：

import * as https from 'https';
import AWSXRay from 'aws-xray-sdk';
import AWS from 'aws-sdk';

AWSXRay.captureHTTPsGlobal(https, false);
AWSXRay.captureAWS(AWS);

核心差异说明 #

AWS SDK v3采用模块化设计，旧版的全局捕获（captureAWS、captureHTTPsGlobal）不再适用，需要为每个服务客户端单独配置XRay追踪中间件。

替代实现步骤 #

1. 安装依赖 #

需要安装v3版的服务客户端包和XRay中间件：

npm install @aws-sdk/client-xray @aws-sdk/middleware-xray @aws-sdk/client-s3 @aws-sdk/client-ses @aws-sdk/client-sqs

注：仍需保留aws-xray-sdk基础包用于HTTP请求捕获和核心XRay功能。

2. 代码实现 #

import * as https from 'https';
import { XRayClient } from '@aws-sdk/client-xray';
import { S3Client } from '@aws-sdk/client-s3';
import { SESClient } from '@aws-sdk/client-ses';
import { SQSClient } from '@aws-sdk/client-sqs';
import { addXRayTraceIdMiddleware } from '@aws-sdk/middleware-xray';
import AWSXRay from 'aws-xray-sdk';

// 替代旧版captureHTTPsGlobal：捕获全局HTTPS请求
AWSXRay.captureHTTPs(https, false);

// 初始化XRay客户端（用于中间件追踪逻辑）
const xrayClient = new XRayClient({});

// 封装创建带XRay追踪的客户端的工具函数
const createTracedClient = (ClientClass) => {
  const client = new ClientClass({});
  // 添加XRay中间件，注入Trace ID并上报追踪数据
  client.middlewareStack.add(addXRayTraceIdMiddleware({ client: xrayClient }), {
    step: 'build',
    name: 'xrayTraceIdMiddleware',
  });
  return client;
};

// 创建带XRay追踪的各服务客户端
const s3Client = createTracedClient(S3Client);
const sesClient = createTracedClient(SESClient);
const sqsClient = createTracedClient(SQSClient);

3. 关键注意事项 #

• v3不支持全局捕获所有AWS客户端，必须为每个服务客户端单独添加XRay中间件
• @aws-sdk/middleware-xray是v3实现XRay追踪的核心，负责处理Trace ID注入和数据上报
• HTTP请求捕获仍可使用aws-xray-sdk的captureHTTPs方法，与v3兼容
• 如果不需要主动创建自定义追踪段，XRayClient的配置可以保持默认

内容的提问来源于stack exchange，提问作者Mehdi Javan