IBM MQ JMS 客戶端 RHF2 消息頭處理：targetClient 參數完整解析與配置指南

IBM MQ JMS 客戶端 RHF2 消息頭處理指南

對接 IBM MQ 時，JMS 客戶端默認在消息中注入 RHF2 頭（RFH2 - Rules and Formatting Header Version 2），導致非 JMS 消費端（如 C/C++、.NET、主機端）解析失敗。本文詳細解析 targetClient 參數機制，提供 Queue/Topic 兩種場景的配置代碼與驗證方法。

一、RFH2 頭是什麼？為什麼要移除？

• RFH2：IBM MQ 專有消息頭，包含 JMS 標準屬性（JMSDestination、JMSMessageID、JMSCorrelationID、JMSType、JMSXGroupID 等）及用戶自定義屬性；
• 問題：非 JMS 消費端無法識別 RFH2 結構，導致業務數據偏移、解析異常、甚至消息被拒；
• 解決：設置 targetClient=1 告訴 MQ「目標客戶端非 JMS」，發送時自動剝離 RFH2，僅傳遞純業務 Payload（BytesMessage/TextMessage 體）。

二、targetClient 參數取值與行為

三、Queue 場景配置代碼

// 方式一：創建 Queue 時指定（推薦）
String queueName = "DEV.QUEUE.1";
String targetClient = "1";  // 剝離 RFH2
Queue queue = session.createQueue("queue:///" + queueName + "?targetClient=" + targetClient);

// 方式二：使用 JNDI 查找預配置 Queue（運維預先在 MQ 控制台設置 TARGCLNT(1)）
// @Resource(mappedName = "jms/MyQueue") Queue queue;

// 發送消息
MessageProducer producer = session.createProducer(queue);
TextMessage msg = session.createTextMessage("{\"orderId\":1001}");
producer.send(msg);  // 到達隊列時無 RFH2 頭

四、Topic 發布/訂閱場景配置

String topicName = "PRICE.UPDATES";
String targetClient = "1";
Topic topic = session.createTopic("topic:///" + topicName + "?targetClient=" + targetClient);

MessageProducer publisher = session.createProducer(topic);
MapMessage msg = session.createMapMessage();
msg.setString("symbol", "AAPL");
msg.setDouble("price", 150.25);
publisher.send(msg);  // 訂閱端收到純 MapMessage 體

五、Spring JMS 整合配置（生產推薦）

<!-- 連接工廠配置 targetClient -->
<bean id="mqConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
    <property name="hostName" value="${mq.host}"/>
    <property name="port" value="${mq.port}"/>
    <property name="queueManager" value="${mq.qmgr}"/>
    <property name="channel" value="${mq.channel}"/>
    <property name="transportType" value="1"/> <!-- CLIENT 模式 -->
    <property name="targetClient" value="1"/> <!-- 關鍵：全局剝離 RFH2 -->
</bean>

<!-- 或針對單個 Destination 覆蓋 -->
<bean id="orderQueue" class="com.ibm.mq.jms.MQQueue">
    <property name="baseQueueName" value="DEV.ORDER.QUEUE"/>
    <property name="targetClient" value="1"/>
</bean>

六、驗證 RFH2 是否剝離

1. MQ Explorer / runmqsc：DISPLAY QUEUE(DEV.QUEUE.1) TARGCLNT 確認 TARGCLNT(1)；
2. 消費端抓包：使用 amqsbcg (MQ 示例消費程序) 瀏覽消息，查看 Message Descriptor 中 Format 字段：
   • MQFMT_RF_HEADER_2 (RFH2) → 未剝離；
   • MQFMT_STRING / MQFMT_NONE → 已剝離。
3. JMS 代碼檢查：

   Message received = consumer.receive(5000);
   if (received instanceof TextMessage) {
       System.out.println("Body: " + ((TextMessage) received).getText());
       // 檢查是否殘留 JMS_IBM_ 等 RFH2 專有屬性
       Enumeration<String> props = received.getPropertyNames();
       while (props.hasMoreElements()) {
           String k = props.nextElement();
           if (k.startsWith("JMS_IBM_")) System.out.println("⚠️ RFH2 屬性殘留: " + k);
       }
   }

七、常見誤區與避坑

八、最佳實踐總結

1. 全局默認剝離：連接工廠設置 targetClient=1，除非明確雙端均為 JMS；
2. 隊列級別覆蓋：特定業務需保留 RFH2 時，在該 Queue/Topic Bean 覆蓋 targetClient=0；
3. 文檔化約定：接口文檔明確註明「消息體格式：純 JSON/Protobuf，無 RFH2」，避免雙端理解不一致；
4. 自動化測試：CI 流程中包含「發送→消費→斷言無 JMS_IBM_* 屬性」的集成測試。

「RFH2 是 IBM MQ 生態內的『身份證』，出了生態就是『亂碼』。一句 targetClient=1，讓消息輕裝上陣，暢行無阻。」