From e01d40b013c63a89527a270c3531c266f1356dd5 Mon Sep 17 00:00:00 2001
From: Chiwency <574300395@qq.com>
Date: Thu, 15 Sep 2022 20:38:50 +0800
Subject: [PATCH] add:msg_topic

---
 docs/guide/e-msg.md  | 28 ++++++++++++++++++++++++++++
 docs/practice/msg.md | 10 ++++++++++
 2 files changed, 38 insertions(+)

diff --git a/docs/guide/e-msg.md b/docs/guide/e-msg.md
index 96ef15e..902d417 100644
--- a/docs/guide/e-msg.md
+++ b/docs/guide/e-msg.md
@@ -65,6 +65,34 @@ app.GET(BusiAPI+"/QueryPreparedB", dtmutil.WrapHandler2(func(c *gin.Context) int
 
 At this point, a complete two-stage message distributed transaction is written.
 
+## Topic message
+
+You can also make the  2-phase message transaction call by topic message.  "topic" has the same semantics which is in message queue.
+
+Firstly we subscribe a topic named `TransIn` for our business api:
+
+> We can also manage topics in dtm's console.
+
+```go
+resp, err := dtmcli.GetRestyClient().R().SetQueryParams(map[string]string{
+		"topic":  "TransIn",
+		"url":    busi.Busi+"/SagaBTransIn",
+		"remark": "trans in api",
+	}).Get(dtmutil.DefaultHTTPServer + "/subscribe")
+```
+
+Then open the 2-phase message transaction and send message to the topic `TransIn`
+
+```go
+		msg := dtmcli.NewMsg(DtmServer, shortuuid.New()).
+			AddTopic("TransIn", &TransReq{ Amount: 30 })
+		err := msg.DoAndSubmitDB(busi.Busi+"/QueryPreparedB", dbGet(), func(tx *sql.Tx) error {
+			return busi.SagaAdjustBalance(tx, busi.TransOutUID, -req.Amount)
+		})
+```
+
+Note that the change of topic needs to take a few seconds to take effect, which depends on the `ConfigUpdateInterval` configuration parameter.
+
 ## Run the example
 If you want to run a successful example in its entirety, the steps are as follows.
 1. run dtm
diff --git a/docs/practice/msg.md b/docs/practice/msg.md
index 40c9047..b748085 100644
--- a/docs/practice/msg.md
+++ b/docs/practice/msg.md
@@ -140,6 +140,16 @@ This problem is completely solved by dtm's 2-phase message solution. dtm's 2-pha
 
 So how do 2-phase message distinguish between in-progress and rolled back messages? The trick lies in the data inserted during the checkback. If the database transaction is still in progress at the time of the checkback, then the insert operation will be blocked by the in-progress transaction, because the insert operation will wait for the row lock held by the transaction. If the insert operation returns normally, then the local transaction in the database, which must have ended.
 
+## Topic message principle
+
+As mentioned in previous article, the 2-phase message can also implement branch transaction call by topic message.
+
+The dtm server maintains a mapping of `topic -> APIs ` and stores it in database. The server reads the mapping information regularly and loads it into memory for cache. 
+
+When dtm  server processes the 2-phase message request which includes topic message, it will use the cached mapping information to find corresponding APIs for each topic, and then call the APIs one by one.
+
+Topic message decouples the distributed transaction caller and external services, which means we don't need to modify caller's code when external services' APIs change, and we can configure APIs dynamically.
+
 ## Common messages
 2-phase messages can replace not only the local message table scheme, but also the normal message scheme. If you call Submit directly, then it is similar to the normal message scheme, but provides a more flexible and simple interface.