HTTP 参考

概述

DTM 可以通过HTTP协议交互。因为事务本身具有特殊性,它和普通的api调用只区分成功和失败不同,DTM的结果状态详情,请参考接口协议

接口主要分为三类: AP调用TM的接口、AP调用RM的接口、TM调用RM的接口。本文主要讲解AP调用TM的接口,其他两类接口参见dtm 架构

AP调用TM的接口

这部分接口的路径前缀为/api/dtmsvr。例如后面介绍的prepare,实际路径为/api/dtmsvr/prepare

这部分接口如果对事务状态进行变更,则dtm会对事务状态做相关的校验,有可能校验失败,而返回错误。以一个实际的例子说明:

如果调用prepare时,这个事务状态已经是failed,那么dtm将返回错误码409,错误内容:

  1. {
  2. "dtm_result":"FAILURE",
  3. "message":"current status 'failed', cannot prepare"
  4. }

每个接口的详细说明如下:

newGid 获取Gid

此接口用于获取gid。dtm的gid生成采用ip+snowflake。如果发生短时间内ip重用的情况,有极低概率发生gid重复情况。

因为几乎每个公司都会有自己的唯一id生成基础设置,建议在dtm中使用的gid,采用自己公司内部的唯一id生成算法。

接口名称请求方法请求格式适用事务
newGidGET--

请求示例

  1. curl 'localhost:36789/api/dtmsvr/newGid'

响应示例

  1. {
  2. "dtm_result":"SUCCESS",
  3. "gid":"c0a8038b_4nxAcyxSX8N"
  4. }

prepare 准备事务

此接口用于准备事务,正常情况下,后续将提交事务。

接口名称请求方法请求格式适用事务
preparePOSTJSONMSG, TCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid": "xxx",
  5. "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2. "dtm_result":"SUCCESS"
  3. }

MSG 的prepare请求还会携带分支信息

MSG的prepare示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid":"TestMsgTimeoutSuccess",
  5. "trans_type":"msg",
  6. "steps":[
  7. {
  8. "action":"http://localhost:8081/api/busi/TransOut"
  9. },
  10. {
  11. "action":"http://localhost:8081/api/busi/TransIn"
  12. }
  13. ],
  14. "payloads":[
  15. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  16. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  17. ],
  18. "query_prepared":"http://localhost:8081/api/busi/CanSubmit"
  19. }'
  • steps 指定整个事务会分成多个步骤,每个步骤的正向操作url为action
  • payloads 表示每个步骤中进行http请求时的body
  • query_prepared 指定事务消息超时后进行查询的url

submit 提交事务

此接口用于提交全局事务

接口名称请求方法请求格式适用事务
submitPOSTJSONMSG, SAGA, TCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid": "xxx",
  5. "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2. "dtm_result":"SUCCESS"
  3. }

其中MSG和SAGA的submit还会携带分支信息

MSG的submit示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid":"TestMsgNormal",
  5. "trans_type":"msg",
  6. "steps":[
  7. {
  8. "action":"http://localhost:8081/api/busi/TransOut"
  9. },
  10. {
  11. "action":"http://localhost:8081/api/busi/TransIn"
  12. }
  13. ],
  14. "payloads":[
  15. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  16. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  17. ]
  18. }'

详细字段含义见上述MSG的prepare示例

SAGA的submit示例

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/submit' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid":"TestSagaNormal",
  5. "trans_type":"saga",
  6. "steps":[
  7. {
  8. "action":"http://localhost:8081/api/busi/TransOut",
  9. "compensate":"http://localhost:8081/api/busi/TransOutRevert"
  10. },
  11. {
  12. "action":"http://localhost:8081/api/busi/TransIn",
  13. "compensate":"http://localhost:8081/api/busi/TransInRevert"
  14. }
  15. ],
  16. "payloads":[
  17. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}",
  18. "{\"amount\":30,\"transInResult\":\"SUCCESS\",\"transOutResult\":\"SUCCESS\"}"
  19. ]
  20. }'
  • steps 指定整个事务会分成多个步骤,每个步骤的正向操作url为action,补偿操作url为compensate
  • payloads 每个步骤http请求的body

abort 回滚事务

此接口用于回滚全局事务

接口名称请求方法请求格式适用事务
abortPOSTJSONTCC, XA

请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/abort' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid": "xxx",
  5. "trans_type": "tcc"
  6. }'

响应示例

  1. {
  2. "dtm_result":"SUCCESS"
  3. }

registerBranch

此接口用于TCC, XA事务模式中,注册事务分支

接口名称请求方法请求格式适用事务
registerBranchPOSTJSONXA TCC

注册XA分支请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/registerBranch' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "branch_id":"0101",
  5. "gid":"c0a8038b_4nxEEB1M7K3",
  6. "trans_type":"xa",
  7. "url":"http://localhost:8081/api/busi/xa"
  8. }'
  • url: xa事务模式最后进行commit/rollback的服务地址

注册TCC分支请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/registerTccBranch' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "branch_id":"01",
  5. "cancel":"http://localhost:8081/api/busi/TransOutRevert",
  6. "confirm":"http://localhost:8081/api/busi/TransOutConfirm",
  7. "data":"{\"amount\":30,\"transInResult\":\"\",\"transOutResult\":\"\"}",
  8. "gid":"c0a8038b_4nxEEGy7W5h",
  9. "trans_type":"tcc"
  10. }'
  • cancel:指定cancel操作的url
  • confirm:指定confirm操作的url
  • data:调用cancel/confirm时需要传递的body

响应示例

  1. {
  2. "dtm_result":"SUCCESS"
  3. }

query 查询事务

此接口用于查询指定gid的事务。

接口名称请求方法请求格式适用事务
queryGET--

请求示例

  1. curl 'localhost:36789/api/dtmsvr/query?gid=xxx'

成功响应示例

  1. {
  2. "branches":[
  3. ],
  4. "transaction":{
  5. "ID":69,
  6. "CreateTime":"2021-10-25T08:51:27+08:00",
  7. "UpdateTime":"2021-10-25T08:51:39+08:00",
  8. "gid":"xxx",
  9. "trans_type":"tcc",
  10. "data":"",
  11. "status":"failed",
  12. "query_prepared":"",
  13. "protocol":"http",
  14. "CommitTime":null,
  15. "FinishTime":null,
  16. "RollbackTime":"2021-10-25T08:51:39+08:00",
  17. "Options":"{}",
  18. "NextCronInterval":10,
  19. "NextCronTime":"2021-10-25T08:51:49+08:00"
  20. }
  21. }

未找到gid的响应示例

  1. {
  2. "branches":[
  3. ],
  4. "transaction":null
  5. }

all 批量查询事务

此接口用于批量查询事务。dtm将返回id小于last_id,按照id从大到小排序的100条数据

接口名称请求方法请求格式适用事务
allGET--

请求示例

  1. curl 'localhost:36789/api/dtmsvr/all?last_id='

参数last_id: 上一次请求返回数据的最小id。

成功响应示例

  1. {
  2. "transactions":[
  3. {
  4. "ID":69,
  5. "CreateTime":"2021-10-25T08:51:27+08:00",
  6. "UpdateTime":"2021-10-25T08:51:39+08:00",
  7. "gid":"xxx",
  8. "trans_type":"tcc",
  9. "data":"",
  10. "status":"failed",
  11. "query_prepared":"",
  12. "protocol":"http",
  13. "CommitTime":null,
  14. "FinishTime":null,
  15. "RollbackTime":"2021-10-25T08:51:39+08:00",
  16. "Options":"{}",
  17. "NextCronInterval":10,
  18. "NextCronTime":"2021-10-25T08:51:49+08:00"
  19. }
  20. ]
  21. }

空响应示例

  1. {
  2. "transactions":[
  3. ]
  4. }

事务选项

事务支持以下选项,具体含义参加事务选项文档

  • wait_result: 等待事务结果
  • retry_interval: 重试间隔
  • timeout_to_fail: 超时失败时间
  • branch_headers: 自定义header

这些事务选项可以在prepare/submit请求中,发送给TM,请求示例

  1. curl --location --request POST 'localhost:36789/api/dtmsvr/prepare' \
  2. --header 'Content-Type: application/json' \
  3. --data-raw '{
  4. "gid": "xxx",
  5. "trans_type": "tcc",
  6. "wait_result": true,
  7. "retry_interval": 15,
  8. "branch_headers":{"test_header":"test"},
  9. "timeout_to_fail": 60
  10. }'

响应示例

  1. {
  2. "dtm_result":"SUCCESS"
  3. }