aws-sdk-java-v2 中 User-Agent 附加元数据（md/rb、md/rt）的格式规范与源码实现解析

aws-sdk-java-v2 中 User-Agent 附加元数据（md/rb、md/rt）的格式规范与源码实现解析

【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2

AWS SDK for Java V2 会在每个服务请求的User-Agent头中携带一批"附加元数据"，用于记录请求体/响应体的实现方式、I/O 组件、身份来源等诊断信息。本文基于仓库文档 docs/user-agent.md，完整覆盖文档中定义的md/rb、md/rt元数据取值表，并结合core/sdk-core下的实际源码（AdditionalMetadata、ApplyUserAgentStage、SdkUserAgentBuilder）与集成测试，讲清楚这些元数据是如何被构造、挂载到请求头、以及如何在测试中验证的，帮助你在排查流式传输、大对象上传下载问题时快速定位 SDK 内部使用的具体实现。

一、附加元数据的位置与通用格式

SDK 发出的请求中，User-Agent头由多个字段组成。除 SDK 版本、操作系统、语言等基础字段外，SDK 还可能附带"附加元数据"（additional metadata）。文档明确规定其统一格式为：

md/[name]#[value]

即：字段名固定为md，字段名与具体内容之间用/分隔，内容本身是name#value形式的键值对，多个元数据之间以空格分隔。这个格式在源码中有严格对应——AdditionalMetadata 是承载单个附加元数据的类，其toString()直接调用 UserAgentConstant 的field(METADATA, uaPair(name, value))拼出md/{name}#{value}字符串；其中METADATA常量值就是"md"，分隔符常量SLASH、HASH分别对应/和#。

该值通过 Builder 模式构造（name 与 value 均不允许为 null），并可作为普通 Java 对象参与等值比较，这在 SDK 内部把"元数据列表"作为执行上下文属性传递、以及在测试中断言时都有直接用处（见第四节的CapturingInterceptor断言方式）。

二、文档定义的元数据项：rb 与 rt 取值表

2.1rb：请求体实现方式

rb（request body）记录本次请求所采用的请求体实现。同步客户端对应ContentStreamProvider，异步客户端对应AsyncRequestBody。文档定义的完整取值如下：

对应到常用 API 即：RequestBody.fromString(...)→md/rb#c、RequestBody.fromFile(...)→md/rb#f、RequestBody.fromInputStream(...)→md/rb#s，异步侧的AsyncRequestBody.fromString/fromFile/fromInputStream/fromPublisher同理。

2.2rt：响应转换器实现方式

rt（response transformer）记录本次响应所采用的转换器实现。同步客户端对应ResponseTransformer，异步客户端对应AsyncResponseTransformer。文档定义的取值：

注意rt没有c（String）取值，因为 SDK 不提供"把响应体读成字符串"的标准转换器路径；而rb没有u之外的p以外的额外取值——两张表的差异本身就反映了同步/异步两侧 API 面的不对称（同步侧请求体是RequestBody，异步侧才是AsyncRequestBody，转换器同理）。

三、元数据如何被挂到 User-Agent 头：ApplyUserAgentStage

附加元数据最终进入请求头的位置在 HTTP 执行管线中的 ApplyUserAgentStage。其finalizeUserAgent方法给出的拼装顺序（也是源码 Javadoc 明确说明的顺序）为：

1. 用户通过SdkAdvancedClientOption.USER_AGENT_PREFIX配置的前缀（可选）；
2. 客户端级 SDK User-Agent 字符串（SdkClientOption.CLIENT_USER_AGENT，按统一规范生成）；
3. 请求级附加元数据——从执行上下文的SdkInternalExecutionAttribute.USER_AGENT_METADATA属性中取出List<AdditionalMetadata>，逐项以空格追加；
4. 业务指标，以m/...字段表达（BUSINESS_METADATA常量为"m"）；
5. 请求上附加的 API 名称列表；
6. 用户通过USER_AGENT_SUFFIX配置的后缀（可选）。

关键实现在 ApplyUserAgentStage.java 第 138-142 行：

//add useragent metadata from execution context List<AdditionalMetadata> userAgentMetadata = context.executionAttributes().getAttribute(SdkInternalExecutionAttribute.USER_AGENT_METADATA); if (userAgentMetadata != null) { userAgentMetadata.forEach(s -> javaUserAgent.append(SPACE).append(s)); }

也就是说，md/rb#...、md/rt#...并不是全局静态的，而是请求级元数据：SDK 在构造具体操作（尤其是带流式输入/输出的操作）的协议处理逻辑时，把对应AdditionalMetadata写入ExecutionAttributes，由该 Stage 在发送前统一渲染进User-Agent头。属性定义见 SdkInternalExecutionAttribute，类型正是ExecutionAttribute<List<AdditionalMetadata>>。文档中提到的rb/rt正是通过这条请求级通道进入请求头的元数据之一。

四、客户端级 User-Agent 的构成（前缀字段从哪里来）

理解附加元数据之前，值得先了解它"前面"的字符串是如何生成的，这部分由 SdkUserAgentBuilder 完成。buildClientUserAgentString依次追加：

• aws-sdk-java/{版本号}（JAVA_SDK_METADATA）；
• SDK 组件元数据md/io#...（I/O 组件，如 netty、apache）与md/http#...（HTTP 客户端类型）；
• 内部工具标记md/internal（仅内部构建存在）；
• ua/2.1（User-Agent 规范版本，UserAgentConstant 第 42 行）；
• api/...、os/...、lang/...，以及 JVM 相关的md/...项；
• exec-env/...（运行环境，值为空或 "unknown" 时省略）；
• app/{appId}（可选）。

其中app字段的解析逻辑在 AppIdResolver：优先读取系统设置aws.sdk.ua.app.id，其次读取配置文件（~/.aws/config）中对应 profile 的sdk_ua_app_id属性。此外 SdkUserAgentBuilder 第 133-139 行 会对超过 50 字符的 appId 记录警告日志，提示可能因 User-Agent 过长而截断。

User-Agent头的最终取值还受 UserAgentConstant 第 57-58 行 定义的字符黑名单约束（按 RFC 7230 token 规则），sanitizeInput会把空格、括号、逗号等非法字符替换为下划线——所以附加元数据的 name/value 若来自用户输入，也会经过同一套清洗。

五、测试证据：rb / rt 各取值的端到端验证

仓库内置了专门验证上述元数据的集成测试 StreamingBodyAndTransformerImplTrackingTest，它对同步/异步两种客户端分别构造流式输入/输出操作，并通过拦截器在beforeTransmission钩子里捕获User-Agent头进行断言（测试故意抛出异常中断请求，只验证头部已写入）：

例如 测试第 48-52 行：

@Test public void streamingInputOperation_syncClient_stringBody_recordsMetadata() { callStreamingInputOperation(syncClient(), RequestBody.fromString("body")); assertThat(interceptor.userAgent()).contains("md/rb#b"); }

该测试证实了文档表格与源码行为的一致性：rb/rt元数据确实会随请求实际发出，且取值与所用的RequestBody/AsyncRequestBody/ResponseTransformer/AsyncResponseTransformer工厂方法一一对应。除核心测试外，TransferManagerUploadUserAgentBusinessMetricWireMockTest 也表明 S3 TransferManager 等高层组件会复用同一套 User-Agent 元数据机制上报自身行为。

六、实践要点与适用前提

• 诊断价值：当 AWS 服务侧支持团队或你自己的网关侧日志里出现md/rb#u（unknown）时，意味着 SDK 无法识别请求体实现来源；md/rt#p表明响应以 Reactor/Rx 风格的SdkPublisher消费——这是排查"流式操作内存/背压异常"时最先应看的线索。
• 适用前提：以上行为适用于本仓库当前版本的 SDK（ua/2.1规范）；USER_AGENT_PREFIX/USER_AGENT_SUFFIX属高级配置（SdkAdvancedClientOption），源码注释明确建议谨慎使用，因为它们不参与统一规范、且可能使 User-Agent 过长被截断。
• 扩展方式：如需自定义附加元数据，SDK 已提供AdditionalMetadata.builder().name(...).value(...).build()的受保护 API 入口；而rb/rt两项由 SDK 根据具体操作自动注入，无需手工设置。

综上，docs/user-agent.md所定义的md/[name]#[value]附加元数据格式，在实现上由 AdditionalMetadata 建模、经 SdkInternalExecutionAttribute.USER_AGENT_METADATA 在请求级传递、最终由 ApplyUserAgentStage 渲染进User-Agent头，并由 StreamingBodyAndTransformerImplTrackingTest 对rb/rt的全部关键取值做了端到端断言。

【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2