1. 从一条报错日志说起：分布式事务到底难在哪
我第一次接触分布式事务，是被一段线上日志逼出来的。订单创建成功了，库存扣减也返回了成功，结果账户余额扣款那一步超时回滚，最后数据库里躺着一笔“有订单、没扣款、库存还少了”的脏数据。单机事务里一个@Transactional就能搞定的事，一旦跨了服务、跨了数据库，立刻变成另一套游戏规则。这也是我后来专门搭seata测试demo来复现和验证@GlobalTransactional行为的原因——不亲手把各种失败场景跑一遍，你永远不知道全局事务在什么边界上会失效。
这篇内容围绕一个订单场景的 Seata 测试 Demo 展开，核心是搞清楚@GlobalTransactional这个注解在订单服务里到底做了什么、它背后的两阶段提交是怎么运转的、分支事务如何注册和回滚，以及在实际搭建和测试过程中会遇到哪些坑。适合已经写过 Spring Boot 单体事务、但对分布式事务只有概念认知的后端同学，也适合正在评估 Seata 是否适合自己业务的技术负责人。我会把整个 Demo 的搭建思路、关键配置、代码结构、失败场景复现和排查经验完整拆开讲，尽量做到你照着做就能跑起来，跑起来之后还能看懂每一步为什么这么设计。
需要先说明一点：Seata 的部署模式有几种，本文的 Demo 采用最常见的独立 TC 服务加业务侧 RM/TM 集成的思路，这是社区里资料最多、也最适合入门验证的组合。至于更高阶的集群和高可用部署，属于后续扩展话题，这里先把单机链路跑通、把原理吃透，比一上来堆架构更有价值。
2. Demo 整体设计与技术选型拆解
2.1 为什么选订单场景作为验证载体
订单是分布式事务最典型的试验田。一个下单动作天然横跨订单、库存、账户三个领域，每个领域在微服务拆分下往往对应独立服务和独立数据库。这种“一个业务动作、多个数据源”的结构，正好把本地事务的边界打破，让全局一致性需求暴露出来。
我设计的最小闭环是：订单服务负责创建订单记录，同时通过远程调用触发库存扣减和账户扣款。三个服务各自持有自己的库，订单服务作为全局事务的发起方，也就是 TM（Transaction Manager）角色，库存和账户服务作为分支事务的参与者，也就是 RM（Resource Manager）角色。这个结构足够简单，但已经能覆盖全局提交、全局回滚、分支失败、超时等核心场景。
选订单场景还有一个实际好处：业务语义清晰，回滚是否成功一眼就能判断。订单表有没有记录、库存数字有没有复原、账户余额有没有退回，三个数字对得上就说明事务生效，对不上就说明链路有问题。比起抽象的资金转账 Demo，订单场景更容易在测试时定位问题出在哪一环。
2.2 组件角色与数据流走向
在动手写代码前，必须先把 Seata 的几个角色在脑子里摆清楚，否则配置项会看得一头雾水。整个链路里存在三类角色：TC 是事务协调者，独立部署，负责维护全局事务和分支事务的状态，驱动二阶段提交或回滚；TM 是事务管理器，通常就是发起全局事务的那个服务，通过@GlobalTransactional注解标记方法边界；RM 是资源管理器，管理分支事务对应的数据库资源，负责向 TC 注册分支、上报状态、执行提交或回滚。
数据流的走向是这样的：订单服务的方法被@GlobalTransactional拦截后，向 TC 申请开启一个全局事务，拿到一个全局唯一的 XID；这个 XID 会通过远程调用的上下文一路透传到库存和账户服务；每个服务在执行本地数据库操作前，向 TC 注册自己的分支事务，并把本地事务和 XID 绑定；本地操作完成后上报分支状态；最后订单方法正常结束，TM 向 TC 发起全局提交，TC 再通知各分支完成二阶段动作。如果中途任何一环抛异常，TM 发起全局回滚，TC 驱动各分支根据 undo log 把数据还原。
理解这条链路的关键在于：全局事务的边界由 TM 的方法决定，而分支事务的原子性由各 RM 的本地事务加 undo log 保证。这两层是解耦的，很多人一开始误以为全局事务是一个“大事务”，实际上它是多个本地事务被协调起来的结果。
2.3 模式选择：AT 模式为何适合做入门验证
Seata 支持 AT、TCC、SAGA、XA 等几种模式。这个 Demo 我选 AT 模式，理由很直接：它对业务代码侵入最小，只需要在数据源上做代理，业务 SQL 几乎不用改，靠框架自动生成前后镜像来构造 undo log。对于验证@GlobalTransactional的基本行为来说，AT 模式能让你把注意力放在事务边界和协调流程上，而不是被补偿逻辑的编写分散精力。
AT 模式的代价也要提前知道：它依赖数据库的本地事务能力和全局锁机制，在高并发写同一行数据时会有锁竞争，性能不是它的强项。但作为测试 Demo，这些都不是问题，反而能让你在压测时直观感受到全局锁的存在。等 AT 模式跑通、原理吃透之后，再根据业务特性去评估 TCC 或 SAGA，这个顺序我认为是合理的。
2.4 技术栈与版本搭配的取舍
技术栈上我用的是 Spring Boot 加 Spring Cloud 的常规组合，注册中心用轻量方案，数据库选支持本地事务的关系型库。版本搭配是这类 Demo 最容易翻车的地方，我的经验是：Seata 客户端版本、Spring Cloud 版本、Spring Boot 版本三者必须查官方兼容矩阵，不能凭感觉升到最新。我踩过一次坑，客户端版本比服务端高了一个小版本，结果分支注册一直失败，日志里只报序列化异常，排查了大半天才发现是版本不匹配。
数据库方面，每个服务单独一个库，表结构里除了业务字段，AT 模式还要求每张参与全局事务的表有主键，因为 undo log 的回滚要靠主键定位行。这一点在后面讲表设计时还会强调，主键缺失是新手最常见的隐性故障源。
3. 环境搭建与核心配置实操
3.1 TC 服务的准备与启动要点
TC 服务是整个链路的心脏，它没起来，后面所有配置都是空谈。我的做法是先把 TC 单独跑起来，确认它能正常接受注册和开启全局事务，再去接业务服务。启动 TC 之前要确认它的存储模式，测试环境用文件存储就够，生产才考虑数据库存储。文件存储的好处是零依赖、启动快，缺点是重启后事务状态不持久，但对 Demo 验证完全够用。
启动时要注意端口和注册配置，业务侧的 TM 和 RM 需要能连上 TC。我一般先在 TC 日志里确认它监听的地址和端口，然后在业务配置里一字不差地对应上。这里有个细节：TC 的注册地址如果配成了主机名而业务侧解析不了，会出现连接超时但报错信息很模糊的情况，建议测试阶段直接用 IP 加端口，减少变量。
提示：TC 启动后先别急着接业务，用官方自带的事务开启接口或日志确认服务健康，再往下走，能省掉大量“到底是 TC 没起来还是业务配错了”的扯皮时间。
3.2 业务侧数据源代理配置
AT 模式的核心魔法发生在数据源代理这一层。业务代码里注入的DataSource必须被 Seata 包装成代理数据源，否则框架拦截不到 SQL，也就生成不了 undo log，全局回滚时会发现分支根本没有可回滚的数据。配置方式上，我倾向于用配置类显式声明代理数据源，把原始数据源包一层，这样比依赖自动装配更可控，出问题时也容易定位。
代理数据源配置好之后，还要确认undo_log表在每个业务库里都存在。这张表是 AT 模式的回滚依据，记录每次本地操作的前镜像和后镜像。表结构不能自己乱改，按官方脚本建就行。我见过有人图省事用自动建表，结果字段类型对不上，回滚时反序列化失败，数据卡在中间状态。
# 业务服务数据源相关配置示意 seata: enabled: true application-id: order-service tx-service-group: my_test_tx_group service: vgroup-mapping: my_test_tx_group: default grouplist: default: 127.0.0.1:8091上面这段是业务侧连接 TC 的关键配置，tx-service-group和vgroup-mapping的对应关系必须和 TC 侧一致，这是分支注册能成功的前提。很多人配置写完发现事务不生效，最后查出来就是这两个名字对不上。
3.3 订单服务中 @GlobalTransactional 的落点
注解加在哪，决定了全局事务的边界。我的做法是加在订单创建的入口方法上，这个方法内部先写订单库，再发起对库存和账户的远程调用。这样整个“下单”动作被一个全局事务包住，任何一步失败都能整体回滚。
这里有个容易忽略的点：@GlobalTransactional标注的方法必须是外部调用的入口，如果同类内部方法自调用，注解不会生效，因为代理没被经过。这个坑和 Spring 本地事务的@Transactional自调用失效是同一个道理，我在 Demo 里特意留了一个自调用的错误示例做对比，跑一遍就能直观看到全局事务没有开启、XID 为空的现象。
注解的几个常用属性也值得说清楚：rollbackFor要显式指定异常类型，默认只对运行时异常回滚，受检异常不会触发回滚；timeoutMills控制全局事务超时时间，超时后 TC 会主动回滚，这个值要结合业务耗时合理设置，设太短会导致正常业务被误回滚。
3.4 分支服务的接入与 XID 透传
库存和账户服务作为分支，接入的关键是两件事：数据源同样要被代理，以及远程调用时 XID 要能透传过去。XID 透传依赖调用链路的上下文传递，如果用的是带拦截能力的远程调用框架，Seata 一般能自动把 XID 塞进请求头。但如果中间经过了消息队列或者异步线程池，XID 就可能丢失，导致分支注册不上、回滚失效。
我在 Demo 里专门验证了同步调用和异步调用两种情况。同步调用下 XID 透传正常，分支能正确注册；异步场景下如果不手动传递 XID，分支就会脱离全局事务管理，变成一个独立的本地事务，这时候全局回滚根本管不到它。这个差异非常值得亲手跑一遍，因为它是很多线上事故的根源——看起来用了全局事务，实际上部分分支根本没被纳入。
4. 完整实操流程与关键环节验证
4.1 建表与初始数据准备
先把三个库的表建好。订单表记录订单号和状态，库存表记录商品和剩余数量，账户表记录用户和余额。每张表都要有主键，参与全局事务的表还要配套undo_log表。初始数据我准备了库存 100、余额 1000，方便后续观察数字变化。
| 表名 | 关键字段 | 初始值 | 作用 |
|---|---|---|---|
| order_info | id, order_no, status | 空 | 记录订单 |
| stock_info | id, product_id, count | count=100 | 库存数量 |
| account_info | id, user_id, balance | balance=1000 | 账户余额 |
| undo_log | 各业务库各一张 | 空 | AT 回滚依据 |
建表时我特意把主键设成自增，undo log 回滚靠主键定位，自增主键能保证定位准确。如果业务表用了业务主键，也要确保唯一且不为空，否则回滚时可能定位到多行或零行。
4.2 正常下单链路的执行与观察
正常链路是第一步验证。调用下单接口，传入商品和用户，预期结果是订单表新增一条记录、库存减 1、余额扣减对应金额，三个数字同步变化。跑通之后，我会去 TC 日志里确认全局事务的开启、分支注册、全局提交三个阶段都有记录，这是判断链路是否真正走通的硬证据。
只看业务结果是不够的，因为即使全局事务没生效，三个本地事务各自成功也会让数据看起来“正确”。所以必须结合 TC 日志和 XID 来确认。我在订单方法里打印了当前 XID，正常提交时能看到一个非空的全局事务 ID，分支服务日志里也能看到同一个 XID，这才说明整条链路被同一个全局事务串起来了。
4.3 制造异常触发全局回滚
验证回滚才是这个 Demo 的核心价值。我在账户服务里加了一个开关，当传入特定金额时主动抛异常，模拟扣款失败。预期行为是：订单方法捕获到远程调用异常后，全局事务回滚，订单记录被撤销、库存复原、余额不变。
实际跑的时候要注意异常类型。如果远程调用把异常包装成了别的类型，而rollbackFor没覆盖到，全局事务可能不会回滚。我第一次跑就遇到这个问题，账户服务抛的是受检异常，订单侧没显式配置rollbackFor，结果全局事务提交了，数据出现不一致。把rollbackFor配成Exception.class之后行为才符合预期。这个细节值得每个人亲手踩一次，比看十遍文档印象都深。
回滚完成后，去三个库分别查数据，订单表应该没有新记录，库存回到 100，余额回到 1000。同时undo_log表里对应的记录会被清理，如果发现 undo log 残留，说明回滚过程有问题，需要进一步查 TC 和 RM 的日志。
4.4 超时场景与全局锁的表现
除了异常回滚，超时也是必须验证的场景。我在库存服务里加了一段人为延时，把全局事务的timeoutMills设得比延时短，观察 TC 是否主动发起回滚。结果是超时后 TC 驱动全局回滚，已经完成的分支被撤销，未完成的分支收到回滚通知。
这个场景还能顺带观察全局锁。AT 模式下，分支在提交本地事务前要申请全局锁，如果另一个全局事务正在操作同一行数据，后到的会等待锁释放。我在 Demo 里用两个并发请求操作同一商品，能看到其中一个短暂阻塞，这就是全局锁在起作用。理解这一点很重要，它解释了为什么 AT 模式在高并发写热点数据时性能会下降——锁竞争是绕不开的成本。
4.5 分支失败但全局未感知的排查演练
有一种情况特别隐蔽：分支服务本地事务成功了，但上报状态给 TC 时网络抖动失败，导致 TC 认为分支没完成。这种场景下全局事务的状态和实际数据可能不一致。我在 Demo 里通过断点或人为制造上报失败来复现，观察 TC 的重试机制和最终状态。
排查这类问题的思路是：先看 TC 日志里该分支的状态记录，再看分支服务本地是否有对应的 undo log，最后核对业务数据。如果 TC 显示分支未完成但数据已改，说明上报环节出了问题，需要检查网络和 TC 连接配置。这个演练让我养成了一个习惯：任何分布式事务问题，先对齐 TC 视角和数据库视角，两边对不上，问题一定在中间的上报或通知环节。
5. 常见问题速查与避坑经验
5.1 事务不生效的几类典型原因
事务不生效是最高频的问题，我整理了一张速查表，按出现频率排序。大部分问题都能在这张表里找到对应项，剩下的再去看日志。
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 全局事务未开启，XID 为空 | 注解自调用、方法非 public、代理未生效 | 检查调用方式，确认经过代理 |
| 分支未注册 | XID 未透传、TC 地址配置错误 | 查远程调用上下文和 TC 连接 |
| 异常后未回滚 | rollbackFor 未覆盖异常类型 | 显式配置 rollbackFor |
| 回滚后数据未复原 | undo_log 缺失或表结构不符 | 检查 undo_log 表和主键 |
| 分支注册失败 | 版本不兼容、序列化异常 | 核对版本矩阵和序列化配置 |
这张表是我踩坑踩出来的，每一条背后都有具体的失败现场。比如“注解自调用”这一条，我当初排查了很久，因为日志里没有任何报错，只是事务静默地没生效，最后靠打印 XID 才发现根本没开启全局事务。
5.2 版本与依赖冲突的处理心得
Seata 客户端和服务端的版本兼容是个隐形雷区。我的经验是：服务端和客户端尽量用同一大版本，小版本差异也要查兼容说明。依赖冲突方面，重点看序列化相关的包，Seata 内部对序列化组件有版本要求，如果项目里其他依赖引入了不同版本的序列化库，可能出现分支注册时序列化失败。
排查依赖冲突我一般用依赖树命令把相关包列出来，看有没有重复引入或版本被顶掉。有一次分支注册一直失败，日志只报一个笼统的序列化错误，最后发现是项目里另一个组件把序列化库降了版本，导致 Seata 用的序列化器行为不一致。把版本统一之后问题消失。这类问题没有捷径，只能靠依赖树加日志定位。
5.3 全局锁竞争与性能观察
AT 模式的全局锁在测试时值得专门观察。我在 Demo 里用并发请求压同一行数据，能看到明显的等待。这个等待不是数据库行锁造成的，而是 Seata 的全局锁在协调。理解这一点对评估是否选用 AT 模式很关键：如果业务存在大量对同一行数据的高并发写，AT 模式的锁竞争会成为瓶颈，这时候要考虑业务拆分或者换模式。
观察全局锁的方法很简单，看分支提交前的日志，或者看 TC 侧的锁记录。我在压测时把并发数调高，能直观看到部分请求的耗时被拉长，拉长的部分主要花在等锁上。这个体感比看文档描述要深刻得多。
5.4 日志排查的正确打开方式
分布式事务的日志分散在 TC、TM、RM 三处，排查时必须按 XID 串起来看。我的习惯是：先在入口方法拿到 XID，然后分别去 TC 日志和分支日志里搜这个 XID，把整条链路的时序拼出来。只看单边日志很容易误判，比如分支日志显示本地事务成功，但 TC 日志显示分支未上报，两边一对比就知道问题在上报环节。
日志级别也要调对，测试阶段把 Seata 相关包的日志级别调低到能输出事务状态的程度，否则关键信息会被淹没。但要注意别开太细，日志量过大会拖慢测试节奏，也会让真正的问题更难找。我一般先开 info 级别看主干流程，定位到具体环节再临时调细。
6. 从 Demo 到真实业务的延伸思考
跑通这个 Demo 之后，我对@GlobalTransactional的理解从“一个注解”变成了“一套协调机制”。注解只是入口，真正决定事务行为的是 TC 的协调逻辑、RM 的 undo log 机制和 XID 的透传链路。这三者任何一环出问题，全局一致性都会打折扣。
往真实业务延伸时，有几个点需要提前想清楚。第一是事务边界的设计，全局事务包得越大，锁持有时间越长，性能越差，包得太小又可能漏掉需要一致性的操作，这个粒度要结合业务语义反复权衡。第二是分支服务的幂等性，回滚和重试都可能让分支操作执行多次，业务逻辑必须能承受重复执行。第三是超时和重试策略，全局事务超时后 TC 会回滚，但已经完成的分支回滚是否彻底，需要结合 undo log 和业务校验双重确认。
我在实际项目里还遇到过一个 Demo 覆盖不到的情况：分支服务内部又调用了另一个服务，形成了多级调用链。这种嵌套结构下 XID 的透传和分支注册会更复杂，需要确认每一级调用都正确携带了上下文。这个场景建议在 Demo 跑通后单独加一层调用做验证，提前暴露问题比上线后补救成本低得多。
最后分享一个我自己的习惯：每验证一个分布式事务场景，我都会把当时的配置、日志片段和数据库前后状态记成一份小笔记。这些笔记后来成了排查线上问题的第一手参考，因为真实故障往往就是这些基础场景的变体。Demo 的价值不在于它本身多复杂，而在于它把抽象的一致性概念变成了可以反复观察、反复验证的具体现象，跑得越多，对这套机制的理解就越扎实。
