消息网关

如前所述，最好不依赖于 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() 属性实际上是 @Compnent.value() 的别名。这样，网关代理的 bean 名称生成策略就与扫描和导入组件的标准 Spring 注解配置保持一致。可以通过 AnnotationConfigUtils.CONFIGURATION_BEAN_NAME_GENERATOR 全局覆盖默认的 AnnotationBeanNameGenerator，或者作为 @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 属性来提供对专用于错误的消息通道的支持。在以下示例中，“转换器”从 Exception 创建回复 Message

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

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

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

从 5.0 版本开始，当您使用具有 void 返回类型（单向流）的网关方法时，标准 errorChannel 标头中的每个发送消息都会填充 error-channel 引用（如果提供）。此功能允许基于标准 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数组属性可用。有关此根对象的更多信息，请参阅表达式和“全局”标头。在使用XML配置时，超时属性可以是长整型值或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示例中的async-gateway示例。

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

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