RSocket

RSocket 的优点之一是它具有定义明确的线上传输行为和易于阅读的 规范 以及一些协议 扩展。因此，阅读规范是一个好主意，而无需考虑语言实现和更高级别的框架 API。本节提供了一个简洁的概述，以建立一些上下文。

连接

最初，客户端通过 TCP 或 WebSocket 等低级流传输连接到服务器，并向服务器发送 SETUP 帧以设置连接参数。

服务器可能会拒绝 SETUP 帧，但通常在发送（对于客户端）和接收（对于服务器）之后，双方都可以开始发出请求，除非 SETUP 指示使用租约语义来限制请求数量，在这种情况下，双方必须等待来自另一端的 LEASE 帧以允许发出请求。

发出请求

一旦建立连接，双方都可以通过 REQUEST_RESPONSE、REQUEST_STREAM、REQUEST_CHANNEL 或 REQUEST_FNF 帧发起请求。每个帧都携带一条从请求者到响应者的消息。

然后，响应者可以返回带有响应消息的 PAYLOAD 帧，在 REQUEST_CHANNEL 的情况下，请求者也可以发送带有更多请求消息的 PAYLOAD 帧。

当请求涉及消息流（例如 Request-Stream 和 Channel）时，响应者必须遵守来自请求者的需求信号。需求表示为消息数量。初始需求在 REQUEST_STREAM 和 REQUEST_CHANNEL 帧中指定。后续需求通过 REQUEST_N 帧发出信号。

双方还可以通过 METADATA_PUSH 帧发送元数据通知，这些通知不属于任何单个请求，而是针对整个连接。

消息格式

RSocket 消息包含数据和元数据。元数据可用于发送路由、安全令牌等。数据和元数据可以以不同的格式进行格式化。每种数据的 mime 类型在 SETUP 帧中声明，并适用于给定连接上的所有请求。

虽然所有消息都可以包含元数据，但通常路由等元数据是按请求的，因此仅包含在请求的第一条消息中，即与 REQUEST_RESPONSE、REQUEST_STREAM、REQUEST_CHANNEL 或 REQUEST_FNF 帧之一一起。

协议扩展定义了用于应用程序的常见元数据格式：

RSocket 的 Java 实现 基于 Project Reactor 构建。TCP 和 WebSocket 的传输基于 Reactor Netty 构建。作为一个 Reactive Streams 库，Reactor 简化了协议的实现工作。对于应用程序来说，使用 Flux 和 Mono 配合声明式操作符和透明的背压支持是自然的选择。

RSocket Java 中的 API 故意保持最小和基本。它专注于协议特性，并将应用程序编程模型（例如，RPC 代码生成与其他）作为一个更高级别、独立的问题。

主要契约 io.rsocket.RSocket 使用 Mono 表示单个消息的承诺，Flux 表示消息流，io.rsocket.Payload 表示实际消息，可访问数据和元数据作为字节缓冲区，对四种请求交互类型进行建模。RSocket 契约是对称使用的。对于请求，应用程序获得一个 RSocket 来执行请求。对于响应，应用程序实现 RSocket 来处理请求。

这并非详尽的介绍。在大多数情况下，Spring 应用程序无需直接使用其 API。但是，独立于 Spring 查看或试验 RSocket 可能很重要。RSocket Java 存储库包含许多 示例应用程序，演示其 API 和协议特性。

spring-messaging 模块包含以下内容：

spring-web 模块包含 Encoder 和 Decoder 实现，例如 Jackson CBOR/JSON 和 Protobuf，RSocket 应用程序可能需要这些实现。它还包含 PathPatternParser，可以插入以实现高效的路由匹配。

Spring Boot 2.2 支持通过 TCP 或 WebSocket 启动 RSocket 服务器，包括在 WebFlux 服务器中通过 WebSocket 公开 RSocket 的选项。还提供了客户端支持和 RSocketRequester.Builder 和 RSocketStrategies 的自动配置。有关更多详细信息，请参阅 Spring Boot 参考手册中的 RSocket 部分。

Spring Security 5.2 提供 RSocket 支持。

Spring Integration 5.2 提供入站和出站网关，用于与 RSocket 客户端和服务器交互。有关更多详细信息，请参阅 Spring Integration 参考手册。

Spring Cloud Gateway 支持 RSocket 连接。

在客户端获取 RSocketRequester 是连接到服务器，这涉及到发送一个带有连接设置的 RSocket SETUP 帧。RSocketRequester 提供了一个构建器，有助于准备 io.rsocket.core.RSocketConnector，包括 SETUP 帧的连接设置。

这是使用默认设置连接的最基本方式：

上述操作不会立即连接。当发出请求时，将透明地建立并使用一个共享连接。

要从服务器向连接的客户端发出请求，只需从服务器获取连接客户端的请求者即可。

在 rsocket-annot-responders 中，@ConnectMapping 和 @MessageMapping 方法支持 RSocketRequester 参数。使用它来访问连接的请求者。请记住，@ConnectMapping 方法本质上是 SETUP 帧的处理程序，必须在请求开始之前处理。因此，最开始的请求必须与处理解耦。例如：

一旦您拥有 rsocket-requester-client 或 rsocket-requester-server 请求者，您可以按如下方式发出请求：

交互类型由输入和输出的基数隐式决定。上面的示例是 Request-Stream，因为发送了一个值并接收了一个值流。在大多数情况下，只要输入和输出的选择与 RSocket 交互类型以及响应者预期的输入和输出类型匹配，您就不需要考虑这一点。唯一无效组合的示例是多对一。

data(Object) 方法还接受任何 Reactive Streams Publisher，包括 Flux 和 Mono，以及在 ReactiveAdapterRegistry 中注册的任何其他值生产者。对于产生相同类型值的多值 Publisher（例如 Flux），请考虑使用重载的 data 方法之一，以避免在每个元素上进行类型检查和 Encoder 查找：

data(Object) 步骤是可选的。对于不发送数据的请求，跳过此步骤：

如果使用 复合元数据（默认）并且值受注册的 Encoder 支持，则可以添加额外的元数据值。例如：

对于 Fire-and-Forget，使用返回 Mono<Void> 的 send() 方法。请注意，Mono 仅表示消息已成功发送，而不表示已处理。

对于 Metadata-Push，使用返回 Mono<Void> 的 sendMetadata() 方法。

要在服务器端使用注解响应者，请将 RSocketMessageHandler 添加到您的 Spring 配置中，以检测带有 @MessageMapping 和 @ConnectMapping 方法的 @Controller bean：

然后通过 Java RSocket API 启动 RSocket 服务器，并按如下方式插入 RSocketMessageHandler 作为响应者：

RSocketMessageHandler 默认支持 复合 和 路由 元数据。如果您需要切换到不同的 mime 类型或注册其他元数据 mime 类型，可以设置其 rsocket-metadata-extractor。

您需要设置数据和元数据格式所需的 Encoder 和 Decoder 实例。您可能需要 spring-web 模块以获取编解码器实现。

默认情况下，SimpleRouteMatcher 用于通过 AntPathMatcher 匹配路由。我们建议插入 spring-web 中的 PathPatternRouteMatcher 以实现高效的路由匹配。RSocket 路由可以是分层的，但不是 URL 路径。这两个路由匹配器都默认配置为使用 "." 作为分隔符，并且不像 HTTP URL 那样进行 URL 解码。

RSocketMessageHandler 可以通过 RSocketStrategies 进行配置，如果您需要在同一个进程中的客户端和服务器之间共享配置，这可能会很有用：

客户端的注解响应者需要在 RSocketRequester.Builder 中进行配置。有关详细信息，请参阅 rsocket-requester-client-responder。

一旦 rsocket-annot-responders-server 或 rsocket-annot-responders-client 响应者配置到位，就可以按如下方式使用 @MessageMapping 方法：

上述 @MessageMapping 方法响应路由为 "locate.radars.within" 的 Request-Stream 交互。它支持灵活的方法签名，并可选择使用以下方法参数：

返回值预期是一个或多个对象，将被序列化为响应负载。这可以是异步类型，如 Mono 或 Flux，一个具体值，或者 void 或无值异步类型，如 Mono<Void>。

@MessageMapping 方法支持的 RSocket 交互类型由输入（即 @Payload 参数）和输出的基数决定，其中基数表示以下内容：

下表显示了所有输入和输出基数组合以及相应的交互类型：

作为 @MessageMapping 的替代方案，您还可以使用 @RSocketExchange 方法处理请求。此类方法在 rsocket-interface 上声明，可以通过 RSocketServiceProxyFactory 用作请求者，或由响应者实现。

例如，作为响应者处理请求：

@RSocketExhange 和 @MessageMapping 之间存在一些差异，因为前者需要保持适用于请求者和响应者。例如，虽然 @MessageMapping 可以声明为处理任意数量的路由，并且每个路由都可以是模式，但 @RSocketExchange 必须声明为单个具体路由。在支持的方法参数方面也存在细微差异，请参阅 <<@MessageMapping,rsocket-annot-messagemapping>> 和 rsocket-interface 以获取支持参数的列表。

@RSocketExchange 可以在类型级别使用，以指定给定 RSocket 服务接口的所有路由的通用前缀。

@ConnectMapping 处理 RSocket 连接开始时的 SETUP 帧，以及随后通过 METADATA_PUSH 帧进行的任何元数据推送通知，即 io.rsocket.RSocket 中的 metadataPush(Payload)。

@ConnectMapping 方法支持与 <<@MessageMapping,rsocket-annot-messagemapping>> 相同的参数，但基于 SETUP 和 METADATA_PUSH 帧中的元数据和数据。@ConnectMapping 可以具有模式以将处理范围缩小到元数据中具有路由的特定连接，或者如果未声明任何模式，则所有连接都匹配。

@ConnectMapping 方法不能返回数据，并且必须声明为 void 或 Mono<Void> 作为返回值。如果处理对新连接返回错误，则连接将被拒绝。处理不得暂停以对连接的 RSocketRequester 发出请求。有关详细信息，请参阅 rsocket-requester-server。

带注解的 RSocket 交换方法支持灵活的方法签名，具有以下方法参数：

带注解的 RSocket 交换方法支持返回值，这些返回值可以是具体值，也可以是任何可以通过 ReactiveAdapterRegistry 适配为 Reactive Streams Publisher 的值生产者。

默认情况下，RSocket 服务方法的同步（阻塞）方法签名的行为取决于底层 RSocket ClientTransport 的响应超时设置以及 RSocket keep-alive 设置。RSocketServiceProxyFactory.Builder 确实公开了一个 blockTimeout 选项，也允许您配置阻塞响应的最长时间，但我们建议在 RSocket 级别配置超时值以获得更多控制。