Messaging Gateways

如前所述，最好不依赖 Spring Integration API，包括网关类。因此，Spring Integration 提供了 GatewayProxyFactoryBean，它为任何接口生成一个代理，并在内部调用下面显示的网关方法。然后，通过使用依赖关系注入，你可以向你的业务方法公开接口。

以下示例显示了可用来与 Spring Integration 交互的接口：

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

在此配置定义下，cafeService 现在可注入到其他 Bean，并且在 Cafe 接口的代理实例上调用方法的代码无需知道 Spring Integration API。有关一个在 Cafe 示例中使用 gateway 元素的示例，请参阅 xref:samples.adoc#samples-impl[“Samples” 附件。

上述配置中的默认值将应用到网关接口上的所有方法。如果没有指定回复超时，则调用线程将等待回复 30 秒。请参见 Gateway Behavior When No response Arrives。

可以针对各个方法覆盖默认值。请参见 Gateway Configuration with Annotations and 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。网关从它到存储在标头中的临时匿名回复通道创建一个桥梁。

您可能还想明确提供一个回复通道，以通过拦截器（例如，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 元素进行配置。以下两组示例对比了为同一个网关配置的两种方法：

你可以使用 @Profile 注释来标记 @MessagingGateway 注释的服务接口，以在非活动状态中避免 bean 创建。

从版本 6.0 开始，带有 @MessagingGateway 的接口还可以使用 @Primary 注释来标记各自的配置逻辑，就像任何 Spring @Component 定义一样。

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

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

在调用网关接口中没有任何参数的方法时，默认行为是接收来自 PollableChannel 的 Message。

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

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

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

你还可以使用 @Gateway 注释。

另请参阅 Gateway Configuration with Annotations and 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 属性的支持。在以下示例中，一个“转换器”从 Exception 创建一个答复 Message：

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

或者，你可能只想记录异常（或异步地将其发送到某个地方）。如果你提供单向流，不会向调用者发送任何内容。如果你想要完全禁止异常，你可以提供对全局 nullChannel 的引用（基本上是 /dev/null 方法）。最后，正如上文所述，如果没有定义 error-channel，则异常会像往常一样传播。

当您使用 @MessagingGateway 注释时（请参见 @MessagingGateway` Annotation), you can use an `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），并且 args 数组属性来自 #root 对象可用。有关此根对象的更多信息，请参阅 xref:gateway.adoc#gateway-expressions[Expressions and “Global” 标题。使用 XML 配置时，超时属性可以是长值或 SpEL 表达式，如下例所示：

作为一种模式，消息传递网关提供了一种很好的方法来隐藏特定于消息传递的代码，同时仍公开消息传递系统的所有功能。正如 described earlier，GatewayProxyFactoryBean 提供了一种便捷的方法，可以通过服务接口公开一个代理，使您能够基于 POJO 访问消息传递系统（基于您自己域、基元/字符串或其他对象中的对象）。但是，当通过返回值的简单 POJO 方法公开网关时，这意味着对于每个请求消息（在调用该方法时生成），都必须有一个响应消息（在该方法返回时生成）。由于消息传递系统本质上是异步的，因此您可能无法始终保证合约中的 “for each request, there will always be a reply”。Spring Integration 2.0 引入了对异步网关的支持，这提供了一种便捷的方法来启动流程，在该流程中您可能不知道是否预期收到回复或收到回复需要多长时间。

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

在 XML 配置中，没有任何更改，你仍然像定义常规网关一样定义异步网关，如下例所示：

但是，网关接口（一个服务接口）有点不同，如下所示：

如前例所示，网关方法的返回类型是 Future。当 GatewayProxyFactoryBean 看到网关方法的返回类型是 Future 时，它会立即通过使用 AsyncTaskExecutor 切换到异步模式。这就是不同之处的全部。对这样的方法的调用总是立即返回一个 Future 实例。然后，你可以按照自己的步调与 Future 进行交互以获取结果、取消等等。而且，与任何其他使用 Future 实例的情况一样，调用 get() 可能会显示超时、执行异常等。以下示例展示了如何使用从异步网关返回的 Future：

有关更详细的示例，请参阅 Spring 集成示例中的 async-gateway 示例。

与 explained earlier 相同，该网关提供了一种通过 POJO 方法调用与消息传递系统进行交互的便捷方式。但是，通常预期始终返回的典型方法调用（即使出现异常）可能并不总是映射为一对一的消息交换（例如，回复消息可能无法到达，相当于方法未返回）。

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