RSocket

RSocket 的一项优点就在于它在传输线上有明确的行为，还有一个该协议的https://rsocket.io/about/protocol[规范]以及该协议的几个https://github.com/rsocket/rsocket/tree/master/Extensions[扩展]，但它们都很容易阅读。因此，阅读一下该规范是个好主意，虽然该规范和语言实现及更高级的框架 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 的https://github.com/rsocket/rsocket-java[Java 实现]建立在https://projectreactor.io/[Project Reactor]之上。TCP 和 WebSocket 的传输建立在https://github.com/reactor/reactor-netty[Reactor Netty]之上。Reactor 是一个反应式流库，它简化了实现该协议的工作。对于应用程序来说，与 `Flux`和 `Mono`配合使用具有声明式运算符和透明反压支持，这是一个自然而然的选择。

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

主合约https://github.com/rsocket/rsocket-java/tree/master//rsocket-core/src/main/java/io/rsocket/RSocket.java[io.rsocket.RSocket]对四种请求交互类型进行了建模，其中 `Mono`表示一条消息的承诺，`Flux`表示一系列消息，而 `io.rsocket.Payload`则表示实际消息（可访问到数据和元数据，形式是字节缓冲区）。对 `RSocket`契约的对称使用。对于请求，应用程序会收到一个 `RSocket`来执行请求。对于响应，应用程序实现 `RSocket`以处理请求。

这并不是一个全面的介绍。在大多数情况下，Spring 应用程序不必直接使用其 API。然而，独立于 Spring 查看或体验 RSocket 可能很重要。RSocket Java 存储库包含许多https://github.com/rsocket/rsocket-java/tree/master//rsocket-examples[示例应用]，展示了其 API 和协议特性。

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

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

Spring Boot 2.2 支持在 TCP 或 WebSocket 上建立一个 RSocket 服务器，包括在 WebFlux 服务器中通过 WebSocket 公开 RSocket 的选项。对于一个 RSocketRequester.Builder`和 `RSocketStrategies，还有客户端支持和自动配置。有关更多详细信息，请参阅 Spring Boot 参考中的https://docs.spring.io/spring-boot/docs/current/reference/html/messaging.html#messaging.rsocket[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 帧的连接设置。

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

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

从服务器向已连接客户端发出请求，只涉及从服务器获取已连接客户端的请求者。

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

获得 client 或 server 请求者后，你可以如下进行请求：

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

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

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

如果使用https://github.com/rsocket/rsocket/tree/master/Extensions/CompositeMetadata.md[复合元数据]（默认值）并且注册的 `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 默认支持 composite 和 routing 元数据。如果你需要切换到不同 MIME 类型或注册其他元数据 MIME 类型，可以设置其 MetadataExtractor。

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

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

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

客户机端的带注释响应器需要在`RSocketRequester.Builder`中配置。有关详细信息，请参见Client Responders。

一旦server或client响应器配置就绪，就可以使用`@MessageMapping`方法，如下所示：

上述 @MessageMapping 方法响应具有路由“locate.radars.within”的请求流交互。它支持一个灵活的方法签名，其中提供使用以下方法参数的选项：

返回值预期是多个对象，其作为响应有效负载进行序列化。这可以是异步类型（如 Mono 或 Flux）、一个具体值、void 或无值异步类型（如 Mono<Void>）。

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

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

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

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

@RSocketExhange 和 @MessageMapping 之间有一些区别，因为前者需要适用于请求者和响应者的使用。例如，虽然 @MessageMapping 可以声明为处理任意数量的路由，且每个路由可以是一个模式，但 @RSocketExchange 必须使用一个具体的路由声明。还有一些与元数据相关的受支持方法参数的差异，有关受支持参数的列表，请参见 <<@MessageMapping，rsocket-annot-messagemapping>> 和 [RSocket Interface，rsocket-interface]。

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

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

@ConnectMapping`方法支持与@MessageMapping相同的自变量，但基于来自`SETUP`和`METADATA_PUSH`帧的元数据和数据。@ConnectMapping`可以有一个模式，可以将处理范围缩小到具有元数据中路由的特定连接，或者如果没有声明模式，则所有连接都匹配。

`@ConnectMapping`方法不能返回数据，并且必须声明为以`void`或`Mono<Void>`作为返回值。如果处理为新连接返回错误，则拒绝该连接。不得保留处理以向`RSocketRequester`发出连接请求。有关详细信息，请参见Server Requester。

经过注释的 RSocket 交换方法支持具有以下方法参数的灵活方法签名：

带注释的 RSocket 交换方法支持返回具体值或能够通过 ReactiveAdapterRegistry 调整到 Reactive Streams Publisher 的任何值生成器。

默认情况下，具有同步（阻塞）方法签名的 RSocket 服务方法的行为取决于 RSocket ClientTransport 的响应超时设置以及 RSocket 保活设置。RSocketServiceProxyFactory.Builder 公开了一个 blockTimeout 选项，还允许您配置阻塞响应的最大时间，但是我们建议在 RSocket 层配置超时值，以获得更好的控制。