doc:文档更新

2025-11-10 18:04:12 +08:00
parent 52ab580346
commit 174f720f65
3 changed files with 425 additions and 1 deletions
--- a/doc/中铜技术文档/Seata分布式事务集成参考.md
+++ b/doc/中铜技术文档/Seata分布式事务集成参考.md
@@ -0,0 +1,158 @@
+[Seata分布式事务集成参考.md](Seata%E5%88%86%E5%B8%83%E5%BC%8F%E4%BA%8B%E5%8A%A1%E9%9B%86%E6%88%90%E5%8F%82%E8%80%83.md)# Seata 分布式事务集成参考
+
+## 一、架构说明
+
+### 多环境 Seata 配置管理
+
+所有环境的 Seata 配置统一通过 Nacos 管理，本地配置文件不包含 Seata 配置。
+
+```
+├── dev 环境:   base-server-dev.yaml (dev_tx_group, namespace: dev)
+├── test 环境:  base-server-test.yaml (test_tx_group, namespace: test)
+└── prod 环境:  base-server-prod.yaml (prod_tx_group, namespace: prod)
+
+Seata Server: 172.16.46.63:30088
+```
+
+### 为什么使用 IP 直连？
+
+Nacos 的 namespace 隔离机制导致不同命名空间的应用无法跨 namespace 发现服务。Seata Server 通过 IP 直连（`registry.type=file`）避免此限制，所有环境共享同一个 Seata Server，通过不同的 `tx-service-group` 实现逻辑隔离。
+
+---
+
+## 二、Nacos 配置
+
+在对应环境的 Nacos 配置中心创建配置文件。以 `base-server-dev.yaml` 为例（其他环境只需修改 `tx-service-group`）：
+
+```yaml
+seata:
+  enabled: true
+  application-id: base-server
+  tx-service-group: dev_tx_group
+  enable-auto-data-source-proxy: true
+  data-source-proxy-mode: AT
+  registry:
+    type: file
+  config:
+    type: file
+  service:
+    vgroupMapping:
+      default_tx_group: default
+      dev_tx_group: default
+      test_tx_group: default
+      prod_tx_group: default
+    default:
+      grouplist: 172.16.46.63:30088
+  client:
+    tm:
+      defaultGlobalTransactionTimeout: 60000
+    undo:
+      logTable: undo_log
+      dataValidation: true
+      logSerialization: jackson
+```
+
+---
+
+## 三、业务集成步骤
+
+### 步骤 1：在 pom.xml 中添加依赖
+
+Seata 2.4.0 版本已在 `zt-dependencies` 中统一管理。业务模块只需在 `pom.xml` 中添加：
+
+```xml
+<dependency>
+    <groupId>io.seata</groupId>
+    <artifactId>seata-spring-boot-starter</artifactId>
+</dependency>
+```
+
+版本号会从 `zt-dependencies` 继承。
+
+### 步骤 2：创建 undo_log 表
+
+在业务数据库执行：
+
+```sql
+CREATE TABLE "UNDO_LOG" (
+    "BRANCH_ID"     BIGINT       NOT NULL,
+    "XID"           VARCHAR(128) NOT NULL,
+    "CONTEXT"       VARCHAR(128) NOT NULL,
+    "ROLLBACK_INFO" BLOB         NOT NULL,
+    "LOG_STATUS"    INT          NOT NULL,
+    "LOG_CREATED"   DATETIME     DEFAULT SYSDATE,
+    "LOG_MODIFIED"  DATETIME     DEFAULT SYSDATE,
+    PRIMARY KEY ("BRANCH_ID")
+);
+
+CREATE UNIQUE INDEX "UX_UNDO_LOG" ON "UNDO_LOG" ("XID", "BRANCH_ID");
+```
+
+### 步骤 3：在 Service 方法上添加 @GlobalTransactional 注解
+
+```java
+import io.seata.spring.annotation.GlobalTransactional;
+
+@Service
+public class OrderServiceImpl implements OrderService {
+
+    @GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
+    @Override
+    public Long createOrder(OrderCreateReqVO req) {
+        // 本地操作
+        orderMapper.insert(order);
+
+        // 跨服务调用自动参与分布式事务
+        inventoryApi.deduct(productId, quantity);
+
+        return order.getId();
+    }
+}
+```
+
+**说明**:
+- 只在事务发起方添加注解
+- 被调用的其他服务自动参与，无需额外配置
+- Seata 自动通过 HTTP Header 传递事务 ID
+
+---
+
+## 四、配置汇总
+
+| 配置项 | 开发环境 | 测试环境 | 生产环境 |
+|--------|---------|---------|---------|
+| **tx-service-group** | `dev_tx_group` | `test_tx_group` | `prod_tx_group` |
+| **Nacos 命名空间** | `hwc` | `test` | `prod` |
+| **Seata Server** | `172.16.46.63:30088` | `172.16.46.63:30088` | `172.16.46.63:30088` |
+
+---
+
+## 五、其他事务模式
+
+当前配置默认使用 **AT 模式**（自动事务模式）。Seata 还支持其他事务模式，需要业务自己实现：
+
+### TCC 模式
+
+需要实现 Try、Confirm、Cancel 三个业务方法，使用 `@TwoPhaseBusinessAction` 注解标记。详见官方文档。
+
+### Saga 模式
+
+需要定义 Saga 流程和状态机。详见官方文档。
+
+### XA 模式
+
+需要数据库支持 XA 事务，配置中修改 `data-source-proxy-mode: XA`。
+
+**详见**: https://seata.apache.org/zh-cn/docs/overview/what-is-seata
+
+---
+
+## 六、Seata 控制台
+
+**地址**: `http://172.16.46.63:30087`
+
+可查看全局事务、分支事务、全局锁等监控信息。
+
+---
+
+**官方文档**: https://seata.apache.org/zh-cn/docs/overview/what-is-seata