AWS SDK for Java v2 响应式流Reactive Streams实现指南规范符合性、常用模式与 TCK 测试要求【免费下载链接】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 官方仓库中的 Reactive Streams 实现指南对应 docs/guidelines/reactive-streams-guidelines.md的完整解读与源码级展开。AWS SDK for Java v2 的异步 API如 S3 流式上传/下载、异步分页响应、事件流等全部构建在 Reactive Streams 规范之上以实现非阻塞、可背压backpressure的数据处理。阅读本文后你将掌握该 SDK 对响应式流实现的强制合规要求、官方推荐的既有工具类SimplePublisher、ByteBufferStoringSubscriber、SdkPublisher的用法与内部机制、通用实现模式以及 TCK 验证测试的编写与覆盖要求能够直接指导你在该仓库内新增或修改 Publisher / Subscriber 实现。一、背景为什么 AWS SDK for Java v2 依赖 Reactive StreamsAWS SDK for Java v2 在异步场景下AsyncClient系列使用 Reactive Streams 作为异步、非阻塞数据处理的统一抽象核心诉求是背压支持——即下游消费者可以按自身处理能力向上游请求数据避免内存被无限堆积的数据撑爆。从源码结构看响应式流能力分布在两个核心包中utils/src/main/java/software/amazon/awssdk/utils/async/存放SimplePublisher、StoringSubscriber、ByteBufferStoringSubscriber、BufferingSubscriber、FilteringSubscriber、LimitingSubscriber等一批通用工具实现core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.javaSDK 面向异步 API 公开的发布者接口。该指南明确要求所有实现必须完全符合 Reactive Streams JVM 规范且必须通过 Reactive Streams Technology Compatibility KitTCK测试。任何对响应式流实现的代码改动都必须附带 TCK 验证测试。这两条是硬性约束MUST也是本指南的立论基础。二、实现指南Implementation Guidelines2.1 合规要求Compliance Requirements指南提出的三项强制要求如下完全符合 Reactive Streams 规范MUST所有 Publisher / Subscriber / Subscription 实现必须遵循规范中的各项规则包括信号时序onSubscribe→onNext* →onComplete/onError、背压语义request(n)只能增加需求、取消语义cancel()后不得再发送信号等。必须通过 Reactive Streams TCK 测试MUSTTCK 是规范官方提供的合规性测试套件对 Publisher、Subscriber、Subscription 分别提供断言测试用于验证实现是否满足规范的每条规则。响应式流实现的任何代码变更必须包含 TCK 验证测试MUST这保证了改动不会破坏规范合规性防止回归。2.2 最佳实践不要从零实现 Publisher / SubscriberSHOULD NOT指南给出明确建议开发者不应从零编写新的 Publisher 或 Subscriber 接口实现而应优先使用仓库内已有的、经过验证的工具类。官方推荐三类工具工具类定位源码位置SimplePublisherPublisher 接口的简单实现向调用方暴露send/complete/error三个简化操作utils/src/main/java/software/amazon/awssdk/utils/async/SimplePublisher.javaByteBufferStoringSubscriber存储接收到的ByteBuffer数据、供调用方按需取出的 Subscriberutils/src/main/java/software/amazon/awssdk/utils/async/ByteBufferStoringSubscriber.javaSdkPublisher中的工具方法常见 Publisher 操作map、filter、buffer、limit等core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.java在 utils/src/main/java/software/amazon/awssdk/utils/async/ 目录下还有BufferingSubscriber、FilteringSubscriber、FlatteningSubscriber、LimitingSubscriber、SequentialSubscriber、EventListeningSubscriber、AddingTrailingDataSubscriber、IterablePublisher等更多可复用组件它们在SdkPublisher的默认方法中被组合使用详见下文第四节。三、核心工具类源码解析SimplePublisherSimplePublisherT位于 SimplePublisher.java是一个SdkProtectedApi标注的发布者实现其设计目标是把实现一个 Publisher这件事简化成三个操作CompletableFutureVoid send(T value)发送一条消息CompletableFutureVoid complete()表示消息流正常结束CompletableFutureVoid error(Throwable error)表示消息流异常结束。每个操作都返回一个CompletableFuture用于指示该操作是否已成功送达下游 Subscriber。典型调用序列为若干次send之后紧跟一次complete()或error(...)。3.1 内部机制基于事件队列的状态机从源码可以确认SimplePublisher的线程安全与信号顺序保证建立在事件队列模型之上双优先级队列standardPriorityQueue标准队列保存ON_NEXT、ON_COMPLETE、ON_ERROR事件highPriorityQueue高优先级队列用于插队专门承载终止类事件如Subscription.cancel()产生的CANCEL事件以及request(0)等非法请求触发的ON_ERROR。队列均采用ConcurrentLinkedQueue。单线程事件处理processingQueue这个AtomicBoolean保证同一时刻只有一个线程在处理队列processEventQueue()/doProcessQueue()既保证了线程安全又避免了onSubscribe/onNext与Subscription.request(long)之间可能出现的相互递归。需求计数outstandingDemandAtomicLong跟踪下游累计请求量只有ON_NEXT事件且需求大于 0 时才会被投递shouldProcessQueueEntry中对entry.type() ! ON_NEXT的事件不要求需求即可处理终止事件不受背压阻塞。单订阅限制subscribed标志保证只支持一个订阅者第二次subscribe会被拒绝收到NoOpSubscription并收到IllegalStateException(Only one subscription may be active at a time.)。信号时序保障onSubscribeInProgress标志确保在onSubscribe返回之前不会投递onNext对应 Reactive Streams 规则 1.03。终止后的引用清理流在complete、error、cancel任一终止时会将subscriber置空避免发布者长期持有订阅者引用对应规范规则 3.13FailureMessage惰性记录首个终止原因此后任何send/complete/error调用都会以该原因异常完成其 future。非法请求防护SubscriptionImpl.request(n)对n 0的请求直接向高优先级队列投入ON_ERROR事件并投递IllegalArgumentException。3.2 内存使用注意点源码 Javadoc 明确提示SimplePublisher会无界存储未送达的消息send调用后到 future 完成前消息驻留内存因此强烈建议调用方限制在途send的数量以控制内存占用。四、SdkPublisherSDK 面向异步 API 的发布者接口SdkPublisherT位于 SdkPublisher.java是SdkPublicApi公开接口继承org.reactivestreams.PublisherT由异步自动分页响应auto-paginated responses实现。它通过默认方法提供了一组声明式组合算子底层复用utils包中的 Subscriber 工具类方法作用底层实现adapt(Publisher)/fromIterable(Iterable)将普通 Publisher 或 Iterable 适配为 SdkPublisherIterablePublisherfilter(Class)/filter(Predicate)按类型或谓词过滤事件FilteringSubscribermap(Function)对事件做映射转换MappingSubscriberflatMapIterable(Function)映射为 Iterable 后逐个展平发出FlatteningSubscriberbuffer(int)按指定大小分批缓冲为List最后一批可能不足BufferingSubscriberlimit(int)最多发布 N 个事件到达上限后取消订阅LimitingSubscriberaddTrailingData(Supplier)在事件流末尾追加补充数据AddingTrailingDataSubscriberdoAfterOnComplete(Runnable)/doAfterOnError(Consumer)/doAfterOnCancel(Runnable)注册onComplete/onError/cancel之后的回调EventListeningSubscribersubscribe(Consumer)以 Consumer 订阅每个事件返回全部消费完成或出错时完成的CompletableFutureVoidSequentialSubscriber其中subscribe(Consumer)的 Javadoc 特别提醒若 Consumer 将处理异步分发出去则该方法无法提供背压需要精细控制背压时应改用标准的subscribe(Subscriber)。这正呼应了指南中处理好背压的通用模式要求。五、核心工具类源码解析ByteBufferStoringSubscriber 与 StoringSubscriber5.1 ByteBufferStoringSubscriberByteBufferStoringSubscriber位于 ByteBufferStoringSubscriber.java实现SubscriberByteBuffer职责是把收到的 ByteBuffer 事件暂存起来供调用方读取典型应用是异步 HTTP 响应的字节流消费例如 S3 流式下载。核心设计最小缓冲阈值构造时传入minimumBytesBuffered必须为正数Validate.isPositive校验订阅者会持续向上游请求数据直到已缓冲字节数达到该阈值当缓冲与在途数据之和低于阈值时再请求下一个ByteBuffer见maybeRequestMore中对dataBufferedAndInFlight的估算。数据读取transferTo(ByteBuffer out)将暂存数据拷贝到目标缓冲若out容量不足则填满为止若流已正常结束则返回TransferResult.END_OF_STREAM若上游onError则抛出对应异常RuntimeException否则返回TransferResult.SUCCESS。blockingTransferTo(ByteBuffer)是阻塞版本借助Phaser在无数据可读时等待状态更新、直到写出数据或到达流末尾。并发约束Javadoc 明确要求transferTo与blockingTransferTo二者不得并发调用但可与类上其他方法并发。内部委托底层委托StoringSubscriberByteBuffer存储事件并通过DemandIgnoringSubscription包装订阅以自行管理请求节奏。5.2 StoringSubscriberStoringSubscriberT位于 StoringSubscriber.java是更通用的事件暂存订阅者构造时指定maxEvents最大可存储事件数必须为正通过peek()/poll()观察与取出事件poll()取出一个事件后会自动向上游request(1)补足需求实现取出多少、请求多少的自然背压。onSubscribe时若已有订阅会先cancel()旧订阅随后一次性request(maxEvents)。六、通用模式Common Patterns指南总结的通用模式与上述源码实现一一对应使用SdkPublisher承载 SDK 特定的发布者实现异步分页响应等场景直接面向SdkPublisher编程可复用其丰富的组合算子。成功与失败场景都要做资源清理SimplePublisher在终止后置空subscriber、StoringSubscriber在onNext中校验空值并保证队列有界都是资源/内存清理的落地例子。优雅处理取消cancelSimplePublisher将取消建模为高优先级CANCEL事件确保取消尽快生效并让后续send的 future 以CancellationException完成有分配资源时必须一并清理。保证线程安全SimplePublisher用AtomicBoolean/AtomicLong/ConcurrentLinkedQueue支撑并发指南要求任何实现都要确保多线程下的正确性。文档化线程安全特性与执行上下文假设每个工具类 Javadoc 都明确标注了哪些方法可并发、哪些必须串行如ByteBufferStoringSubscriber.transferTo的并发约束这是必须延续的工程习惯。七、测试要求Testing Requirements7.1 TCK 验证测试是硬性要求指南规定所有响应式流实现必须包含 TCK 验证测试测试应当覆盖正常路径与边界情况包括流式传输进行中的取消cancellation during active streaming错误传播error propagation各种请求量场景下的背压处理backpressure handling under various request scenarios所有终止场景下的资源清理resource cleanup in all termination scenarios。7.2 仓库中的 TCK 测试实例仓库中已有大量遵循该要求的 TCK 测试可作为编写新测试的参考模板core/sdk-core/src/test/java/software/amazon/awssdk/core/async/SimpleSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/FileSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/BaosSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/IndividualPartSubscriberTckTest.javacore/http-auth-aws/src/test/java/software/amazon/awssdk/http/auth/aws/internal/signer/io/ChecksumSubscriberTckTest.javaservices-custom/s3-transfer-manager/src/test/java/software/amazon/awssdk/transfer/s3/internal/AsyncBufferingSubscriberTckTest.javaservices/s3/src/test/java/software/amazon/awssdk/services/s3/internal/multipart/MultipartDownloaderSubscriberTckTest.java以SimpleSubscriberTckTest为例其命名遵循{类名}TckTest约定从包路径看TCK 测试与对应实现放在同模块的test目录下便于与实现同步演进。这些测试覆盖了请求量、取消、错误与完成等各类场景正是指南 7.1 所要求的正常操作 边界情况落地。7.3 测试编写建议为每个新增/修改的 Publisher、Subscriber 实现新建XxxTckTest继承 TCK 提供的断言类将实现类作为被测对象注入在 TCK 覆盖之外针对实现特有行为补充单元测试如SimplePublisher的重复订阅拒绝、request(0)报错、终止后send异常完成等场景修改现有实现时务必运行该实现对应的 TCK 测试确保没有破坏规范合规性。八、开发流程落地检查清单结合指南与源码在仓库中贡献响应式流代码时可对照以下清单优先复用SdkPublisher组合算子与utils.async包内工具类避免从零实现确需自定义实现时严格遵循规范信号时序与背压/取消语义参考SimplePublisher的事件队列模型保证线程安全在所有终止路径complete / error / cancel完成资源清理并释放订阅者引用在 Javadoc 中明确线程安全边界与执行上下文假设编写并通过 TCK 验证测试覆盖取消、错误传播、多档请求量下的背压、终止场景的资源清理将 TCK 测试与实现放在同一模块的 test 目录遵循XxxTckTest命名约定。以上要求同时受仓库顶层 docs/guidelines/README.md 所列出的整体工程规范约束属于 SDK 开发者在响应式流模块必须遵守的硬性标准。九、相关资源本文依据的原始指南docs/guidelines/reactive-streams-guidelines.md规范说明入口含自动匹配规则**/*{Publisher,Subscriber}*.java.kiro/steering/reactive-streams-guidelines.md通用异步工具实现utils/src/main/java/software/amazon/awssdk/utils/async/SDK 发布者接口core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.java响应式流规范与 TCK由 Reactive Streams 官方项目 提供规范与 TCK 的 Maven 依赖声明可参考各模块pom.xml中对org.reactivestreams的引用【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AWS SDK for Java v2 响应式流（Reactive Streams）实现指南：规范符合性、常用模式与 TCK 测试要求
AWS SDK for Java v2 响应式流Reactive Streams实现指南规范符合性、常用模式与 TCK 测试要求【免费下载链接】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 官方仓库中的 Reactive Streams 实现指南对应 docs/guidelines/reactive-streams-guidelines.md的完整解读与源码级展开。AWS SDK for Java v2 的异步 API如 S3 流式上传/下载、异步分页响应、事件流等全部构建在 Reactive Streams 规范之上以实现非阻塞、可背压backpressure的数据处理。阅读本文后你将掌握该 SDK 对响应式流实现的强制合规要求、官方推荐的既有工具类SimplePublisher、ByteBufferStoringSubscriber、SdkPublisher的用法与内部机制、通用实现模式以及 TCK 验证测试的编写与覆盖要求能够直接指导你在该仓库内新增或修改 Publisher / Subscriber 实现。一、背景为什么 AWS SDK for Java v2 依赖 Reactive StreamsAWS SDK for Java v2 在异步场景下AsyncClient系列使用 Reactive Streams 作为异步、非阻塞数据处理的统一抽象核心诉求是背压支持——即下游消费者可以按自身处理能力向上游请求数据避免内存被无限堆积的数据撑爆。从源码结构看响应式流能力分布在两个核心包中utils/src/main/java/software/amazon/awssdk/utils/async/存放SimplePublisher、StoringSubscriber、ByteBufferStoringSubscriber、BufferingSubscriber、FilteringSubscriber、LimitingSubscriber等一批通用工具实现core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.javaSDK 面向异步 API 公开的发布者接口。该指南明确要求所有实现必须完全符合 Reactive Streams JVM 规范且必须通过 Reactive Streams Technology Compatibility KitTCK测试。任何对响应式流实现的代码改动都必须附带 TCK 验证测试。这两条是硬性约束MUST也是本指南的立论基础。二、实现指南Implementation Guidelines2.1 合规要求Compliance Requirements指南提出的三项强制要求如下完全符合 Reactive Streams 规范MUST所有 Publisher / Subscriber / Subscription 实现必须遵循规范中的各项规则包括信号时序onSubscribe→onNext* →onComplete/onError、背压语义request(n)只能增加需求、取消语义cancel()后不得再发送信号等。必须通过 Reactive Streams TCK 测试MUSTTCK 是规范官方提供的合规性测试套件对 Publisher、Subscriber、Subscription 分别提供断言测试用于验证实现是否满足规范的每条规则。响应式流实现的任何代码变更必须包含 TCK 验证测试MUST这保证了改动不会破坏规范合规性防止回归。2.2 最佳实践不要从零实现 Publisher / SubscriberSHOULD NOT指南给出明确建议开发者不应从零编写新的 Publisher 或 Subscriber 接口实现而应优先使用仓库内已有的、经过验证的工具类。官方推荐三类工具工具类定位源码位置SimplePublisherPublisher 接口的简单实现向调用方暴露send/complete/error三个简化操作utils/src/main/java/software/amazon/awssdk/utils/async/SimplePublisher.javaByteBufferStoringSubscriber存储接收到的ByteBuffer数据、供调用方按需取出的 Subscriberutils/src/main/java/software/amazon/awssdk/utils/async/ByteBufferStoringSubscriber.javaSdkPublisher中的工具方法常见 Publisher 操作map、filter、buffer、limit等core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.java在 utils/src/main/java/software/amazon/awssdk/utils/async/ 目录下还有BufferingSubscriber、FilteringSubscriber、FlatteningSubscriber、LimitingSubscriber、SequentialSubscriber、EventListeningSubscriber、AddingTrailingDataSubscriber、IterablePublisher等更多可复用组件它们在SdkPublisher的默认方法中被组合使用详见下文第四节。三、核心工具类源码解析SimplePublisherSimplePublisherT位于 SimplePublisher.java是一个SdkProtectedApi标注的发布者实现其设计目标是把实现一个 Publisher这件事简化成三个操作CompletableFutureVoid send(T value)发送一条消息CompletableFutureVoid complete()表示消息流正常结束CompletableFutureVoid error(Throwable error)表示消息流异常结束。每个操作都返回一个CompletableFuture用于指示该操作是否已成功送达下游 Subscriber。典型调用序列为若干次send之后紧跟一次complete()或error(...)。3.1 内部机制基于事件队列的状态机从源码可以确认SimplePublisher的线程安全与信号顺序保证建立在事件队列模型之上双优先级队列standardPriorityQueue标准队列保存ON_NEXT、ON_COMPLETE、ON_ERROR事件highPriorityQueue高优先级队列用于插队专门承载终止类事件如Subscription.cancel()产生的CANCEL事件以及request(0)等非法请求触发的ON_ERROR。队列均采用ConcurrentLinkedQueue。单线程事件处理processingQueue这个AtomicBoolean保证同一时刻只有一个线程在处理队列processEventQueue()/doProcessQueue()既保证了线程安全又避免了onSubscribe/onNext与Subscription.request(long)之间可能出现的相互递归。需求计数outstandingDemandAtomicLong跟踪下游累计请求量只有ON_NEXT事件且需求大于 0 时才会被投递shouldProcessQueueEntry中对entry.type() ! ON_NEXT的事件不要求需求即可处理终止事件不受背压阻塞。单订阅限制subscribed标志保证只支持一个订阅者第二次subscribe会被拒绝收到NoOpSubscription并收到IllegalStateException(Only one subscription may be active at a time.)。信号时序保障onSubscribeInProgress标志确保在onSubscribe返回之前不会投递onNext对应 Reactive Streams 规则 1.03。终止后的引用清理流在complete、error、cancel任一终止时会将subscriber置空避免发布者长期持有订阅者引用对应规范规则 3.13FailureMessage惰性记录首个终止原因此后任何send/complete/error调用都会以该原因异常完成其 future。非法请求防护SubscriptionImpl.request(n)对n 0的请求直接向高优先级队列投入ON_ERROR事件并投递IllegalArgumentException。3.2 内存使用注意点源码 Javadoc 明确提示SimplePublisher会无界存储未送达的消息send调用后到 future 完成前消息驻留内存因此强烈建议调用方限制在途send的数量以控制内存占用。四、SdkPublisherSDK 面向异步 API 的发布者接口SdkPublisherT位于 SdkPublisher.java是SdkPublicApi公开接口继承org.reactivestreams.PublisherT由异步自动分页响应auto-paginated responses实现。它通过默认方法提供了一组声明式组合算子底层复用utils包中的 Subscriber 工具类方法作用底层实现adapt(Publisher)/fromIterable(Iterable)将普通 Publisher 或 Iterable 适配为 SdkPublisherIterablePublisherfilter(Class)/filter(Predicate)按类型或谓词过滤事件FilteringSubscribermap(Function)对事件做映射转换MappingSubscriberflatMapIterable(Function)映射为 Iterable 后逐个展平发出FlatteningSubscriberbuffer(int)按指定大小分批缓冲为List最后一批可能不足BufferingSubscriberlimit(int)最多发布 N 个事件到达上限后取消订阅LimitingSubscriberaddTrailingData(Supplier)在事件流末尾追加补充数据AddingTrailingDataSubscriberdoAfterOnComplete(Runnable)/doAfterOnError(Consumer)/doAfterOnCancel(Runnable)注册onComplete/onError/cancel之后的回调EventListeningSubscribersubscribe(Consumer)以 Consumer 订阅每个事件返回全部消费完成或出错时完成的CompletableFutureVoidSequentialSubscriber其中subscribe(Consumer)的 Javadoc 特别提醒若 Consumer 将处理异步分发出去则该方法无法提供背压需要精细控制背压时应改用标准的subscribe(Subscriber)。这正呼应了指南中处理好背压的通用模式要求。五、核心工具类源码解析ByteBufferStoringSubscriber 与 StoringSubscriber5.1 ByteBufferStoringSubscriberByteBufferStoringSubscriber位于 ByteBufferStoringSubscriber.java实现SubscriberByteBuffer职责是把收到的 ByteBuffer 事件暂存起来供调用方读取典型应用是异步 HTTP 响应的字节流消费例如 S3 流式下载。核心设计最小缓冲阈值构造时传入minimumBytesBuffered必须为正数Validate.isPositive校验订阅者会持续向上游请求数据直到已缓冲字节数达到该阈值当缓冲与在途数据之和低于阈值时再请求下一个ByteBuffer见maybeRequestMore中对dataBufferedAndInFlight的估算。数据读取transferTo(ByteBuffer out)将暂存数据拷贝到目标缓冲若out容量不足则填满为止若流已正常结束则返回TransferResult.END_OF_STREAM若上游onError则抛出对应异常RuntimeException否则返回TransferResult.SUCCESS。blockingTransferTo(ByteBuffer)是阻塞版本借助Phaser在无数据可读时等待状态更新、直到写出数据或到达流末尾。并发约束Javadoc 明确要求transferTo与blockingTransferTo二者不得并发调用但可与类上其他方法并发。内部委托底层委托StoringSubscriberByteBuffer存储事件并通过DemandIgnoringSubscription包装订阅以自行管理请求节奏。5.2 StoringSubscriberStoringSubscriberT位于 StoringSubscriber.java是更通用的事件暂存订阅者构造时指定maxEvents最大可存储事件数必须为正通过peek()/poll()观察与取出事件poll()取出一个事件后会自动向上游request(1)补足需求实现取出多少、请求多少的自然背压。onSubscribe时若已有订阅会先cancel()旧订阅随后一次性request(maxEvents)。六、通用模式Common Patterns指南总结的通用模式与上述源码实现一一对应使用SdkPublisher承载 SDK 特定的发布者实现异步分页响应等场景直接面向SdkPublisher编程可复用其丰富的组合算子。成功与失败场景都要做资源清理SimplePublisher在终止后置空subscriber、StoringSubscriber在onNext中校验空值并保证队列有界都是资源/内存清理的落地例子。优雅处理取消cancelSimplePublisher将取消建模为高优先级CANCEL事件确保取消尽快生效并让后续send的 future 以CancellationException完成有分配资源时必须一并清理。保证线程安全SimplePublisher用AtomicBoolean/AtomicLong/ConcurrentLinkedQueue支撑并发指南要求任何实现都要确保多线程下的正确性。文档化线程安全特性与执行上下文假设每个工具类 Javadoc 都明确标注了哪些方法可并发、哪些必须串行如ByteBufferStoringSubscriber.transferTo的并发约束这是必须延续的工程习惯。七、测试要求Testing Requirements7.1 TCK 验证测试是硬性要求指南规定所有响应式流实现必须包含 TCK 验证测试测试应当覆盖正常路径与边界情况包括流式传输进行中的取消cancellation during active streaming错误传播error propagation各种请求量场景下的背压处理backpressure handling under various request scenarios所有终止场景下的资源清理resource cleanup in all termination scenarios。7.2 仓库中的 TCK 测试实例仓库中已有大量遵循该要求的 TCK 测试可作为编写新测试的参考模板core/sdk-core/src/test/java/software/amazon/awssdk/core/async/SimpleSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/FileSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/BaosSubscriberTckTest.javacore/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/IndividualPartSubscriberTckTest.javacore/http-auth-aws/src/test/java/software/amazon/awssdk/http/auth/aws/internal/signer/io/ChecksumSubscriberTckTest.javaservices-custom/s3-transfer-manager/src/test/java/software/amazon/awssdk/transfer/s3/internal/AsyncBufferingSubscriberTckTest.javaservices/s3/src/test/java/software/amazon/awssdk/services/s3/internal/multipart/MultipartDownloaderSubscriberTckTest.java以SimpleSubscriberTckTest为例其命名遵循{类名}TckTest约定从包路径看TCK 测试与对应实现放在同模块的test目录下便于与实现同步演进。这些测试覆盖了请求量、取消、错误与完成等各类场景正是指南 7.1 所要求的正常操作 边界情况落地。7.3 测试编写建议为每个新增/修改的 Publisher、Subscriber 实现新建XxxTckTest继承 TCK 提供的断言类将实现类作为被测对象注入在 TCK 覆盖之外针对实现特有行为补充单元测试如SimplePublisher的重复订阅拒绝、request(0)报错、终止后send异常完成等场景修改现有实现时务必运行该实现对应的 TCK 测试确保没有破坏规范合规性。八、开发流程落地检查清单结合指南与源码在仓库中贡献响应式流代码时可对照以下清单优先复用SdkPublisher组合算子与utils.async包内工具类避免从零实现确需自定义实现时严格遵循规范信号时序与背压/取消语义参考SimplePublisher的事件队列模型保证线程安全在所有终止路径complete / error / cancel完成资源清理并释放订阅者引用在 Javadoc 中明确线程安全边界与执行上下文假设编写并通过 TCK 验证测试覆盖取消、错误传播、多档请求量下的背压、终止场景的资源清理将 TCK 测试与实现放在同一模块的 test 目录遵循XxxTckTest命名约定。以上要求同时受仓库顶层 docs/guidelines/README.md 所列出的整体工程规范约束属于 SDK 开发者在响应式流模块必须遵守的硬性标准。九、相关资源本文依据的原始指南docs/guidelines/reactive-streams-guidelines.md规范说明入口含自动匹配规则**/*{Publisher,Subscriber}*.java.kiro/steering/reactive-streams-guidelines.md通用异步工具实现utils/src/main/java/software/amazon/awssdk/utils/async/SDK 发布者接口core/sdk-core/src/main/java/software/amazon/awssdk/core/async/SdkPublisher.java响应式流规范与 TCK由 Reactive Streams 官方项目 提供规范与 TCK 的 Maven 依赖声明可参考各模块pom.xml中对org.reactivestreams的引用【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考