消息网关

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

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

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

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

上述配置中的默认值应用于网关接口上的所有方法。如果未指定回复超时，则调用线程将等待回复 30 秒。请参阅 gateway-no-response。

可以为单个方法覆盖默认值。请参阅 gateway-configuration-annotations。

通常，您无需指定 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。网关从它创建一个桥梁到存储在头中的临时匿名回复通道。

您可能还希望通过拦截器（例如，wiretap）显式提供一个回复通道用于监控或审计。要配置通道拦截器，您需要一个命名通道。

考虑以下示例，它通过添加 @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 定义的替代方案。

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

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

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

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

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

您也可以使用 @Gateway 注解。

另请参阅 gateway-configuration-annotations。

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

网关代理的接口也可以有 default 方法，从 5.3 版本开始，框架将 DefaultMethodInvokingMethodInterceptor 注入到代理中，用于使用 java.lang.invoke.MethodHandle 方法调用 default 方法，而不是代理。JDK 中的接口，例如 java.util.function.Function，仍然可以用于网关代理，但由于 MethodHandles.Lookup 实例化针对 JDK 类的内部 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 属性来支持专用于错误的通道。在以下示例中，一个“转换器”从 Exception 创建一个回复 Message：

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

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

当您使用 @MessagingGateway 注解时（请参阅 <<@MessagingGateway` Annotation,messaging-gateway-annotation>>`），您可以使用 errorChannel 属性。

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

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

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

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

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

作为一种模式，消息网关提供了一种很好的方式来隐藏消息特定代码，同时仍然暴露消息传递系统的全部功能。如 gateway-proxy，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 示例中的 async-gateway 示例。

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

如 gateway-proxy，网关提供了一种通过 POJO 方法调用与消息传递系统交互的便捷方式。然而，通常预期总是返回（即使带有异常）的典型方法调用可能并不总是与消息交换一一对应（例如，回复消息可能不会到达——这相当于方法没有返回）。

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