add protocol

README.md

@@ -4,7 +4,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/yedf/dtm)](https://goreportcard.com/report/github.com/yedf/dtm)
 [![Go Reference](https://pkg.go.dev/badge/github.com/yedf/dtm.svg)](https://pkg.go.dev/github.com/yedf/dtm)
 
-[English](https://github.com/yedf/dtm/blob/master/README-en.md)
+[English](https://github.com/yedf/dtm/blob/main/README-en.md)
 
 # GO语言分布式事务管理服务
 DTM是首款golang的开源分布式事务管理器，优雅的解决了幂等、空补偿、悬挂等分布式事务难题。在微服务架构中，提供了高性能和简单易用的分布式事务解决方案。
@@ -36,6 +36,7 @@ DTM是首款golang的开源分布式事务管理器，优雅的解决了幂等
     - [TCC事务模式](https://zhuanlan.zhihu.com/p/388357329)
     - 可靠消息事务模式
   * [子事务屏障](https://zhuanlan.zhihu.com/p/388444465)
+  * [通信协议](https://github.com/yedf/dtm/blob/main/protocol.md)
   * FAQ
   * 部署指南
 

protocol.md

@@ -0,0 +1,37 @@
+## dtm通信协议
+
+### 角色
+一个dtm事务，有三个角色参与：
+
+- RM-资源管理器：管理系统资源。数据库就是一种资源管理器，资源管理还应该具有管理事务提交和回滚的能力。
+  * RM管理分布式事务中的子事务，负责相关数据的修改、提交、回滚、补偿等操作。通常对应一个微服务。
+- TM-事务管理器：事务管理器是分布式事务的核心管理者。事务管理器与每个资源管理器RM进行通信，协调并完成事务的处理。
+  * 每个全局事务在TM注册，每个子事务也注册到TM。TM会协调所有的RM，将同一个全局事务的不同子事务，全部提交或全部回滚。
+- AP-应用程序：应用程序，按照业务规则调用RM接口来完成对业务模型数据的变更。
+  * AP会注册全局事务，按照业务规则，注册子事务，调用RM接口。通常对应一个微服务。
+
+在子事务嵌套的情况下，一个微服务，同时会扮演RM和AP的角色，如图
+
+<img src="https://pic1.zhimg.com/80/v2-b6645d3aedefe42ffe8395faa1a94224_1440w.png" alt="示意图">
+
+### 协议
+
+目前dtm只支持了http协议。由于分布式事务涉及多个角色协作，某些参与者可能出现暂时不可用，需要重试；某些参与者明确告知失败，需要进行回滚。
+下面对各种情况进行分类说明，定义各类情况的返回值。设计主要借鉴了微信/支付宝订单成功回调的接口，他们也是通过返回SUCCESS来表示成功，不再进行重试。
+
+上面的图中，主要有以下几类接口：
+
+AP调用TM的接口，主要为全局事务注册、提交，子事务注册等：
+  - 成功: {dtm_result:"SUCCESS"}
+  - 失败: {dtm_result:"FAILURE} // 表示这个请求状态不对，例如已经走fail的全局事务不允许再注册分支
+  - 其他错误则需要重试
+
+TM调用RM的接口，主要为二阶段的提交、回滚，以及saga的各分支
+  - 成功: {dtm_result: "SUCCESS"} // 表示这个接口调用成功，正常进行下一步操作
+  - 失败: {dtm_result: "FAILURE"} // 表示这个接口调用失败，业务需要进行回滚。例如saga中的动作如果返回FAILURE，则整个saga事务失败回滚
+  - 其他则需要重试 // 结果不确定，需要重试
+
+AP调用RM的接口，跟业务相关，建议的接口形式，非必须
+  - 成功: {dtm_result: "SUCCESS"}，表示这个接口调用成功，正常进行下一步操作。返回的结果还可以包含其他业务数据。
+  - 失败: {dtm_result: "FAILURE"}，表示这个接口调用失败，业务需要进行回滚。例如tcc中的Try动作如果返回FAILURE，则整个tcc事务失败回滚
+  - 其他则需要重试 // 结果不确定，需要重试