消息网关

如前所述，不依赖 Spring Integration API（包括网关类）会很好。因此，Spring Integration 提供了 GatewayProxyFactoryBean，它为任何接口生成一个代理，并在内部调用下面所示的网关方法。通过使用依赖注入，你可以将接口暴露给你的业务方法。

以下示例展示了一个可用于与 Spring Integration 交互的接口

还提供了命名空间支持。它允许你将接口配置为服务，如下例所示

通过定义此配置，cafeService 现在可以注入到其他 bean 中，并且调用 Cafe 接口的代理实例上的方法的代码无需了解 Spring Integration API。请参阅“示例”附录，了解使用 gateway 元素的示例（在 Cafe 演示中）。

前面配置中的默认值应用于网关接口上的所有方法。如果未指定回复超时，则调用线程将等待回复 30 秒。请参阅没有回复到达时的网关行为。

可以为单个方法覆盖默认值。请参阅使用注解和 XML 的网关配置。

通常，你不需要指定 default-reply-channel，因为网关会自动创建一个临时的匿名回复通道，并在其中侦听回复。但是，某些情况下你可能需要定义一个 default-reply-channel（或适配器网关（如 HTTP、JMS 等）的 reply-channel）。

为了一些背景知识，我们简要讨论一下网关的一些内部工作原理。网关创建一个临时点对点回复通道。它是匿名的，并以名称 replyChannel 添加到消息头中。当提供显式的 default-reply-channel（远程适配器网关的 reply-channel）时，你可以指向一个发布-订阅通道，之所以这样命名是因为你可以向其添加多个订阅者。在内部，Spring Integration 在临时 replyChannel 和显式定义的 default-reply-channel 之间创建一个桥接。

假设你希望你的回复不仅发送到网关，还发送到其他一些消费者。在这种情况下，你需要两件事

网关使用的默认策略不满足这些需求，因为添加到头部中的回复通道是匿名的点对点通道。这意味着没有其他订阅者可以获得它的句柄，而且即使可以，该通道也具有点对点行为，只有一个订阅者会收到消息。通过定义 default-reply-channel，你可以指向你选择的通道。在这种情况下，它是一个 publish-subscribe-channel。网关从它创建一个桥接到存储在头部中的临时匿名回复通道。

你可能还希望通过拦截器（例如，监听器）显式提供回复通道以进行监视或审计。要配置通道拦截器，你需要一个命名通道。

考虑以下示例，它通过添加 @Gateway 注解扩展了前面的 Cafe 接口示例

@Header 注解允许你添加被解释为消息头的值，如下例所示

如果你喜欢使用 XML 方法来配置网关方法，你可以将 method 元素添加到网关配置中，如下例所示

你还可以使用 XML 为每个方法调用提供单独的头部。如果需要设置的头部本质上是静态的，并且你不想通过使用 @Header 注解将它们嵌入到网关的方法签名中，这会很有用。例如，在贷款经纪人示例中，我们希望根据发起的请求类型（单引号或所有引号）影响贷款报价的聚合方式。通过评估调用哪个网关方法来确定请求类型，尽管可能，但会违反关注点分离范例（该方法是一个 Java 工件）。但是，在消息架构中，在消息头部中表达你的意图（元信息）是很自然的。以下示例展示了如何为两个方法添加不同的消息头部

在前面的例子中，'RESPONSE_TYPE' 头部的不同值是根据网关方法设置的。

使用上一节中的配置技术可以控制方法参数如何映射到消息元素（有效载荷和头部）。当不使用显式配置时，将使用某些约定来执行映射。在某些情况下，这些约定无法确定哪个参数是有效载荷，哪个应该映射到头部。考虑以下示例

在第一种情况下，约定是将第一个参数映射到有效载荷（只要它不是 Map），第二个参数的内容成为头部。

在第二种情况（或者当参数 thing1 的参数是 Map 时的第一种情况）下，框架无法确定哪个参数应该是有效载荷。因此，映射失败。这通常可以通过使用 payload-expression、@Payload 注解或 @Headers 注解来解决。

或者（以及当约定失效时），你可以承担将方法调用映射到消息的全部责任。为此，请实现一个 MethodArgsMessageMapper，并通过使用 mapper 属性将其提供给 <gateway/>。映射器映射一个 MethodArgsHolder，它是一个简单的类，封装了 java.reflect.Method 实例和包含参数的 Object[]。当提供自定义映射器时，网关上不允许使用 default-payload-expression 属性和 <default-header/> 元素。同样，任何 <method/> 元素上都不允许使用 payload-expression 属性和 <header/> 元素。

从 4.0 版本开始，网关服务接口可以使用 @MessagingGateway 注解进行标记，而无需定义 <gateway /> xml 元素进行配置。以下两组示例比较了配置同一网关的两种方法

除了 @MessagingGateway 注解之外，你还可以使用 @Profile 注解标记服务接口，以避免在未激活该配置文件时创建 bean。

从 6.0 版本开始，带有 @MessagingGateway 的接口也可以用 @Primary 注解标记，以实现其相应的配置逻辑，这与任何 Spring @Component 定义都可能实现。

从 6.0 版本开始，@MessagingGateway 接口可以在标准的 Spring @Import 配置中使用。这可以作为 @IntegrationComponentScan 或手动 AnnotationGatewayProxyFactoryBean bean 定义的替代方案。

自 6.0 版本以来，@MessagingGateway 使用 @MessageEndpoint 进行元注解，并且 name() 属性实际上是 @Component.value() 的别名。这样，网关代理的 bean 名称生成策略与扫描和导入组件的标准 Spring 注解配置保持一致。默认的 AnnotationBeanNameGenerator 可以通过 AnnotationConfigUtils.CONFIGURATION_BEAN_NAME_GENERATOR 或作为 @IntegrationComponentScan.nameGenerator() 属性进行全局覆盖。

当调用网关接口上没有任何参数的方法时，默认行为是从 PollableChannel 接收 Message。

但是，有时你可能希望触发无参数方法，以便与不需要用户提供参数的其他下游组件进行交互，例如触发无参数 SQL 调用或存储过程。

要实现发送和接收语义，你必须提供一个有效载荷。生成有效载荷不需要接口上的方法参数。你可以使用 @Payload 注解或 XML 中 method 元素上的 payload-expression 属性。以下列表包含一些有效载荷的示例

以下示例展示了如何使用 @Payload 注解

你也可以使用 @Gateway 注解。

另请参阅使用注解和 XML 的网关配置。

如果方法没有参数也没有返回值，但包含有效载荷表达式，则将其视为仅发送操作。

网关代理的接口也可以有 default 方法，从 5.3 版本开始，框架会将 DefaultMethodInvokingMethodInterceptor 注入到代理中，以便使用 java.lang.invoke.MethodHandle 方法调用 default 方法，而不是代理。JDK 中的接口，例如 java.util.function.Function，仍然可以用于网关代理，但由于 JDK 类的 MethodHandles.Lookup 实例化内部 Java 安全原因，它们的 default 方法无法调用。这些方法也可以被代理（失去其实现逻辑，同时恢复以前的网关代理行为），方法是在方法上使用显式 @Gateway 注解，或者在 @MessagingGateway 注解或 <gateway> XML 组件上使用 proxyDefaultMethods。

网关调用可能导致错误。默认情况下，下游发生的任何错误都会在网关方法调用时“原样”重新抛出。例如，考虑以下简单流程

如果服务激活器调用的服务抛出 MyException（例如），框架会将其包装在 MessagingException 中，并将传递给服务激活器的消息附加到 failedMessage 属性中。因此，框架执行的任何日志记录都具有完整的故障上下文。默认情况下，当网关捕获异常时，MyException 会被解包并抛给调用者。你可以在网关方法声明上配置 throws 子句，以匹配原因链中的特定异常类型。例如，如果你想捕获一个带有所有消息传递信息（下游错误原因）的完整 MessagingException，你的网关方法应该类似于以下内容

由于我们鼓励 POJO 编程，你可能不想让调用者接触消息传递基础设施。

如果你的网关方法没有 throws 子句，网关会遍历原因树，查找不是 MessagingException 的 RuntimeException。如果找不到，框架会抛出 MessagingException。如果前面讨论的 MyException 的原因是 SomeOtherException，并且你的方法 throws SomeOtherException，则网关会进一步解包并将其抛给调用者。

当声明的网关没有 service-interface 时，将使用内部框架接口 RequestReplyExchanger。

考虑以下示例

在 5.0 版本之前，此 exchange 方法没有 throws 子句，因此异常会被解包。如果你使用此接口并希望恢复以前的解包行为，请改用自定义 service-interface 或自行访问 MessagingException 的 cause。

但是，你可能希望记录错误而不是传播它，或者你可能希望将异常视为有效回复（通过将其映射到符合调用者理解的某些“错误消息”契约的消息）。为了实现这一点，网关通过包含对 error-channel 属性的支持来提供对专门用于错误的 message channel 的支持。在以下示例中，一个“转换器”从 Exception 创建一个回复 Message

exceptionTransformer 可以是一个简单的 POJO，它知道如何创建预期的错误响应对象。这成为发送回调用者的有效载荷。如果需要，你可以在这样的“错误流”中做更多复杂的事情。它可能涉及路由器（包括 Spring Integration 的 ErrorMessageExceptionTypeRouter）、过滤器等等。但是，大多数情况下，一个简单的“转换器”就足够了。

或者，你可能只想记录异常（或将其异步发送到某个地方）。如果你提供单向流，则不会向调用者发送任何内容。如果你想完全抑制异常，你可以提供对全局 nullChannel 的引用（本质上是 /dev/null 方法）。最后，如上所述，如果未定义 error-channel，则异常照常传播。

当您使用 @MessagingGateway 注解时（参见 @MessagingGateway` 注解），您可以使用 `errorChannel 属性。

从 5.0 版本开始，当你使用返回类型为 void 的网关方法（单向流）时，error-channel 引用（如果提供）会填充到每条发送消息的标准 errorChannel 头中。此功能允许基于标准 ExecutorChannel 配置（或 QueueChannel）的下游异步流覆盖默认的全局 errorChannel 异常发送行为。以前，你必须使用 @GatewayHeader 注解或 <header> 元素手动指定 errorChannel 头。error-channel 属性对于异步流的 void 方法会被忽略。相反，错误消息会发送到默认的 errorChannel。

网关有两个超时属性：requestTimeout 和 replyTimeout。请求超时仅在通道可以阻塞时适用，例如已满的受限 QueueChannel。replyTimeout 值是网关等待回复或返回 null 的时间。它默认为无限。

超时可以作为网关上所有方法的默认值（defaultRequestTimeout 和 defaultReplyTimeout）或在 MessagingGateway 接口注解上设置。单个方法可以覆盖这些默认值（在 <method/> 子元素中）或在 @Gateway 注解上设置。

从 5.0 版本开始，超时可以定义为表达式，如下例所示

评估上下文具有 BeanResolver（使用 @someBean 引用其他 bean），并且 #root 对象的 args 数组属性可用。有关此根对象的更多信息，请参阅表达式和“全局”头部。当使用 XML 配置时，超时属性可以是 long 值或 SpEL 表达式，如下例所示

作为一种模式，消息网关提供了一种很好的方式来隐藏消息特定代码，同时仍然暴露消息系统的全部功能。如前所述，GatewayProxyFactoryBean 提供了一种方便的方式来通过服务接口暴露代理，为你提供基于 POJO 的消息系统访问（基于你自己的域中的对象、原语/字符串或其他对象）。但是，当网关通过返回值的简单 POJO 方法暴露时，它意味着对于每个请求消息（在方法调用时生成），必须有一个回复消息（在方法返回时生成）。由于消息系统本质上是异步的，你可能无法始终保证“每个请求始终有回复”的契约。Spring Integration 2.0 引入了对异步网关的支持，它提供了一种方便的方式来启动流，当你可能不知道是否期望回复或回复需要多长时间才能到达时。

为了处理这些类型的场景，Spring Integration 使用 java.util.concurrent.Future 实例来支持异步网关。

从 XML 配置来看，没有什么变化，你仍然以与定义常规网关相同的方式定义异步网关，如下例所示

然而，网关接口（服务接口）略有不同，如下所示

如上例所示，网关方法的返回类型是 Future。当 GatewayProxyFactoryBean 发现网关方法的返回类型是 Future 时，它会立即通过使用 AsyncTaskExecutor 切换到异步模式。这就是区别的程度。对这种方法的调用总是立即返回一个 Future 实例。然后，你可以按照自己的节奏与 Future 交互以获取结果、取消等。此外，与任何其他使用 Future 实例的情况一样，调用 get() 可能会揭示超时、执行异常等。以下示例展示了如何使用从异步网关返回的 Future

有关更详细的示例，请参阅 Spring Integration 示例中的异步网关示例。

此外，从 6.5 版本开始，Java DSL gateway() 操作符完全支持 async(true) 行为。在内部，为 GatewayProxyFactoryBean 提供了 AsyncRequestReplyExchanger 服务接口。由于 AsyncRequestReplyExchanger 契约是 CompletableFuture<Message<?>>，因此整个请求-回复以异步方式执行。此行为很有用，例如，在分发器-聚合器场景中，当必须为每个项调用另一个流时。但是，顺序不重要——只有在所有处理之后它们在聚合器上的分组聚集。

如前所述，网关通过 POJO 方法调用提供了一种与消息系统交互的便捷方式。但是，典型的方法调用（通常期望始终返回（即使发生异常））可能并不总是与消息交换一对一映射（例如，回复消息可能不会到达——这相当于方法不返回）。

本节的其余部分涵盖了各种场景以及如何使网关表现得更可预测。可以配置某些属性以使同步网关行为更可预测，但其中一些属性可能并不总是像你期望的那样工作。其中之一是 reply-timeout（在方法级别或 default-reply-timeout 在网关级别）。我们检查 reply-timeout 属性，看看它在各种场景中如何以及不能如何影响同步网关的行为。我们检查单线程场景（所有下游组件通过直接通道连接）和多线程场景（例如，在下游某个地方你可能有一个可轮询或执行器通道，打破了单线程边界）。