訊息閘道器

如前所述，最好不依賴 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 屬性，以瞭解它在各種場景中如何影響和不能影響同步閘道器的行為。我們檢查單執行緒場景（所有下游元件透過直接通道連線）和多執行緒場景（例如，下游某個地方可能有一個可輪詢或執行器通道，打破了單執行緒邊界）。