AlexStocks commented on issue #879:
URL:
https://github.com/apache/incubator-seata-go/issues/879#issuecomment-3263430520
# 补充：Seata-go README.md 核心缺失模块与完善建议
基于现有 README.md 内容，结合分布式事务框架的用户使用场景与文档规范性，可补充以下关键信息，帮助用户更全面理解项目、降低上手成本并规避常见问题：
## 一、核心功能：支持的事务模式说明
现有文档仅提及 TM/RM/TC 角色，未明确 Seata-go 支持的事务模式（分布式事务核心特性），需补充每种模式的适用场景与核心逻辑：
### 1. 支持的事务模式
Seata-go 对齐 Seata-Java 核心能力，目前支持以下4种主流分布式事务模式，满足不同业务场景需求：
| 事务模式 | 核心原理 | 适用场景 | 优势 | 注意事项 |
|----------|----------|----------|------|----------|
| **AT 模式（Automatic Transaction）** | 基于 SQL 解析自动生成 undo/redo
log，无侵入式事务控制，两阶段提交（一阶段本地提交+二阶段异步确认/补偿回滚） | 非侵入式需求、SQL 操作场景（如电商订单-库存-支付链路） |
开发无感知、性能优、适配主流关系型数据库（MySQL 优先） | 需创建 undo_log 表（见下文配置）、不支持非 SQL 操作 |
| **XA 模式** | 基于数据库原生 XA 协议，强一致性事务（一阶段准备+二阶段提交/回滚） |
强一致性需求、多数据库跨库事务（如金融核心业务） | 完全遵循 ACID、数据库原生支持 | 性能较弱（长事务锁定资源）、需数据库支持 XA 协议 |
| **TCC 模式（Try-Confirm-Cancel）** | 业务层手动定义
Try（资源检查/预留）、Confirm（确认执行）、Cancel（补偿回滚）三阶段接口 | 非 SQL 操作场景（如调用第三方 API、缓存更新） |
灵活性高、无锁阻塞 | 开发侵入式强、需手动处理幂等与空回滚 |
| **SAGA 模式** | 基于状态机的长事务解决方案，拆分事务为多个本地事务节点，失败时按逆序调用补偿节点 |
长事务场景（如跨天订单处理、物流状态流转） | 支持超长事务、低资源占用 | 最终一致性、需手动设计补偿逻辑 |
## 二、环境依赖与前置条件
现有“如何运行”仅提供 `go get` 命令，缺少环境依赖说明，用户易因版本不兼容或前置配置缺失导致启动失败：
### 1. 基础环境要求
- **Go 版本**：最低要求 Go 1.18+（依赖泛型、模块特性），推荐 Go 1.20+ 以保障性能与兼容性；
- **TC 服务器**：需部署 Seata 服务器（TC 角色），版本兼容性如下：
- Seata-go v2.0.0 兼容 Seata-Java TC v1.7.x / v2.0.x；
- 低于 Seata-go v1.6.0 版本需匹配 Seata-Java TC v1.5.x 及以下；
- **数据库支持**：
- 主流关系型数据库：MySQL 5.7+ / 8.0+（AT/XA 模式优先支持）；
- 实验性支持：PostgreSQL 12+（需手动适配方言配置）；
- 暂不支持 NoSQL 数据库（如 Redis、MongoDB）。
### 2. 前置配置（必做步骤）
#### （1）创建 undo_log 表（AT 模式必填）
AT 模式需在业务数据库中创建 undo_log 表（用于存储事务回滚日志），SQL 语句如下（以 MySQL 为例）：
```sql
CREATE TABLE `undo_log` (
`id` bigint NOT NULL AUTO_INCREMENT,
`branch_id` bigint NOT NULL,
`xid` varchar(100) NOT NULL,
`context` varchar(128) NOT NULL,
`rollback_info` longblob NOT NULL,
`log_status` int NOT NULL,
`log_created` datetime NOT NULL,
`log_modified` datetime NOT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `ux_undo_log` (`xid`,`branch_id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;
```
#### （2）TC 服务器配置
需确保 TC 服务器已启动，并配置 `registry.conf`（注册中心）与 `file.conf`（事务存储模式），示例：
- 注册中心：支持 Nacos / Eureka / ZooKeeper，如 Nacos 配置：
```yaml
registry {
type = "nacos"
nacos {
serverAddr = "127.0.0.1:8848"
namespace = ""
group = "SEATA_GROUP"
}
}
```
- 事务存储：支持 DB / Redis / File，生产环境推荐 DB 存储。
## 三、快速开始：极简代码示例
现有文档引导用户前往 samples 仓库，但 README 中加入极简示例可让用户快速理解核心用法（以 AT 模式为例）：
### 1. 步骤1：初始化全局事务配置
在项目启动时初始化 Seata 配置（如 `main.go`）：
```go
package main
import (
"github.com/apache/incubator-seata-go/pkg/client"
"github.com/apache/incubator-seata-go/pkg/conf"
)
func init() {
// 1. 配置 TC 地址（或通过配置文件加载）
conf.Load(conf.WithFile("seata-config.yaml"))
// 2. 初始化 Seata 客户端（TM + RM）
if err := client.Init(); err != nil {
panic("seata client init failed: " + err.Error())
}
}
```
### 2. 步骤2：定义全局事务（TM 角色）
在业务入口函数中开启全局事务，包裹多个微服务调用：
```go
import (
"context"
"github.com/apache/incubator-seata-go/pkg/tm"
)
// 全局事务入口：创建订单 -> 扣减库存 -> 扣减余额
func CreateOrder(ctx context.Context) error {
// 1. 开启全局事务（生成 XID 并自动传播）
globalTx, err := tm.BeginTx(ctx, tm.WithTimeout(60*1000)) // 事务超时 60s
if err != nil {
return err
}
defer func() {
// 3. 全局事务提交/回滚（根据业务结果）
if err != nil {
_ = tm.RollbackTx(globalTx)
} else {
_ = tm.CommitTx(globalTx)
}
}()
// 2. 调用各微服务（XID 会通过 Context 自动传播）
if err = orderService.CreateOrder(globalTx, orderDTO); err != nil {
return err
}
if err = stockService.DeductStock(globalTx, stockDTO); err != nil {
return err
}
if err = accountService.DeductBalance(globalTx, accountDTO); err != nil {
return err
}
return nil
}
```
### 3. 步骤3：本地事务接入（RM 角色）
在微服务的本地数据库操作中，通过 Seata 包装事务：
```go
import (
"context"
"github.com/apache/incubator-seata-go/pkg/datasource/sql"
)
// 扣减库存（本地事务，自动注册为分支事务）
func (s *StockService) DeductStock(ctx context.Context, dto StockDTO) error {
// 使用 Seata 包装的 DB 连接，自动关联全局事务
db, err := sql.Open("mysql", "root:123456@tcp(127.0.0.1:3306)/stock_db")
if err != nil {
return err
}
defer db.Close()
// 本地 SQL 操作（自动生成 undo log，参与全局事务）
_, err = db.ExecContext(ctx,
"UPDATE stock SET count = count - ? WHERE product_id = ? AND count >= ?",
dto.DeductNum, dto.ProductID, dto.DeductNum,
)
return err
}
```
## 四、关键配置项说明
补充核心配置文件（如 `seata-config.yaml`）的关键参数，帮助用户快速适配环境：
```yaml
seata:
client:
tm:
rollback-retry-count: 3 # 全局回滚重试次数
commit-retry-count: 3 # 全局提交重试次数
timeout: 60000 # 全局事务超时时间（ms）
rm:
report-retry-count: 5 # 分支事务状态上报重试次数
table-meta-check-enable: true # 是否开启表结构自动检查（AT 模式）
lock:
retry-count: 3 # 锁冲突重试次数
retry-interval: 1000 # 锁冲突重试间隔（ms）
service:
vgroup-mapping:
my_test_tx_group: default # 事务分组与 TC 集群映射（需与 TC 配置一致）
grouplist:
default: 127.0.0.1:8091 # TC 服务器地址（多个用逗号分隔）
transport:
type: tcp # 通信协议（默认 TCP）
server: nio # TC 通信模式（NIO）
heartbeat: true # 是否开启心跳检测
```
## 五、常见问题（FAQ）
补充用户初次使用时高频遇到的问题及解决方案，减少排查成本：
### 1. Q：XID 未传播到下游服务，导致分支事务未注册？
A：需确保以下两点：
- 下游服务调用时，必须通过 `context.Context` 传递（Seata-go 基于 Context 携带 XID）；
- 避免使用 goroutine 异步调用（需手动通过 `tm.TransferTx(ctx)` 传递上下文）。
### 2. Q：AT 模式下报错“undo_log 表不存在”？
A：需在**所有业务数据库**中创建 undo_log 表（见上文 SQL），且表结构与数据库版本匹配（如 MySQL 8.0 需注意字符集为
utf8mb4）。
### 3. Q：TC 连接超时，报错“connect to 127.0.0.1:8091 failed”？
A：检查：
- TC 服务器是否已启动，且端口 8091 未被占用；
- 配置文件中 `seata.service.grouplist` 与 TC 实际地址一致；
- 网络防火墙是否开放 TC 端口。
### 4. Q：TCC 模式下出现“空回滚”（Cancel 调用时无对应 Try 记录）？
A：需在 Cancel 接口中增加“幂等校验”：通过 XID + BranchID 查询本地事务状态，若未执行 Try 则直接返回成功。
## 六、版本兼容性说明
明确版本匹配关系，避免因版本不兼容导致功能异常：
| Seata-go 版本 | 兼容 Seata-Java TC 版本 | 最低 Go 版本 | 主要特性 |
|---------------|--------------------------|--------------|----------|
| v2.0.0 | v1.7.x / v2.0.x | Go 1.18+ | 新增 SAGA 模式、优化 AT
模式性能 |
| v1.6.0 | v1.5.x / v1.6.x | Go 1.16+ | 完善 XA 模式、支持
PostgreSQL 实验性适配 |
| v1.0.0 | v1.4.x | Go 1.14+ | 基础 AT/TCC
模式、MySQL 支持 |
> 注意：跨大版本使用时（如 Seata-go v2.0.0 对接 TC v1.4.x）可能存在兼容性问题，建议优先使用同大版本的 TC 服务器。
## 七、性能优化与监控建议
补充生产环境优化点与监控方案，满足高可用需求：
### 1. 性能优化建议
- **连接池配置**：增大数据库连接池（如 `maxOpenConns: 100`），避免 AT 模式下 undo log 写入阻塞；
- **批量操作**：对高频小事务（如批量订单创建），建议合并为单次全局事务，减少 TC 交互次数；
- **锁优化**：AT 模式下避免长事务（超时时间建议不超过 30s），减少行锁占用时间。
### 2. 监控集成
Seata-go 支持接入 Prometheus + Grafana 监控，核心指标包括：
- 全局事务总数/成功数/失败数（`seata_global_transaction_total`）；
- 分支事务注册数/提交数/回滚数（`seata_branch_transaction_total`）；
- 事务平均耗时（`seata_transaction_duration_seconds`）。
配置方式：在 `seata-config.yaml` 中启用监控：
```yaml
seata:
metrics:
enabled: true
type: prometheus
prometheus:
port: 9898 # Prometheus 暴露端口
```
## 八、生态工具与资源
补充 Seata-go 相关生态工具，帮助用户提升开发效率：
- **代码生成工具**：Seata-go 提供 TCC
接口代码生成插件（[seata-go-tcc-generator](https://github.com/apache/incubator-seata-go/tree/master/tools/tcc-generator)），自动生成
Try/Confirm/Cancel 模板代码；
- **诊断工具**：支持 Seata 诊断命令（如 `seata-cli`），可查询全局事务状态、手动清理异常 undo log；
- **IDE 插件**：IntelliJ IDEA 插件（[Seata
Plugin](https://plugins.jetbrains.com/plugin/18366-seata)）支持事务注解识别、配置文件高亮。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@seata.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscr...@seata.apache.org
For additional commands, e-mail: notifications-h...@seata.apache.org
