消息网关

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

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

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

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

前述配置中的默认设置适用于网关接口上的所有方法。如果未指定回复超时时间，则调用线程将等待回复 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。网关会从该通道桥接到存储在消息头中的临时匿名回复通道。

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

考虑以下示例，它在之前的 Cafe 接口示例基础上添加了 @Gateway 注解

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

如果你倾向于使用 XML 方法来配置网关方法，你可以在网关配置中添加 method 元素，如下例所示

你还可以使用 XML 为每个方法调用提供独立的头信息。这在你想设置的头是静态的，并且不希望通过使用 @Header 注解将其嵌入到网关的方法签名中时非常有用。例如，在贷款代理示例中，我们想根据启动的请求类型（单个报价或所有报价）来影响贷款报价的聚合方式。通过评估调用了哪个网关方法来确定请求类型，虽然可能，但会违反关注点分离范式（方法是 Java 工件）。然而，在消息处理架构中，在消息头中表达你的意图（元信息）是很自然的。以下示例展示了如何为两个方法添加不同的消息头

在前面的示例中，根据网关的方法为 'RESPONSE_TYPE' 头设置了不同的值。

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

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

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

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

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

除了 @MessagingGateway 注解之外，你还可以使用 @Profile 注解标记服务接口，以便在该 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 子句来匹配 cause 链中特定的异常类型。例如，如果你想捕获包含下游错误原因所有消息信息的整个 MessagingException，你的网关方法应该类似于以下内容

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

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

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

考虑以下示例

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

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

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

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

当你使用 @MessagingGateway 注解时（请参阅@MessagingGateway 注解），你可以使用 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 数组属性可用。有关此 root 对象的更多信息，请参见 表达式与“全局”头部。使用 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 示例中的 async-gateway 示例。

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

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