HelloWorld Seata 集成指南

将 HelloWorld 项目接入 Seata 的要点在于三步：先启动兼容的 Seata 服务端（可本地单机模式），然后在微服务中添加 seata-spring-boot-starter 并用 DataSourceProxy 包裹原始数据源，最后在发起分布式事务的方法上标注 @GlobalTransactional，同时保持注册中心和配置一致（registry、store、vgroupMapping 等）。本指南按原理→配置→代码→调试顺序，逐步带你完成从零到可验的集成。

为什么需要 Seata：把复杂说清楚

想象一个电商下单流程：扣库存、生成订单、扣客户积分，分别在不同服务里完成。如果其中一个步骤失败，整个业务就要回滚。Seata 就像一个仲裁者，帮你把这些跨服务的数据库操作组织成“看起来像一条事务”的行为——成功才提交，失败则回滚。

核心概念一览（用最少术语解释）

• Global Transaction（全局事务）：从调用方看，是一次业务调用的整体事务。
• Branch Transaction（分支事务）：每个微服务对自身数据库的操作，Seata 把它们当作分支来管理。
• AT 模式：默认且常用的二阶段补偿机制，通过 Undo Log 回滚数据库。
• Seata Server：负责事务协调（全局事务的管理和分支状态收集）。
• DataSourceProxy：在微服务端代理数据源以拦截 SQL，记录 Undo 信息。

先决条件（你需要准备什么）

• Java 开发环境（JDK 8+），Spring Boot 项目（常见 2.x/3.x）。
• 关系型数据库（MySQL 常用）并允许创建 undo-log 表与开启 binlog（视具体模式）。
• 一个可运行的 Seata Server（本地单机模式或注册中心如 Nacos、Eureka）。
• 网络连通：微服务能访问 Seata Server 与注册中心。

整体集成步骤（先看路线再动手）

• 1）选定 Seata 版本并引入依赖（与 Spring Boot 版本兼容）。
• 2）准备并启动 Seata Server（单机调试时使用 file 注册模式）。
• 3）在微服务中替换数据源为 DataSourceProxy 并配置 seata 参数。
• 4）在业务发起方方法加 @GlobalTransactional，分支服务加 @Transactional。
• 5）本地验证、查看日志与 Undo Log，修正问题。

示例：Maven 依赖与基本目录

这里用 Spring Boot + MyBatis/MyBatis-Plus 或 JPA 的常见组合举例，具体版本以官方兼容说明为准。

<dependency>
  <groupId>io.seata</groupId>
  <artifactId>seata-spring-boot-starter</artifactId>
  <version>{与项目兼容的版本}</version>
</dependency>

运行 Seata Server（本地单机快速验证）

开发调试时，用单机模式最省心：下载 seata-server 包，修改 registry.conf 和 file.conf 指向本地，然后启动。常见步骤是：

• 1. 解压 seata-server。
• 2. 在 conf 目录修改 registry.conf：设置 registry.type=file。
• 3. 在 file.conf 中配置 store.type=file 或 db（db 需提前建表 seata.undo_log）。
• 4. 启动 bin/seata-server.sh（或 .bat）。

registry.conf（示例）

registry {
  type = "file"
  file {
    name = "file.conf"
  }
}

file.conf（关键片段示例）

service {
  vgroupMapping.my_test_tx_group = "default"
}
store {
  mode = "file"
  file {
    dir = "./session-store"
  }
}

Spring Boot 项目配置

Seata 的配置可以放到 application.yml 中，关键是指定 tx-service-group、seata 服务地址（通过 registry 指定）和数据源代理的参数。

spring:
  application:
    name: order-service
seata:
enabled: true
tx-service-group: my_test_tx_group
service:
vgroup-mapping:
my_test_tx_group: default
registry:
type: file
config:
type: file

替换数据源：用 DataSourceProxy

最稳妥的做法是在 Spring 配置类中把原始数据源用 DataSourceProxy 包装，然后让 MyBatis/Spring Data 使用这个代理。

@Configuration
public class DataSourceConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource")
public DataSource druidDataSource() {
return DruidDataSourceBuilder.create().build();
}
@Bean
public DataSourceProxy dataSourceProxy(DataSource druidDataSource) {
return new DataSourceProxy(druidDataSource);
}
@Bean
public SqlSessionFactory sqlSessionFactory(DataSourceProxy dataSourceProxy) throws Exception {
SqlSessionFactoryBean fb = new SqlSessionFactoryBean();
fb.setDataSource(dataSourceProxy);
// ... mapper locations 等
return fb.getObject();
}
}

业务代码：如何标注事务

发起全局事务的一方在方法上用 @GlobalTransactional，分支服务在涉及数据库时仍使用 @Transactional 保持本地事务一致性。

@Service
public class OrderService {
@Autowired
private InventoryClient inventoryClient;
@GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
public void createOrder(OrderDTO dto) {
// 扣库存（远程调用）
inventoryClient.decrease(dto.getSkuId(), dto.getCount());
// 保存订单（本服务 DB 操作）
orderRepository.save(...);
// 其它操作...
}
}

分支服务（Inventory）在 controller 或相应 service 上标注 @Transactional，保证分支本地事务的回滚能力。

事务模式简述：AT、TCC、SAGA 与 XA

• AT：基于 undo-log 的补偿回滚，适合大多数关系型数据库场景，集成成本低，性能较好。
• TCC：需要实现 try/confirm/cancel 三个接口，适合业务补偿逻辑复杂但要求确定性的场景。
• SAGA：长事务补偿链，适合有一贯性补偿操作而不容易回滚的场景。
• XA：严格的两段提交协议，支持多资源管理器，但实现复杂且性能开销大。

常见坑与排查技巧（非常实用）

调试步骤（一步步验证）

• 1）先在本地用单机 Seata Server，确保 registry/file 配置一致，能启动。
• 2）在调用链上加入日志：全局事务 ID（XID）是否在日志中传播？
• 3）触发异常：在发起方抛出 RuntimeException，看分支是否回滚（检查数据库与 undo_log）。
• 4）若回滚失败，查看 seata-server 日志和微服务 logs，关注超时、连接拒绝和序列化错误。

最佳实践（来自实际经验）

• 只在发起方使用 @GlobalTransactional，避免在每个微服务都随意添加全局注解。
• 数据源统一代理：团队约束必须使用 DataSourceProxy，代码审查中把这作为一项检查点。
• 避免大事务：尽量把一个全局事务缩小到必要的步骤，长时间占用连接会影响性能。
• 监控：关注 seata-server 和微服务的延迟、错误率及 undo_log 累积情况。

常用命令与配置速查表

遇到网络或版本兼容问题怎么办

版本兼容是常见麻烦。Seata 与 Spring Boot、数据库驱动、MyBatis 版本都有耦合点。排查顺序通常是：先看客户端与服务端的协议/配置（registry、store），再看日志里的异常栈，最后对照官方兼容表。实在怀疑版本问题时，可用最小可运行的示例（HelloWorld）逐步替换依赖进行二分法定位。

最后一点：开发与回归测试

在 CI 中加入分布式事务的单元/集成测试能显著降低线上风险。一个实用的做法是：搭建一个轻量的本地环境（容器化 seata-server + 数据库），在 PR 阶段自动运行关键事务场景的回归用例，检查回滚与补偿是否按预期进行。

说到这里，可能你会想马上动手试试——那就从最小的 HelloWorld 项目开始：先把 seata-server 拉起来，配置好 tx group，把单体里的数据源替换成 DataSourceProxy，写一个简单的两个服务调用的用例，制造一个异常，观察 XID、undo_log 和最终 DB 状态，慢慢你就能把这些概念变成直觉了。