# SpringCloud-Local-Demo

**Repository Path**: send2ocean/spring-cloud-local-demo

## Basic Information

- **Project Name**: SpringCloud-Local-Demo
- **Description**: SpringCloud-Local-Demo
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Cloud 企业级学习项目

## 项目简介

这是一个完整的Spring Cloud企业级学习项目，包含分布式事务、分布式调度、分布式锁、RBAC权限系统等核心功能。每个关键代码都配有详细的学习注释，解释设计思路和实现原理。

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| JDK | 17 | LTS长期支持版本 |
| Spring Boot | 3.2.5 | 最新稳定版 |
| Spring Cloud | 2023.0.1 | 与Spring Boot 3.2兼容 |
| Nacos | 2.3.2 | 服务注册发现+配置中心 |
| Seata | 2.0.0 | 分布式事务 |
| MySQL | 8.0.x | 主数据库 |
| Redis | 7.x | 缓存+分布式锁 |
| RabbitMQ | 3.12.x | 消息队列 |
| Zipkin | Latest | 链路追踪 |

## 项目结构

```
springcloud-learning-demo/
├── cloud-common/                    # 公共模块
│   ├── cloud-common-core/           # 核心组件（Result、异常处理）
│   ├── cloud-common-redis/          # Redis操作、分布式锁
│   ├── cloud-common-seata/          # Seata分布式事务配置
│   └── cloud-common-security/       # JWT认证、用户上下文
├── cloud-gateway/                   # 网关服务 (端口:9000)
├── cloud-auth/                      # 认证服务 (端口:9100)
├── cloud-system/                    # 系统服务 (端口:9200) - RBAC
├── cloud-order/                     # 订单服务 (端口:9300) - AT模式演示
├── cloud-product/                   # 商品服务 (端口:9310) - TCC模式演示
├── cloud-account/                   # 账户服务 (端口:9320) - SAGA模式演示
├── cloud-job/                       # 调度服务 (端口:9400) - 分布式调度演示
├── cloud-admin-web/                 # 前端项目 (Vue3 + TypeScript)
├── docker-compose.yml               # Docker编排配置
└── sql/                             # 数据库脚本
```

---

## 快速启动

### 环境准备

确保本地已安装：
- **JDK 17+**
- **Maven 3.8+**
- **MySQL 8.0+**
- **Redis 7.x**
- **Docker Desktop**（用于运行中间件）

### 第一步：启动中间件

```bash
# 进入项目目录
cd D:\gitees\SpringCloud-Local-Demo

# 启动Docker中间件（Nacos、RabbitMQ、Seata、Zipkin）
docker-compose up -d
```

等待所有服务启动完成（约2-3分钟），可以通过以下地址访问：

| 服务 | 地址 | 用户名/密码 |
|------|------|------------|
| Nacos | http://localhost:8848/nacos | nacos/nacos |
| RabbitMQ | http://localhost:15672 | guest/guest |
| Zipkin | http://localhost:9411 | - |
| XXL-JOB | http://localhost:9090 | admin/123456 |
| MySQL | localhost:13306 | root/1234qwer |
| Redis | localhost:16379 | - |

### 第二步：初始化数据库

```bash
# 连接MySQL，执行SQL脚本
mysql -uroot -p1234qwer < sql/init_databases.sql
mysql -uroot -p1234qwer < sql/rbac_tables.sql
mysql -uroot -p1234qwer < sql/business_tables.sql
```

或者使用MySQL客户端工具（如Navicat）依次执行：
1. `sql/init_databases.sql` - 创建数据库
2. `sql/rbac_tables.sql` - 创建RBAC表
3. `sql/business_tables.sql` - 创建业务表

### 第三步：修改配置（如需要）

如果你的MySQL或Redis配置与默认不同，请修改以下文件中的配置：

- 各服务的 `application.yml` 中的数据库和Redis配置

默认配置：
- MySQL: localhost:13306, root/1234qwer
- Redis: localhost:16379, 无密码

### 第四步：编译项目

```bash
# 编译整个项目
mvn clean install -DskipTests
```

### 第五步：启动微服务

按以下顺序启动各服务：

```bash
# 1. 启动网关服务
cd cloud-gateway
mvn spring-boot:run

# 2. 启动认证服务
cd ../cloud-auth
mvn spring-boot:run

# 3. 启动系统服务
cd ../cloud-system
mvn spring-boot:run

# 4. 启动订单服务（AT模式）
cd ../cloud-order
mvn spring-boot:run

# 5. 启动商品服务（TCC模式）
cd ../cloud-product
mvn spring-boot:run

# 6. 启动账户服务（SAGA模式）
cd ../cloud-account
mvn spring-boot:run

# 7. 启动调度服务（分布式调度）
cd ../cloud-job
mvn spring-boot:run
```

### 第六步：验证启动

1. 访问 Nacos 控制台：http://localhost:8848/nacos
   - 查看服务列表，确认所有服务已注册

2. 访问 API 文档：http://localhost:9000/doc.html
   - 查看各服务的API接口

### 第七步：启动前端

```bash
# 进入前端项目目录
cd cloud-admin-web

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 http://localhost:5173 进入管理系统。

默认登录账号：
- 管理员：admin / 123456
- 普通用户：user / 123456

---

## 功能演示

### 1. 用户登录

```bash
# 登录请求
curl -X POST http://localhost:9000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 返回JWT Token
```

默认账号：
- 管理员：admin / 123456
- 普通用户：user / 123456

### 2. 分布式事务测试

#### AT模式测试（订单服务）

```bash
# 正常事务
curl -X POST http://localhost:9000/order/test?fail=false \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"userId":1,"productId":1,"quantity":1}'

# 事务回滚测试
curl -X POST http://localhost:9000/order/test?fail=true \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"userId":1,"productId":1,"quantity":1}'
```

### 3. 分布式锁测试

查看系统服务中的用户创建接口，使用了 `@DistributedLock` 注解：

```java
@PostMapping
@DistributedLock(key = "#dto.username", prefix = "user:create:")
public Result<Void> save(@RequestBody UserDTO dto) {
    userService.save(dto);
    return Result.success();
}
```

---

## 学习要点

### 分布式事务三种模式对比

| 模式 | 原理 | 优点 | 缺点 | 适用场景 |
|------|------|------|------|---------|
| AT | 自动记录undo_log回滚 | 零侵入、使用简单 | 需要全局锁 | 大多数业务场景 |
| TCC | Try-Confirm-Cancel三阶段 | 性能好、一致性高 | 代码侵入性强 | 核心资金类业务 |
| SAGA | 长事务拆分+补偿动作 | 适合长事务、无全局锁 | 无隔离性 | 复杂业务流程 |

### Redis分布式锁实现

本项目使用Redisson框架实现分布式锁，核心注解：

```java
@DistributedLock(
    key = "#orderId",           // 支持SpEL表达式
    prefix = "order:create:",   // Key前缀
    waitTime = 3000,            // 等待时间
    leaseTime = -1              // -1启用看门狗自动续期
)
```

### RBAC权限模型

```
用户(User) -> 角色(Role) -> 权限(Permission)
                     ↓
                   菜单(Menu)
```

五表模型：用户表、角色表、权限表、菜单表、关联表

---

## 常见问题

### Q1: 服务启动失败，提示Nacos连接不上？

确保Nacos已启动：
```bash
docker ps | grep nacos
```

如果未启动，执行：
```bash
docker-compose up -d nacos
```

### Q2: 分布式事务不生效？

确保Seata Server已启动：
```bash
docker ps | grep seata
```

检查各服务的Seata配置是否正确。

### Q3: 登录返回Token无效？

检查JWT密钥配置是否一致，所有服务使用相同的 `SecurityConstants.JWT_SECRET`。

---

## 项目亮点

1. **完整的分布式事务演示**：AT/TCC/SAGA三种模式对比实现
2. **详细的代码注释**：每个关键代码都有学习要点说明
3. **生产级最佳实践**：统一异常处理、参数校验、日志规范
4. **开箱即用**：完整的启动脚本和数据库初始化
5. **Vue3前端管理系统**：现代化前端技术栈，可视化演示分布式事务
6. **完整的RBAC权限系统**：前后端完整的用户角色权限控制

---

## 后续学习建议

1. 尝试修改代码，观察分布式事务的回滚行为
2. 添加新的微服务，练习服务间调用
3. 实现更复杂的业务场景
4. 学习Spring Cloud Gateway的过滤器链
5. 深入研究Seata的事务协调原理

---

## 前端项目 (cloud-admin-web)

### 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.4.x | 渐进式JavaScript框架 |
| TypeScript | 5.x | 类型安全的JavaScript超集 |
| Vite | 5.x | 下一代前端构建工具 |
| Element Plus | 2.6.x | Vue3组件库 |
| Pinia | 2.1.x | Vue3状态管理 |
| Vue Router | 4.x | Vue路由管理 |
| Axios | 1.6.x | HTTP请求库 |

### 前端项目结构

```
cloud-admin-web/
├── public/                          # 静态资源
├── src/
│   ├── api/                         # API接口定义
│   │   ├── auth.ts                  # 认证接口
│   │   ├── user.ts                  # 用户管理接口
│   │   ├── transaction.ts           # 分布式事务接口
│   │   └── job.ts                   # 调度任务接口
│   ├── components/                  # 公共组件
│   ├── layout/                      # 布局组件
│   │   ├── index.vue                # 主布局
│   │   ├── Sidebar.vue              # 侧边栏
│   │   ├── Navbar.vue               # 导航栏
│   │   └── AppMain.vue              # 内容区
│   ├── router/                      # 路由配置
│   │   └── index.ts                 # 路由定义
│   ├── stores/                      # Pinia状态管理
│   │   └── user.ts                  # 用户状态
│   ├── styles/                      # 全局样式
│   ├── utils/                       # 工具函数
│   │   ├── request.ts               # Axios封装
│   │   └── auth.ts                  # Token管理
│   ├── views/                       # 页面视图
│   │   ├── login/                   # 登录页
│   │   ├── dashboard/               # 首页仪表盘
│   │   ├── system/                  # 系统管理
│   │   │   ├── user/                # 用户管理
│   │   │   ├── role/                # 角色管理
│   │   │   ├── permission/          # 权限管理
│   │   │   └── menu/                # 菜单管理
│   │   ├── transaction/             # 分布式事务演示
│   │   │   ├── at/                  # AT模式演示
│   │   │   ├── tcc/                 # TCC模式演示
│   │   │   ├── saga/                # SAGA模式演示
│   │   │   └── compare/             # 模式对比
│   │   ├── job/                     # 分布式调度演示
│   │   │   ├── task/                # 任务管理
│   │   │   └── compare/             # 调度方案对比
│   │   ├── monitor/                 # 服务监控
│   │   │   └── service/             # 服务状态监控
│   │   └── error/                   # 错误页面
│   │       └── 404.vue              # 404页面
│   ├── App.vue                      # 根组件
│   └── main.ts                      # 入口文件
├── package.json                     # 依赖配置
├── vite.config.ts                   # Vite配置
└── tsconfig.json                    # TypeScript配置
```

### 前端快速启动

#### 安装依赖

```bash
cd cloud-admin-web
npm install
```

#### 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:5173 进入系统。

#### 构建生产版本

```bash
npm run build
```

### 前端功能页面

| 页面 | 路径 | 功能说明 |
|------|------|---------|
| 登录 | /login | 用户登录，JWT Token认证 |
| 首页 | /dashboard | 服务概览、统计数据 |
| 用户管理 | /system/user | 用户CRUD、分配角色 |
| 角色管理 | /system/role | 角色CRUD、分配权限 |
| 权限管理 | /system/permission | 权限标识管理 |
| 菜单管理 | /system/menu | 菜单树形结构管理 |
| AT模式演示 | /transaction/at | 创建订单测试、事务回滚演示 |
| TCC模式演示 | /transaction/tcc | 商品库存TCC扣减演示 |
| SAGA模式演示 | /transaction/saga | 账户余额SAGA扣减演示 |
| 模式对比 | /transaction/compare | 三种分布式事务模式对比表格 |
| 任务管理 | /job/task | XXL-JOB/Quartz任务管理 |
| 调度对比 | /job/compare | XXL-JOB/Quartz/Spring Task对比 |
| 服务监控 | /monitor/service | 微服务状态、中间件状态 |

### 前端特性

1. **经典后台管理布局**
   - 左侧菜单栏 + 右侧内容区
   - 顶部导航栏（用户信息、退出登录）
   - 响应式设计，支持移动端

2. **完整的权限控制**
   - 路由守卫：未登录跳转登录页
   - Token自动刷新机制
   - 按钮级权限控制

3. **分布式事务可视化演示**
   - 实时显示各服务数据变化
   - 一键触发事务回滚测试
   - 三种模式对比表格

4. **服务状态监控**
   - 实时显示各微服务运行状态
   - 一键访问各服务API文档
   - 中间件控制台快捷入口

---

## 许可证

本项目仅供学习使用。