Hyperf 分佈式事務實戰：基於 DTM 的 TCC、Saga、XA 與二階段消息完整指南-北京尧图网络

后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载本篇技術指南以 Hyperf 團隊開發並維護的 DTM 分佈式事務客戶端組件dtm/dtm-client為主線系統講解其在 Hyperf 框架中的安裝、配置與實戰用法涵蓋 TCC、Saga、XA 及二階段消息等主流分佈式事務模式。讀者閱讀完畢後將掌握如何在 Hyperf 微服務架構中接入 DTM-Server利用子事務屏障技術解決冪等、空補償、懸掛等分佈式事務難題並能直接複用文中提供的三種模式完整代碼示例。生態組件總覽dtm-client 與 seata-phpHyperf 團隊在分佈式事務領域維護了兩個 PHP 客戶端組件分別對接當今兩大主流分佈式事務管理器dtm-client由 Hyperf 團隊開發並維護的 DTM 分佈式事務客戶端組件配合 DTM-Server 可以實現分佈式事務的管理穩定可用於生產環境。該組件亦被收錄於官方生態組件列表見 docs/zh-hk/awesome-components.md 中「分佈式事務」一節。seata/seata-php由 Hyperf 團隊開發並貢獻給 Seata 開源社區的 Seata PHP 客戶端組件配合 Seata-Server 可以實現分佈式事務的管理。需要特別注意的是該組件目前仍在開發迭代中尚未能用於生產環境官方期望社區共同參與進來加速孵化。本文重點圍繞已可用於生產的dtm/dtm-client展開。關於 DTMDTMDistributed Transaction Manager是一款基於 Go 語言實現的開源分佈式事務管理器提供跨語言、跨存儲引擎組合事務的強大功能。它優雅地解決了**冪等Idempotency、空補償Null Compensation、懸掛Suspension**等分佈式事務經典難題並提供了簡單易用、高性能、易水平擴展的分佈式事務解決方案。亮點極易上手零配置啟動服務提供非常簡單的 HTTP 接口極大降低上手分佈式事務的難度。跨語言適合多語言棧的公司使用方便 Go、Python、PHP、NodeJs、Ruby、C# 等各類語言使用。使用簡單開發者不再擔心懸掛、空補償、冪等等各類問題DTM 首創的**子事務屏障Branch Barrier**技術會代為處理。易部署、易擴展僅依賴 MySQL/Redis部署簡單易集羣化易水平擴展。多種分佈式事務協議支持TCC、SAGA、XA、二階段消息一站式解決多種分佈式事務問題。DTM 與 Seata 對比在非 Java 語言下暫未看到除 DTM 之外的成熟的分佈式事務管理器因此官方文檔將 DTM 和 Java 生態中最成熟的開源項目 Seata 做了對比特性DTMSEATA備註支持語言Go、C#、Java、Python、PHP...Java、GoDTM 可輕鬆接入一門新語言存儲引擎支持數據庫、Redis、Mongo 等數據庫—異常處理子事務屏障自動處理手動處理DTM 解決了冪等、懸掛、空補償SAGA 事務極簡易用複雜狀態機—二階段消息✓✗最簡消息最終一致性架構TCC 事務✓✓—XA 事務✓✓—AT 事務建議使用 XA✓AT 與 XA 類似但有髒回滾單服務多數據源✓✗—通信協議HTTP、gRPCDubbo 等協議DTM 對雲原生更加友好注上表為文檔中的原始對比結論。DTM 於 2021-06-04 發佈 0.1 版本後發展迅速。從對比特性來看如果考慮多語言支持、多存儲引擎支持DTM 是值得優先考慮的選擇。安裝 dtm-client通過 Composer 可以非常方便地安裝 dtm-clientcomposer require dtm/dtm-client⚠️ 使用時別忘了啟動 DTM Server 哦dtm-client 僅是客戶端真正的全局事務調度由獨立的 DTM-Server 進程完成。配置配置文件如果您是在Hyperf 框架中使用在安裝組件後可通過下面的vendor:publish命令一鍵發佈配置文件至./config/autoload/dtm.phpphp bin/hyperf.php vendor:publish dtm/dtm-client如果您是在非 Hyperf 框架中使用可複製./vendor/dtm/dtm-client/publish/dtm.php文件到對應的配置目錄中。完整的配置文件內容如下註釋已逐項說明含義use DtmClient\Constants\Protocol; use DtmClient\Constants\DbType; return [ // 客戶端與 DTM Server 通訊的協議支持 Protocol::HTTP 和 Protocol::GRPC 兩種 protocol Protocol::HTTP, // DTM Server 的地址 server 127.0.0.1, // DTM Server 的端口 port [ http 36789, grpc 36790, ], // 子事務屏障配置 barrier [ // DB 模式下的子事務屏障配置 db [ type DbType::MySQL ], // Redis 模式下的子事務屏障配置 redis [ // 子事務屏障記錄的超時時間 expire_seconds 7 * 86400, ], // 非 Hyperf 框架下應用子事務屏障的類 apply [], ], // HTTP 協議下 Guzzle 客戶端的通用配置 guzzle [ options [], ], ];對關鍵配置項的理解protocol決定客戶端與 DTM Server 之間的通訊方式。Protocol::HTTP走 REST 風格接口默認端口 36789Protocol::GRPC走 gRPC 通道默認端口 36790。選擇哪種協議需與實際部署的 DTM-Server 對應端口保持一致。server/portDTM Server 的網絡位置。默認本地127.0.0.1生產環境應改為實際部署地址並保證端口可達。barrier.db.type子事務屏障在數據庫模式下使用的存儲類型默認DbType::MySQL也可根據實際情況選擇其他支持的數據庫類型。barrier.redis.expire_secondsRedis 模式下子事務屏障記錄的超時時間默認 7 天7 * 86400秒用於控制屏障記錄在 Redis 中的存活時長。barrier.apply非 Hyperf 框架下需要自行指定應用子事務屏障的類Hyperf 環境下由框架自動注入通常無需配置。guzzle.optionsHTTP 協議下 Guzzle 客戶端的通用配置可根據需要傳入超時、代理等 Guzzle 支持的任何選項。配置中間件在使用之前需要配置DtmClient\Middleware\DtmMiddleware中間件作為 Server 的全局中間件。該中間件遵循 PSR-15 規範可適用於各個支持該規範的框架。在 Hyperf 中中間件配置可參考 Hyperf 文檔 - 中間件一章中間件的完整概念可進一步參閱 docs/zh-hk/middleware 目錄。在非 Hyperf 框架中只要框架兼容 PSR-15 中間件規範即可直接註冊使用。該中間件負責在請求進入業務邏輯前後處理與 DTM-Server 相關的上下文例如全局事務標識的傳遞是子事務屏障正常工作的前置條件缺少該中間件將導致屏障與回調邏輯無法正確關聯。使用dtm-client 的使用非常簡單。官方提供了一個示例項目 dtm-php/dtm-sample 來幫助開發者更好地理解和調試。在使用該組件之前官方也強烈建議先閱讀 DTM 官方文檔以做更詳細的瞭解。下面依次介紹四種模式中已支持的三種核心模式TCC、Saga、XA的完整用法二階段消息模式在文末概述。TCC 模式TCC 模式是一種非常流行的柔性事務解決方案由Try-Confirm-Cancel三個單詞的首字母縮寫組成最早由 Pat Helland 於 2007 年發表的論文《Life beyond Distributed Transactions: an Apostates Opinion》中提出。TCC 的 3 個階段Try 階段嘗試執行完成所有業務檢查一致性預留必須的業務資源準隔離性。Confirm 階段如果所有分支的 Try 都成功了則進入 Confirm 階段。Confirm 真正執行業務不作任何業務檢查只使用 Try 階段預留的業務資源。Cancel 階段如果所有分支的 Try 有一個失敗了則進入 Cancel 階段。Cancel 釋放 Try 階段預留的業務資源。以銀行跨行轉賬為例轉出TransOut和轉入TransIn分別位於不同的微服務中一個成功完成的 TCC 事務典型時序為Try(TransOut) → Try(TransIn) → Confirm(TransOut) → Confirm(TransIn)若 Try 階段任一分支失敗則改為執行各已 Try 分支的 Cancel 進行資源釋放。代碼示例以下展示在 Hyperf 框架中的使用方法其它框架類似?php namespace App\Controller; use DtmClient\TCC; use DtmClient\TransContext; use Hyperf\Di\Annotation\Inject; use Hyperf\HttpServer\Annotation\Controller; use Hyperf\HttpServer\Annotation\GetMapping; use Throwable; #[Controller(prefix: /tcc)] class TccController { protected string $serviceUri http://127.0.0.1:9501; #[Inject] protected TCC $tcc; #[GetMapping(path: successCase)] public function successCase() { try { $this-tcc-globalTransaction(function (TCC $tcc) { // 創建子事務 A 的調用數據 $tcc-callBranch( // 調用 Try 方法的參數 [amount 30], // Try 方法的 URL $this-serviceUri . /tcc/transA/try, // Confirm 方法的 URL $this-serviceUri . /tcc/transA/confirm, // Cancel 方法的 URL $this-serviceUri . /tcc/transA/cancel ); // 創建子事務 B 的調用數據以此類推 $tcc-callBranch( [amount 30], $this-serviceUri . /tcc/transB/try, $this-serviceUri . /tcc/transB/confirm, $this-serviceUri . /tcc/transB/cancel ); }); } catch (Throwable $e) { var_dump($e-getMessage(), $e-getTraceAsString()); } // 通過 TransContext::getGid() 獲得全局事務ID 並返回 return TransContext::getGid(); } }代碼要點說明globalTransaction(callable)開啟一個 TCC 全局事務回調內部的所有callBranch都會被登記到同一個全局事務中。callBranch(parameters, tryUrl, confirmUrl, cancelUrl)註冊一個分支事務四個參數分別為 Try 調用參數、Try/Confirm/Cancel 三個階段的 URL。每個分支需要在對應的微服務中提供這三個端點。TransContext::getGid()全局事務 ID。事務完成後通過它獲取本次全局事務的唯一標識用於日後查詢或與業務數據關聯。分支端點如/tcc/transA/try內部需要配合DtmMiddleware與子事務屏障來保證 Try/Confirm/Cancel 在重試、重複請求下的冪等性。Saga 模式Saga 模式是分佈式事務領域最有名氣的解決方案之一也非常流行於各大系統中最初出現於 1987 年由 Hector Garcia-Molina Kenneth Salem 發表的論文《SAGAS》中。Saga 是一種最終一致性事務也是一種柔性事務又被稱為長時間運行的事務Long-running Transaction。Saga 由一系列的本地事務構成每一個本地事務在更新完數據庫之後會發佈一條消息或者一個事件來觸發 Saga 全局事務中下一個本地事務的執行。如果一個本地事務因為某些業務規則無法滿足而失敗Saga 會執行在這個失敗的事務之前成功提交的所有事務的補償操作。正因如此Saga 模式在對比 TCC 模式時由於缺少了資源預留的步驟往往在實現回滾邏輯時會變得更麻煩——開發者需要為每個正向操作手寫對應的補償操作。Saga 子事務拆分以銀行跨行轉賬為例將 A 賬戶中的 30 元轉到 B 賬戶根據 Saga 事務的原理整個全局事務被拆分為以下服務轉出TransOut服務操作 A 賬戶扣減 30 元。轉出補償TransOutCompensate服務回滾上面的轉出操作即 A 賬戶增加 30 元。轉入TransIn服務B 賬戶增加 30 元。轉入補償TransInCompensate服務回滾上面的轉入操作即 B 賬戶減少 30 元。整個事務的正常邏輯是執行轉出成功執行轉入成功全局事務完成如果在中間發生錯誤例如轉入 B 賬戶發生錯誤則會調用已執行分支的補償操作執行轉出成功執行轉入失敗執行轉入補償成功執行轉出補償成功全局事務回滾完成代碼示例以下展示在 Hyperf 框架中的使用方法其它框架類似namespace App\Controller; use DtmClient\Saga; use DtmClient\TransContext; use Hyperf\Di\Annotation\Inject; use Hyperf\HttpServer\Annotation\Controller; use Hyperf\HttpServer\Annotation\GetMapping; #[Controller(prefix: /saga)] class SagaController { protected string $serviceUri http://127.0.0.1:9501; #[Inject] protected Saga $saga; #[GetMapping(path: successCase)] public function successCase(): string { $payload [amount 50]; // 初始化 Saga 事務 $this-saga-init(); // 增加轉出子事務 $this-saga-add( $this-serviceUri . /saga/transOut, $this-serviceUri . /saga/transOutCompensate, $payload ); // 增加轉入子事務 $this-saga-add( $this-serviceUri . /saga/transIn, $this-serviceUri . /saga/transInCompensate, $payload ); // 提交 Saga 事務 $this-saga-submit(); // 通過 TransContext::getGid() 獲得全局事務ID 並返回 return TransContext::getGid(); } }代碼要點說明init()初始化一個 Saga 全局事務生成全局事務上下文。add(actionUrl, compensateUrl, payload)依序添加子事務每個子事務由正向操作 URL、補償操作 URL 和業務參數組成。多個add的順序即為 Saga 正向執行的順序。submit()將組裝好的 Saga 事務提交給 DTM Server 去編排執行。後續的執行、失敗補償均由 DTM-Server 調度完成客戶端無需自行串聯。補償操作同樣依賴子事務屏障保證在極端情況下如補償重試不重複執行。XA 模式XA 是由 X/Open 組織提出的分佈式事務規範。XA 規範主要定義了全局事務管理器TM和局部資源管理器RM之間的接口。本地數據庫如 MySQL在 XA 中扮演的是 RM 角色而 DTM-Server 扮演 TM 角色。XA 一共分為兩階段第一階段prepare所有參與者 RM 準備執行事務並鎖住需要的資源參與者 ready 時向 TM 報告已準備就緒。第二階段commit/rollback當事務管理者TM確認所有參與者RM都 ready 後向所有參與者發送 commit 命令完成最終提交若有任一參與者未就緒則執行 rollback。目前主流的數據庫基本都支持 XA 事務包括 MySQL、Oracle、SQLServer、PostgreSQL。XA 屬於典型的強一致性方案與 TCC/Saga 這類柔性事務形成互補。代碼示例以下展示在 Hyperf 框架中的使用方法其它框架類似?php namespace App\Controller; use App\Grpc\GrpcClient; use DtmClient\DbTransaction\DBTransactionInterface; use DtmClient\TransContext; use DtmClient\XA; use Hyperf\Contract\ConfigInterface; use Hyperf\Di\Annotation\Inject; use Hyperf\HttpServer\Annotation\Controller; use Hyperf\HttpServer\Annotation\GetMapping; use Hyperf\HttpServer\Annotation\RequestMapping; use Hyperf\HttpServer\Contract\RequestInterface; use Psr\Http\Message\ResponseInterface; #[Controller(prefix: /xa)] class XAController { private GrpcClient $grpcClient; protected string $serviceUri http://127.0.0.1:9502; public function __construct( private XA $xa, protected ConfigInterface $config, ) { $server $this-config-get(dtm.server, 127.0.0.1); $port $this-config-get(dtm.port.grpc, 36790); $hostname $server . : . $port; $this-grpcClient new GrpcClient($hostname); } #[GetMapping(path: successCase)] public function successCase(): string { $payload [amount 50]; // 開啟 XA 全局事務 $gid $this-xa-generateGid(); $this-xa-globalTransaction($gid, function () use ($payload) { // 調用子事務接口 $respone $this-xa-callBranch($this-serviceUri . /xa/api/transIn, $payload); // XA http模式下獲取子事務返回結構 /* var ResponseInterface $respone */ $respone-getBody()-getContents(); // 調用子事務接口 $payload [amount 10]; $this-xa-callBranch($this-serviceUri . /xa/api/transOut, $payload); }); // 通過 TransContext::getGid() 獲得全局事務ID 並返回 return TransContext::getGid(); } #[RequestMapping(methods: [GET, POST, PUT], path: api/transIn)] public function transIn(RequestInterface $request): array { $content $request-post(amount); $amount $content[amount] ?? 50; // 模擬分佈式系統下transIn方法 $this-xa-localTransaction(function (DBTransactionInterface $dbTransaction) use ($amount) { // 請使用 DBTransactionInterface 處理本地 Mysql 事務 $dbTransaction-xaExecute(UPDATE order set amount amount ? where id 1, [$amount]); }); return [status 0, message ok]; } /** * param RequestInterface $request * return array */ #[RequestMapping(methods: [GET, POST, PUT], path: api/transOut)] public function transOut(RequestInterface $request): array { $content $request-post(amount); $amount $content[amount] ?? 10; // 模擬分佈式系統下transOut方法 $this-xa-localTransaction(function (DBTransactionInterface $dbTransaction) use ($amount) { // 請使用 DBTransactionInterface 處理本地 Mysql 事務 $dbTransaction-xaExecute(UPDATE order set amount amount - ? where id 2, [$amount]); }); return [status 0, message ok]; } }代碼流程說明上面的代碼首先通過generateGid()生成全局事務 ID並用globalTransaction($gid, callable)註冊了一個全局 XA 事務。然後通過callBranch(url, payload)添加了兩個子事務transIn、transOut。子事務全部執行成功之後全局事務提交給 DTMDTM 收到提交的 XA 全局事務後會調用所有子事務的 XA commit完成整個 XA 事務。在子事務端點內部業務的本地 SQL 必須通過DBTransactionInterface::xaExecute()執行而不是直接使用普通數據庫查詢這樣本地 MySQL 才能以 XA 資源管理器RM的身份參與到兩階段提交中。這是 XA 模式與前兩種模式最本質的區別。示例中構造函數從dtm.server、dtm.port.grpc配置項讀取 gRPC 地址構建GrpcClient說明 XA 模式下客戶端可通過 gRPC 協議與 DTM-Server 通訊。二階段消息模式除了上述三種模式dtm-client 還支持二階段消息Two-Phase Message模式。從 DTM 與 Seata 的對比表中可以看到二階段消息是 Seata 未提供的能力其本質是最簡消息最終一致性架構先本地事務與消息一同落庫第一階段再由後臺任務或回調確認後真正投遞消息第二階段從而避免「先發消息後業務失敗」與「先業務後消息丟失」兩類經典問題。該模式與事務消息的場景高度契合適用於基於消息隊列的異步最終一致性業務。總結dtm-client 是 Hyperf 團隊維護、可用於生產環境的 DTM 分佈式事務客戶端安裝與配置均十分輕量composer require 發佈配置文件註冊一個 PSR-15 中間件。支持 TCC、Saga、XA、二階段消息四種主流模式通訊協議支持 HTTP 與 gRPC可安全運行於 PHP-FPM 和 Swoole 協程環境並對 Hyperf 做了更加易用的功能支持。選擇模式時需要強一致性且數據庫支持 XA可選XA需要資源預留、避免髒數據可選TCC追求最終一致性、業務補償邏輯可控可選Saga基於消息解耦的場景可選二階段消息。子事務屏障由 DTM-Server 與客戶端中間件協同完成是解決冪等、空補償、懸掛問題的關鍵機制務必保證中間件已在全局生效。配套的 Seata PHP 客戶端仍在孵化中生產環境選型時應優先考慮 dtm-client。與本文相關的微服務架構背景知識可進一步參閱 docs/zh-hk/microservice.md其中特別指出了分佈式事務是微服務化後必須面對的複雜性之一。赞分享后端微服务【免费下载链接】hyperf A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.项目地址https://gitcode.com/gh_mirrors/hy/hyperf点击查看免费下载相关推荐Hyperf 分布式事务实战基于 DTM 与 dtm-client 的 TCC、Saga、XA 完整接入指南Hyperf 分布式事务实战基于 DTM 与 dtm client 的 TCC、Saga、XA 完整接入指南导读本文以 Hyperf 官方维护的 DTM后端微服务Hyperf 分布式事务实战集成 DTM 的 TCC、Saga、XA 模式完整指南Hyperf 分布式事务实战集成 DTM 的 TCC、Saga、XA 模式完整指南本指南以 Hyperf 官方文档《分布式事务》为核心系统讲解由 Hype后端微服务Hyperf 分布式事务实战基于 DTM 与 dtm-client 的 TCC / Saga / XA 模式完全指南Hyperf 分布式事务实战基于 DTM 与 dtm client 的 TCC / Saga / XA 模式完全指南本文以 Hyperf 官方文档《分佈式事后端Web框架微服务RPC框架异步编程上一篇抖音下载神器douyin-downloader 让你的视频收集效率提升10倍下一篇抖音下载神器5分钟搞定免费批量下载的终极方案 ✨创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Hyperf 分佈式事務實戰：基於 DTM 的 TCC、Saga、XA 與二階段消息完整指南

相关推荐

PaddleNLP 土耳其语模型 dbmdz/bert-base-turkish-uncased 下载与使用实战指南

资源稀缺信号与约束内构建：let-fate-decide 中 Five of Pentacles（五角星五）的工程技术解读

ResNet优化模型实现阿尔茨海默症MRI识别：课程设计实战指南

更多资讯

停车场管理系统课程设计：用栈、队列、链表一题通关

仿微信聊天系统源码解析：WinForm桌面端IM开发实战指南

阿里 Qoder 智能体工作台实战：用 TaoToken 统一 Key 打通 Harness 与 Agent 工作流

OpenClaw Talk 模式实战：TaoToken 统一 Key 打通 Voice Call 语音链路配置指南

工控数据类型与值范围详解：从PLC到Modbus的解析避坑指南

新电脑装机指南：从系统初始化到效率工具的科学配置思路

今日更新

PHP htmlentities()函数用法讲解

AI Agent工程实战：从七要素到七个决策点的系统设计指南

AI入局芯片设计验证：验证收敛50倍加速的真相与应对

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？