快速上手

相关源文件

本页面内容基于以下源文件生成：

• pom.xml
• all/pom.xml
• seata-spring-boot-starter/pom.xml
• script/client/conf/file.conf
• script/client/conf/registry.conf
• common/src/test/java/org/apache/seata/common/util/CycleDependencyHandlerTest.java
• common/src/main/java/org/apache/seata/common/util/IOUtil.java
• common/src/main/java/org/apache/seata/common/util/NetUtil.java
• common/src/main/java/org/apache/seata/common/util/MapUtil.java
• common/src/main/java/org/apache/seata/common/util/SizeUtil.java

Apache Seata 是一个易于使用、高性能、基于 Java 的开源分布式事务解决方案。该项目采用 Maven 多模块架构，提供了从核心事务协调到多种注册中心、配置中心、RPC 框架的完整集成能力。

项目简介与模块结构

Seata 采用分层模块化设计，通过父 POM 统一管理所有子模块的构建与依赖版本。项目根目录的 pom.xml 定义了完整的模块列表，包括核心模块、集成模块、测试套件等。

根据 pom.xml:20-69，项目包含以下核心模块：

seata-all 是一个聚合模块，将所有核心功能打包为单一依赖，方便开发者快速引入。根据 all/pom.xml:29-34，该模块的描述为 "Seata is an easy-to-use, high-performance, java based, open source distributed transaction solution"。

环境要求

基础环境

根据 pom.xml:132-190 中的 Profile 配置，Seata 支持多个 JDK 版本：

建议配置：

• JDK 8 或 JDK 17（生产环境推荐）
• Maven 3.6+
• 内存：至少 2GB 可用堆内存（需要确认：具体内存要求未在源文件中明确）

测试依赖环境

项目使用 JUnit 5 作为测试框架，配合 Mockito 进行 Mock 测试。根据 pom.xml:71-118，测试依赖包括：

• junit-jupiter：JUnit 5 核心引擎
• mockito-core / mockito-junit-jupiter / mockito-inline：Mock 测试支持
• assertj-core：流式断言库
• slf4j-simple：测试日志输出

安装步骤

方式一：Maven 依赖引入（推荐）

对于大多数 Spring Boot 项目，推荐使用 seata-spring-boot-starter 进行快速集成。

步骤 1：添加依赖

在项目的 pom.xml 中添加以下依赖配置：

xml
1<dependency>
2    <groupId>org.apache.seata</groupId>
3    <artifactId>seata-spring-boot-starter</artifactId>
4    <version>${seata.version}</version>
5</dependency>

根据 seata-spring-boot-starter/pom.xml:1-30，该 Starter 提供了自动装配能力，无需手动配置 Bean。

步骤 2：引入聚合依赖（可选）

如果需要使用完整功能集，可以引入 seata-all 依赖。根据 all/pom.xml:47-98，该依赖包含以下核心模块：

xml
1<dependency>
2    <groupId>org.apache.seata</groupId>
3    <artifactId>seata-all</artifactId>
4    <version>${seata.version}</version>
5</dependency>

seata-all 聚合的模块包括：

• seata-common：公共工具
• seata-core：核心逻辑
• seata-config-*：多配置中心支持（Apollo、Nacos、ZooKeeper、Consul、etcd3、Spring Cloud）
• seata-discovery-*：多注册中心支持（Consul、Eureka、Nacos、Redis、ZooKeeper 等）
• seata-rm-datasource：数据库资源管理

方式二：源码构建

步骤 1：克隆仓库

bash
1git clone https://github.com/apache/incubator-seata.git
2cd incubator-seata
3git checkout 2.x

步骤 2：Maven 构建

bash
1# 跳过测试的快速构建
2mvn clean install -DskipTests
3
4# 包含测试的完整构建
5mvn clean install

（需要确认：具体构建命令未在源文件中明确，以上为 Maven 项目常见做法）

方式三：Docker 镜像（需要确认）

根据 pom.xml:191-220 中的镜像发布配置，Seata 提供多版本 Docker 镜像：

bash
1# 拉取镜像（需要确认：具体镜像仓库地址）
2docker pull apache/seata-server:latest
3docker pull apache/seata-server:2.x.jdk17

（需要确认：Docker 启动命令、端口号映射未在提供的源文件中找到）

最短可运行路径

Spring Boot 项目快速集成

以下是最小化配置步骤，帮助开发者在 2 分钟内完成 Seata 集成：

1. 添加 Maven 依赖

xml
1<!-- pom.xml -->
2<dependencyManagement>
3    <dependencies>
4        <dependency>
5            <groupId>org.apache.seata</groupId>
6            <artifactId>seata-dependencies</artifactId>
7            <version>2.x</version>
8            <type>pom</type>
9            <scope>import</scope>
10        </dependency>
11    </dependencies>
12</dependencyManagement>
13
14<dependencies>
15    <dependency>
16        <groupId>org.apache.seata</groupId>
17        <artifactId>seata-spring-boot-starter</artifactId>
18    </dependency>
19</dependencies>

2. 配置文件（最小配置）

yaml
1# application.yml
2seata:
3  enabled: true
4  tx-service-group: my_tx_group
5  service:
6    vgroup-mapping:
7      my_tx_group: default

（需要确认：具体配置项来自 script/client/conf/file.conf 和 script/client/conf/registry.conf，但源文件内容为空，无法提供确切配置示例）

3. 启动类添加注解

java
1@SpringBootApplication
2@EnableAutoDataSourceProxy // 开启数据源代理
3public class Application {
4    public static void main(String[] args) {
5        SpringApplication.run(Application.class, args);
6    }
7}

（需要确认：@EnableAutoDataSourceProxy 注解的使用方式未在源文件中找到）

运行验证

验证依赖引入

通过 Maven 命令检查依赖树：

bash
1mvn dependency:tree -Dincludes=org.apache.seata

预期输出应包含 seata-spring-boot-starter 及其传递依赖。

验证模块完整性

根据 all/pom.xml:47-98，seata-all 应包含以下核心模块：

单元测试验证

根据 pom.xml:71-118，项目使用 JUnit 5 测试框架。运行测试验证环境：

bash
1# 运行所有测试
2mvn test
3
4# 运行指定模块测试
5mvn test -pl common

（需要确认：具体测试类位置与预期输出未在源文件中找到）

常见问题与排错

问题 1：依赖冲突

现象：启动时报错 NoSuchMethodError 或 ClassNotFoundException

原因：Seata 依赖的第三方库版本与项目现有依赖冲突

解决方案：

1. 检查依赖树找出冲突：

bash
1mvn dependency:tree -Dverbose

2. 根据 all/pom.xml:540-595，部分依赖标记为 provided scope，需要手动引入：
   • grpc-netty / grpc-protobuf / grpc-stub：gRPC 支持
   • protostuff-core / protostuff-runtime：Protostuff 序列化
   • kryo / kryo-serializers：Kryo 序列化
   • hessian：Hessian 序列化

问题 2：JDK 版本不兼容

现象：构建失败，提示不支持当前 JDK 版本

原因：使用了不兼容的 JDK 版本

解决方案：

根据 pom.xml:132-190，选择正确的 Profile：

bash
1# JDK 8 构建
2mvn clean install -P release-image-based-on-java8
3
4# JDK 17 构建
5mvn clean install -P release-image-based-on-java17
6
7# JDK 25+ 构建（包含 namingserver 和 console 模块）
8mvn clean install -P JDK25Plus

问题 3：序列化框架缺失

现象：运行时报错找不到序列化器

原因：未引入对应的序列化依赖

解决方案：

根据 all/pom.xml:615-639，按需添加序列化依赖：

xml
1<!-- Kryo 序列化 -->
2<dependency>
3    <groupId>com.esotericsoftware</groupId>
4    <artifactId>kryo</artifactId>
5</dependency>
6<dependency>
7    <groupId>de.javakaffee</groupId>
8    <artifactId>kryo-serializers</artifactId>
9</dependency>
10
11<!-- Hessian 序列化 -->
12<dependency>
13    <groupId>com.caucho</groupId>
14    <artifactId>hessian</artifactId>
15</dependency>
16
17<!-- Protostuff 序列化 -->
18<dependency>
19    <groupId>io.protostuff</groupId>
20    <artifactId>protostuff-core</artifactId>
21</dependency>
22<dependency>
23    <groupId>io.protostuff</groupId>
24    <artifactId>protostuff-runtime</artifactId>
25</dependency>

问题 4：数据库驱动缺失

现象：连接数据库时报错找不到驱动

原因：数据库驱动依赖 scope 为 provided

解决方案：

根据 all/pom.xml:596-599，PostgreSQL 驱动需要手动引入：

xml
1<dependency>
2    <groupId>org.postgresql</groupId>
3    <artifactId>postgresql</artifactId>
4</dependency>

（需要确认：MySQL 驱动版本配置在 pom.xml:186-187 中定义为 5.1.42 和 8.0.27，但具体引入方式未明确）

下一步建议

完成快速上手后，建议按以下路径深入学习：

1. 配置详解：了解 file.conf 和 registry.conf 的完整配置项（需要确认：配置文件内容未在源文件中提供）

2. 事务模式选择：

   • AT 模式：无侵入式分布式事务
   • TCC 模式：高性能柔性事务
   • Saga 模式：长事务编排

3. 高可用部署：Seata Server 集群部署与配置中心集成

4. 性能调优：根据业务场景选择合适的序列化与压缩算法

5. 源码阅读：从 seata-core 模块入手，理解事务协调器的核心逻辑

详细的配置说明与使用指南，请参考项目的"使用指南"章节。