hyperf 不推荐对接 seata，因其 java 生态强绑定与协程模型冲突，易致事务悬挂、confirm 超时等问题；应采用原生 tcc 方案，使用 tcc-transaction 组件，严格管控 try/confirm/cancel 幂等性、上下文透传及状态持久化。
Hyperf 本身不原生支持 Seata，也**不推荐强行对接 Seata**——因为 Seata 的 Java 生态强绑定（TM/RM 均依赖 JVM）、通信协议（gRPC/HTTP）与 Hyperf 的协程模型存在调度冲突和生命周期 mismatch，实测中常出现事务悬挂、Confirm 超时未触发、子事务屏障失效等问题。
为什么不能直接用 Seata + Hyperf
Seata 的 AT 模式依赖数据库代理（如 JDBC DataSourceProxy）自动解析 SQL 并生成 undo_log，PHP 没有等效机制；TM（事务管理器）是 Java 进程，Hyperf 服务需通过 HTTP/gRPC 主动注册分支事务并轮询状态，但 Hyperf 协程在长轮询或超时重试时容易丢失上下文，导致 BranchRegisterRequest 重复发送或响应丢包。社区已有多个失败案例反馈：事务 ID 不一致、GlobalSession 状态卡在 Begin、Cancel 阶段收不到回调。
Hyperf 真正可用的 TCC 实战路径
绕过 Seata，用 Hyperf 原生生态落地 TCC，关键是选对组件、管住三个风险点：
本页面提供企业级 PHP 协程框架 Hyperf 3.1.66 版本的官方源码下载与完整更新日志。重点解析 v3.1.66 版本中新增的 gRPC 多客户端负载均衡支持、Pool 连接池全量刷新、Guzzle 持久化 Cookie 以及数据库 JSON 包含键查询等核心优化特性。
- 用
tcc-transaction（非 Seata）：它基于注解 + AOP + Redis 状态存储，所有 Try/Confirm/Cancel 方法都在 PHP 层可控，无跨语言通信开销 - Try 阶段必须做资源预留校验（如库存 check + 冻结），且写入
tcc_transaction表记录事务 ID 和分支状态 - Confirm/Cancel 必须幂等：方法入口加
if ($this->isConfirmed($xid)) return;，避免网络重试导致重复执行 - Cancel 要防空回滚：在 Try 成功后才允许 Cancel；若 Try 未执行就收到 Cancel 请求，需查 DB 判定是否跳过（
tcc-transaction内置该逻辑）
跨服务调用时的事务传播陷阱
Hyperf 默认不传递事务上下文，TCC 分支间无法关联同一 global_xid。必须手动透传：
- 在 Try 方法内生成唯一
$xid = uniqid('tcc_')，存入Context并随 RPC 请求头发出：X-TCC-XID: $xid - 下游服务的 Controller 或 RPC Handler 中，用
Context::set('xid', $request->header('X-TCC-XID'))恢复上下文 - Confirm/Cancel 方法需从 Context 取
xid，而非依赖参数传入——否则异步回调（如 MQ 触发 Cancel）会丢失上下文 - 注意 JSON-RPC 的 header 透传需配置
hyperf/json-rpc的packer支持自定义 header，gRPC 则需在Metadata中显式携带
生产环境必须补的监控与兜底
TCC 在 Hyperf 中不是“开箱即用”的黑盒，以下三点漏掉一个，线上就可能资损：
- 所有 Confirm/Cancel 方法必须有失败告警：用
Hyperf\AsyncQueue\Job包裹重试逻辑，并在第 3 次失败后发钉钉通知——tcc-transaction自带的 NSQ 回查只解决“没收到回调”，不解决“回调失败” - 定期扫描
tcc_transaction表中status = 'TRYING'超过 5 分钟的记录，触发人工介入或强制 Cancel - 不要依赖 Redis 存储事务状态：Redis 故障会导致整个 TCC 流程中断；必须把核心状态（xid、branch_id、status）落库，Redis 仅作缓存加速
真正的难点不在代码怎么写，而在事务边界是否被业务方真正理解——比如订单服务 Try 阶段冻结金额，支付服务 Confirm 阶段才真实扣款，中间任何环节降级为“最终一致”，就必须同步更新前端展示状态，否则用户看到“已支付”但钱没扣，比数据不一致更致命。
