RSocket

本节描述了 Spring Framework 对 RSocket 协议的支持。

概述

RSocket 是一种应用协议，用于通过 TCP、WebSocket 和其他字节流传输进行多路复用、双工通信，使用以下交互模型之一：

  • Request-Response（请求-响应）——发送一条消息并接收一条响应。

  • Request-Stream（请求-流）——发送一条消息并接收一个消息流。

  • Channel（通道）——双向发送消息流。

  • Fire-and-Forget（即发即弃）——发送一个单向消息。

一旦建立初始连接，“客户端”与“服务器”的区别就消失了，双方变得对称，每一方都可以发起上述交互之一。这就是为什么协议中将参与方称为“请求者”和“响应者”，而上述交互被称为“请求流”或简称“请求”。

以下是 RSocket 协议的主要特性和优势：

  • Reactive Streams（响应式流）语义跨网络边界——对于像 Request-Stream 和 Channel 这样的流式请求，背压信号在请求者和响应者之间传播，允许请求者在源头减慢响应者，从而减少对网络层拥塞控制的依赖，以及在网络层或任何层进行缓冲的需求。

  • 请求节流——此功能被命名为“租约”（Leasing），源于 LEASE 帧，该帧可以从每一端发送，以限制另一端在给定时间内允许的总请求数。租约会定期续订。

  • 会话恢复——这旨在应对连接丢失，并需要维护一些状态。状态管理对应用程序是透明的，并且与背压结合良好，背压可以在可能的情况下停止生产者并减少所需的状态量。

  • 大型消息的碎片化和重组。

  • 保持活动（心跳）。

RSocket 在多种语言中都有实现。Java 库构建在 Project Reactor 之上，并使用 Reactor Netty 作为传输层。这意味着应用程序中 Reactive Streams Publisher 的信号会通过 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 帧中的一个。

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

Java 实现

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 支持

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

  • RSocketRequester——流式 API，通过 io.rsocket.RSocket 发出请求，支持数据和元数据的编码/解码。

  • 带注解的响应器——带有 @MessageMapping 和 @RSocketExchange 注解的处理程序方法，用于响应。

  • RSocket 接口——将 RSocket 服务声明为带有 @RSocketExchange 方法的 Java 接口，用作请求者或响应器。

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

RSocketRequester 提供了一个流式 API 来执行 RSocket 请求，接受并返回用于数据和元数据的对象，而不是低级数据缓冲区。它可以对称使用，用于从客户端发出请求以及从服务器发出请求。

客户端请求者

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

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

  • Java

  • Kotlin

RSocketRequester requester = RSocketRequester.builder().tcp("localhost", 7000);

URI url = URI.create("https://example.org:8080/rsocket");
RSocketRequester requester = RSocketRequester.builder().webSocket(url);
val requester = RSocketRequester.builder().tcp("localhost", 7000)

URI url = URI.create("https://example.org:8080/rsocket");
val requester = RSocketRequester.builder().webSocket(url)

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

连接设置

RSocketRequester.Builder 提供以下内容来定制初始的 SETUP 帧：

  • dataMimeType(MimeType)——设置连接上数据的 MIME 类型。

  • metadataMimeType(MimeType)——设置连接上元数据的 MIME 类型。

  • setupData(Object)——包含在 SETUP 中的数据。

  • setupRoute(String, Object…​)——包含在 SETUP 元数据中的路由。

  • setupMetadata(Object, MimeType)——包含在 SETUP 中的其他元数据。

对于数据，默认的 MIME 类型是从第一个配置的 Decoder 派生出来的。对于元数据，默认的 MIME 类型是复合元数据，它允许每个请求有多个元数据值和 MIME 类型对。通常，两者都不需要更改。

SETUP 帧中的数据和元数据是可选的。在服务器端，@ConnectMapping 方法可用于处理连接的开始和 SETUP 帧的内容。元数据可用于连接级别的安全性。

策略

RSocketRequester.Builder 接受 RSocketStrategies 来配置请求者。您需要使用它来为数据和元数据值的（反）序列化提供编码器和解码器。默认情况下，只注册了 spring-core 中用于 String、byte[] 和 ByteBuffer 的基本编解码器。添加 spring-web 可以访问更多可以按如下方式注册的编解码器：

  • Java

  • Kotlin

RSocketStrategies strategies = RSocketStrategies.builder()
	.encoders(encoders -> encoders.add(new Jackson2CborEncoder()))
	.decoders(decoders -> decoders.add(new Jackson2CborDecoder()))
	.build();

RSocketRequester requester = RSocketRequester.builder()
	.rsocketStrategies(strategies)
	.tcp("localhost", 7000);
val strategies = RSocketStrategies.builder()
		.encoders { it.add(Jackson2CborEncoder()) }
		.decoders { it.add(Jackson2CborDecoder()) }
		.build()

val requester = RSocketRequester.builder()
		.rsocketStrategies(strategies)
		.tcp("localhost", 7000)

RSocketStrategies 旨在重用。在某些场景下，例如，同一个应用程序中的客户端和服务器，最好在 Spring 配置中声明它。

客户端响应器

RSocketRequester.Builder 可用于配置对来自服务器的请求的响应器。

您可以使用带注解的处理程序进行客户端响应，它基于与服务器上使用的相同基础设施，但通过编程方式注册，如下所示：

  • Java

  • Kotlin

RSocketStrategies strategies = RSocketStrategies.builder()
	.routeMatcher(new PathPatternRouteMatcher())  (1)
	.build();

SocketAcceptor responder =
	RSocketMessageHandler.responder(strategies, new ClientHandler()); (2)

RSocketRequester requester = RSocketRequester.builder()
	.rsocketConnector(connector -> connector.acceptor(responder)) (3)
	.tcp("localhost", 7000);
1 如果存在 spring-web，请使用 PathPatternRouteMatcher 以实现高效的路由匹配。
2 从带有 @MessageMapping 和/或 @ConnectMapping 方法的类创建响应器。
3 注册响应器。 
val strategies = RSocketStrategies.builder()
		.routeMatcher(PathPatternRouteMatcher())  (1)
		.build()

val responder =
	RSocketMessageHandler.responder(strategies, new ClientHandler()); (2)

val requester = RSocketRequester.builder()
		.rsocketConnector { it.acceptor(responder) } (3)
		.tcp("localhost", 7000)
1 如果存在 spring-web，请使用 PathPatternRouteMatcher 以实现高效的路由匹配。
2 从带有 @MessageMapping 和/或 @ConnectMapping 方法的类创建响应器。
3 注册响应器。

请注意，上述只是为客户端响应器的编程注册而设计的快捷方式。对于替代场景，即客户端响应器在 Spring 配置中，您仍然可以将 RSocketMessageHandler 声明为 Spring bean，然后按如下方式应用：

  • Java

  • Kotlin

ApplicationContext context = ... ;
RSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class);

RSocketRequester requester = RSocketRequester.builder()
	.rsocketConnector(connector -> connector.acceptor(handler.responder()))
	.tcp("localhost", 7000);
import org.springframework.beans.factory.getBean

val context: ApplicationContext = ...
val handler = context.getBean<RSocketMessageHandler>()

val requester = RSocketRequester.builder()
		.rsocketConnector { it.acceptor(handler.responder()) }
		.tcp("localhost", 7000)

对于上述情况，您可能还需要在 RSocketMessageHandler 中使用 setHandlerPredicate 来切换到不同的策略来检测客户端响应器，例如，基于自定义注解（如 @RSocketClientResponder）而不是默认的 @Controller。这在同一个应用程序中包含客户端和服务器或多个客户端的场景中是必需的。

另请参阅带注解的响应器，了解更多关于编程模型的信息。

高级

RSocketRequesterBuilder 提供了一个回调，以公开底层的 io.rsocket.core.RSocketConnector，用于进一步配置 keepalive 间隔、会话恢复、拦截器等选项。您可以在该级别配置选项，如下所示：

  • Java

  • Kotlin

RSocketRequester requester = RSocketRequester.builder()
	.rsocketConnector(connector -> {
		// ...
	})
	.tcp("localhost", 7000);
val requester = RSocketRequester.builder()
		.rsocketConnector {
			//...
		}
		.tcp("localhost", 7000)

服务器请求者

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

在带注解的响应器中，@ConnectMapping 和 @MessageMapping 方法支持 RSocketRequester 参数。使用它来访问连接的请求器。请记住，@ConnectMapping 方法本质上是 SETUP 帧的处理程序，必须在请求开始之前进行处理。因此，开始时的请求必须与处理解耦。例如：

  • Java

  • Kotlin

@ConnectMapping
Mono<Void> handle(RSocketRequester requester) {
	requester.route("status").data("5")
		.retrieveFlux(StatusReport.class)
		.subscribe(bar -> { (1)
			// ...
		});
	return ... (2)
}
1 异步启动请求，独立于处理。
2 执行处理并返回完成的 Mono<Void>。 
@ConnectMapping
suspend fun handle(requester: RSocketRequester) {
	GlobalScope.launch {
		requester.route("status").data("5").retrieveFlow<StatusReport>().collect { (1)
			// ...
		}
	}
	/// ... (2)
}
1 异步启动请求，独立于处理。
2 在挂起函数中执行处理。

请求

一旦您有了客户端或服务器请求者，您可以按如下方式发出请求：

  • Java

  • Kotlin

ViewBox viewBox = ... ;

Flux<AirportLocation> locations = requester.route("locate.radars.within") (1)
		.data(viewBox) (2)
		.retrieveFlux(AirportLocation.class); (3)
1 指定一个路由以包含在请求消息的元数据中。
2 为请求消息提供数据。
3 声明预期的响应。 
val viewBox: ViewBox = ...

val locations = requester.route("locate.radars.within") (1)
		.data(viewBox) (2)
		.retrieveFlow<AirportLocation>() (3)
1 指定一个路由以包含在请求消息的元数据中。
2 为请求消息提供数据。
3 声明预期的响应。

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

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

data(Object producer, Class<?> elementClass);
data(Object producer, ParameterizedTypeReference<?> elementTypeRef);

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

  • Java

  • Kotlin

Mono<AirportLocation> location = requester.route("find.radar.EWR"))
	.retrieveMono(AirportLocation.class);
import org.springframework.messaging.rsocket.retrieveAndAwait

val location = requester.route("find.radar.EWR")
	.retrieveAndAwait<AirportLocation>()

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

  • Java

  • Kotlin

String securityToken = ... ;
ViewBox viewBox = ... ;
MimeType mimeType = MimeType.valueOf("message/x.rsocket.authentication.bearer.v0");

Flux<AirportLocation> locations = requester.route("locate.radars.within")
		.metadata(securityToken, mimeType)
		.data(viewBox)
		.retrieveFlux(AirportLocation.class);
import org.springframework.messaging.rsocket.retrieveFlow

val requester: RSocketRequester = ...

val securityToken: String = ...
val viewBox: ViewBox = ...
val mimeType = MimeType.valueOf("message/x.rsocket.authentication.bearer.v0")

val locations = requester.route("locate.radars.within")
		.metadata(securityToken, mimeType)
		.data(viewBox)
		.retrieveFlow<AirportLocation>()

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

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

带注解的响应器

RSocket 响应器可以作为 @MessageMapping 和 @ConnectMapping 方法实现。@MessageMapping 方法处理单个请求，而 @ConnectMapping 方法处理连接级别的事件（设置和元数据推送）。带注解的响应器是对称支持的，用于从服务器端响应和从客户端响应。

服务器响应器

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

  • Java

  • Kotlin

@Configuration
static class ServerConfig {

	@Bean
	public RSocketMessageHandler rsocketMessageHandler() {
		RSocketMessageHandler handler = new RSocketMessageHandler();
		handler.routeMatcher(new PathPatternRouteMatcher());
		return handler;
	}
}
@Configuration
class ServerConfig {

	@Bean
	fun rsocketMessageHandler() = RSocketMessageHandler().apply {
		routeMatcher = PathPatternRouteMatcher()
	}
}

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

  • Java

  • Kotlin

ApplicationContext context = ... ;
RSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class);

CloseableChannel server =
	RSocketServer.create(handler.responder())
		.bind(TcpServerTransport.create("localhost", 7000))
		.block();
import org.springframework.beans.factory.getBean

val context: ApplicationContext = ...
val handler = context.getBean<RSocketMessageHandler>()

val server = RSocketServer.create(handler.responder())
		.bind(TcpServerTransport.create("localhost", 7000))
		.awaitSingle()

RSocketMessageHandler 默认支持复合和路由元数据。如果您需要切换到不同的 MIME 类型或注册额外的元数据 MIME 类型，可以设置其MetadataExtractor。

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

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

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

  • Java

  • Kotlin

@Configuration
static class ServerConfig {

	@Bean
	public RSocketMessageHandler rsocketMessageHandler() {
		RSocketMessageHandler handler = new RSocketMessageHandler();
		handler.setRSocketStrategies(rsocketStrategies());
		return handler;
	}

	@Bean
	public RSocketStrategies rsocketStrategies() {
		return RSocketStrategies.builder()
			.encoders(encoders -> encoders.add(new Jackson2CborEncoder()))
			.decoders(decoders -> decoders.add(new Jackson2CborDecoder()))
			.routeMatcher(new PathPatternRouteMatcher())
			.build();
	}
}
@Configuration
class ServerConfig {

	@Bean
	fun rsocketMessageHandler() = RSocketMessageHandler().apply {
		rSocketStrategies = rsocketStrategies()
	}

	@Bean
	fun rsocketStrategies() = RSocketStrategies.builder()
			.encoders { it.add(Jackson2CborEncoder()) }
			.decoders { it.add(Jackson2CborDecoder()) }
			.routeMatcher(PathPatternRouteMatcher())
			.build()
}

客户端响应器

客户端的带注解响应器需要在 RSocketRequester.Builder 中进行配置。有关详细信息，请参阅客户端响应器。

@MessageMapping

一旦服务器或客户端响应器配置到位，@MessageMapping 方法可以按如下方式使用：

  • Java

  • Kotlin

@Controller
public class RadarsController {

	@MessageMapping("locate.radars.within")
	public Flux<AirportLocation> radars(MapRequest request) {
		// ...
	}
}
@Controller
class RadarsController {

	@MessageMapping("locate.radars.within")
	fun radars(request: MapRequest): Flow<AirportLocation> {
		// ...
	}
}

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

方法参数 描述

@Payload

请求的有效载荷。这可以是具体的值，也可以是像 Mono 或 Flux 这样的异步类型。

注意：注解的使用是可选的。一个不是简单类型且不是其他任何受支持参数的方法参数，被假定为预期的有效载荷。

RSocketRequester

用于向远程端发出请求的请求者。

@DestinationVariable

根据映射模式中的变量从路由中提取的值，例如，@MessageMapping("find.radar.{id}")。

@Header

已注册用于提取的元数据值，如MetadataExtractor中所述。

@Headers Map<String, Object>

所有已注册用于提取的元数据值，如MetadataExtractor中所述。

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

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

基数 描述

1

可以是显式值，也可以是单值异步类型，例如 Mono<T>。

多

一个多值异步类型，例如 Flux<T>。

0

对于输入，这意味着方法没有 @Payload 参数。

对于输出，这是 void 或无值异步类型，例如 Mono<Void>。

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

输入基数 输出基数 交互类型

0, 1

0

即发即弃，请求-响应

0, 1

1

请求-响应

0, 1

多

请求-流

多

0，1，多

请求-通道

@RSocketExchange

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

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

  • Java

  • Kotlin

public interface RadarsService {

	@RSocketExchange("locate.radars.within")
	Flux<AirportLocation> radars(MapRequest request);
}

@Controller
public class RadarsController implements RadarsService {

	public Flux<AirportLocation> radars(MapRequest request) {
		// ...
	}
}
interface RadarsService {

	@RSocketExchange("locate.radars.within")
	fun radars(request: MapRequest): Flow<AirportLocation>
}

@Controller
class RadarsController : RadarsService {

	override fun radars(request: MapRequest): Flow<AirportLocation> {
		// ...
	}
}

@RSocketExchange 和 @MessageMapping 之间存在一些差异，因为前者需要保持适用于请求者和响应者。例如，虽然 @MessageMapping 可以声明为处理任意数量的路由，并且每个路由都可以是模式，但 @RSocketExchange 必须声明一个单一的、具体的路由。在支持的元数据相关方法参数上也有细微差别，请参阅@MessageMapping 和RSocket 接口以获取支持参数列表。

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

@ConnectMapping

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

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

@ConnectMapping 方法不能返回数据，并且必须声明 void 或 Mono<Void> 作为返回值。如果处理程序为新连接返回错误，则连接将被拒绝。处理程序不得被阻止以向连接的 RSocketRequester 发出请求。有关详细信息，请参阅服务器请求器。

MetadataExtractor

响应器必须解释元数据。复合元数据允许独立格式化的元数据值（例如，用于路由、安全、跟踪），每个值都有自己的 MIME 类型。应用程序需要一种方法来配置要支持的元数据 MIME 类型，以及一种访问提取值的方法。

MetadataExtractor 是一个契约，用于接收序列化的元数据并返回解码后的名称-值对，这些名称-值对可以通过名称像头一样访问，例如通过带注解的处理程序方法中的 @Header。

DefaultMetadataExtractor 可以提供 Decoder 实例来解码元数据。它开箱即用地支持"message/x.rsocket.routing.v0"，它将其解码为 String 并以 "route" 键保存。对于任何其他 MIME 类型，您需要提供 Decoder 并按如下方式注册 MIME 类型：

  • Java

  • Kotlin

DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders);
extractor.metadataToExtract(fooMimeType, Foo.class, "foo");
import org.springframework.messaging.rsocket.metadataToExtract

val extractor = DefaultMetadataExtractor(metadataDecoders)
extractor.metadataToExtract<Foo>(fooMimeType, "foo")

复合元数据非常适合组合独立的元数据值。但是，请求者可能不支持复合元数据，或者可能选择不使用它。为此，DefaultMetadataExtractor 可能需要自定义逻辑来将解码后的值映射到输出映射。下面是一个使用 JSON 作为元数据的示例：

  • Java

  • Kotlin

DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders);
extractor.metadataToExtract(
	MimeType.valueOf("application/vnd.myapp.metadata+json"),
	new ParameterizedTypeReference<Map<String,String>>() {},
	(jsonMap, outputMap) -> {
		outputMap.putAll(jsonMap);
	});
import org.springframework.messaging.rsocket.metadataToExtract

val extractor = DefaultMetadataExtractor(metadataDecoders)
extractor.metadataToExtract<Map<String, String>>(MimeType.valueOf("application/vnd.myapp.metadata+json")) { jsonMap, outputMap ->
	outputMap.putAll(jsonMap)
}

通过 RSocketStrategies 配置 MetadataExtractor 时，您可以让 RSocketStrategies.Builder 使用配置的解码器创建提取器，然后简单地使用回调来自定义注册，如下所示：

  • Java

  • Kotlin

RSocketStrategies strategies = RSocketStrategies.builder()
	.metadataExtractorRegistry(registry -> {
		registry.metadataToExtract(fooMimeType, Foo.class, "foo");
		// ...
	})
	.build();
import org.springframework.messaging.rsocket.metadataToExtract

val strategies = RSocketStrategies.builder()
		.metadataExtractorRegistry { registry: MetadataExtractorRegistry ->
			registry.metadataToExtract<Foo>(fooMimeType, "foo")
			// ...
		}
		.build()

RSocket 接口

Spring Framework 允许您将 RSocket 服务定义为带有 @RSocketExchange 方法的 Java 接口。您可以将此类接口传递给 RSocketServiceProxyFactory 以创建代理，该代理通过 RSocketRequester 执行请求。您还可以将接口实现为处理请求的响应器。

首先创建带有 @RSocketExchange 方法的接口

interface RadarService {

	@RSocketExchange("radars")
	Flux<AirportLocation> getRadars(@Payload MapRequest request);

	// more RSocket exchange methods...

}

现在你可以创建一个代理，在方法调用时执行请求

RSocketRequester requester = ... ;
RSocketServiceProxyFactory factory = RSocketServiceProxyFactory.builder(requester).build();

RadarService service = factory.createClient(RadarService.class);

您还可以实现该接口以作为响应器处理请求。请参阅带注解的响应器。

方法参数

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

方法参数 描述

@DestinationVariable

添加一个路由变量，与 @RSocketExchange 注解中的路由一起传递给 RSocketRequester，以便扩展路由中的模板占位符。此变量可以是字符串或任何对象，然后通过 toString() 进行格式化。

@Payload

设置请求的输入有效载荷。这可以是一个具体值，也可以是任何能够通过 ReactiveAdapterRegistry 适配为 Reactive Streams Publisher 的值生产者。除非 required 属性设置为 false，或者参数根据 MethodParameter#isOptional 被标记为可选，否则必须提供有效载荷。

Object，如果后面跟着 MimeType

输入有效载荷中元数据条目的值。这可以是任何 Object，只要下一个参数是元数据条目的 MimeType。该值可以是具体值，也可以是任何可以通过 ReactiveAdapterRegistry 适配为 Reactive Streams Publisher 的单个值生产者。

MimeType

元数据条目的 MimeType。前面的方法参数预计是元数据值。

返回值

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

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

© . This site is unofficial and not affiliated with VMware.