From 58d3a8c50af5644c0cd60295e8d3a70f6ade7155 Mon Sep 17 00:00:00 2001
From: Savorboard <yangxiaodong1214@126.com>
Date: Sat, 28 Mar 2020 23:38:27 +0800
Subject: [PATCH] update docs

---
 docs/content/user-guide/zh/cap/messaging.md | 40 +++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/content/user-guide/zh/cap/messaging.md b/docs/content/user-guide/zh/cap/messaging.md
index fa54619..ec0987a 100644
--- a/docs/content/user-guide/zh/cap/messaging.md
+++ b/docs/content/user-guide/zh/cap/messaging.md
@@ -6,6 +6,46 @@
 
 你可以阅读 [quick-start](../getting-started/quick-start.md#_3) 来学习如何发送和处理消息。
 
+## 异构系统集成
+
+在 3.0+ 版本中，我们对消息结构进行了重构，我们利用了消息队列中消息协议中的 Header 来传输一些额外信息，以便于在 Body 中我们可以做到不需要修改或包装使用者的原始消息数据格式和内容进行发送。
+
+这样的做法是合理的，它有助于在异构系统中进行更好的集成，相对于以前的版本使用者不需要知道CAP内部使用的消息结构就可以完成集成工作。
+
+现在我们将消息划分为 Header 和 Body 来进行传输。
+
+Body 中的数据为用户发送的原始消息内容，也就是调用 Publish 方法发送的内容，我们不进行任何包装仅仅是序列化后传递到消息队列。
+
+在 Header 中，我们需要传递一些额外信息以便于CAP在收到消息时能够提取到关键特征进行操作。
+
+以下是在异构系统中，需要在发消息的时候向消息的Header 中写入的内容：
+
+ 键 | 类型 | 说明
+-- | --| --
+cap-msg-id |  string | 消息Id， 由雪花算法生成，也可以是 guid
+cap-msg-name | string | 消息名称，即 Topic 名字
+cap-msg-type | string | 消息的类型, 即 typeof(T).FullName (非必须)
+cap-senttime | stringg | 发送的时间 (非必须)
+
+以 Java 系统发送 RabbitMQ 为例：
+
+```java
+
+Map<String, Object> headers = new HashMap<String, Object>();
+headers.put("cap-msg-id",  UUID.randomUUID().toString());
+headers.put("cap-msg-name", routingKey);
+
+channel.basicPublish(exchangeName, routingKey,
+             new AMQP.BasicProperties.Builder()
+               .headers(headers)
+               .build(),
+               messageBodyBytes);
+// messageBodyBytes = "发送的json".getBytes(Charset.forName("UTF-8"))
+// 注意 messageBody 默认为 json 的 byte[]，如果采用其他系列化，需要在CAP侧自定义反序列化器
+
+```
+
+
 ## 消息调度
 
 CAP 接收到消息之后会将消息发送到 Transport, 由 Transport 进行运输。