# Elm_Cloud

**Repository Path**: LCC_Z/Elm_Cloud

## Basic Information

- **Project Name**: Elm_Cloud
- **Description**: 饿了么 Spring Cloud 微服务项目。基于 Spring Cloud + Vue 3 的前后端分离外卖点餐系统，按 DDD 拆分为用户、商家、购物车、订单、地址五个微服务，集成 Eureka、Config、Gateway、OpenFeign 与 Resilience4j 熔断等治理能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Elm_Cloud

> 饿了么 Spring Cloud 微服务项目

基于 **Spring Cloud + Vue 3** 的前后端分离外卖点餐系统。按 DDD 思想拆分为用户、商家、购物车、订单、地址五个业务微服务，并集成 Eureka 注册中心集群、Config 配置中心集群、Gateway 网关、OpenFeign 远程调用及 Resilience4j 熔断保护等治理能力。

---

## 目录

- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [架构设计](#架构设计)
  - [DDD 微服务划分](#ddd-微服务划分)
  - [微服务治理能力](#微服务治理能力)
  - [网关路由](#网关路由)
  - [前端架构](#前端架构)
- [快速开始](#快速开始)
  - [环境准备](#环境准备)
  - [编译](#编译)
  - [启动顺序](#启动顺序)
  - [访问地址](#访问地址)
- [功能验证](#功能验证)
  - [配置动态刷新](#配置动态刷新)
  - [熔断降级](#熔断降级)
  - [负载均衡](#负载均衡)
- [常见问题](#常见问题)
- [相关文档](#相关文档)

---

## 技术栈

| 层次 | 技术 |
|------|------|
| 后端 | Spring Boot 4、Spring Cloud 2025、Eureka、Config Server、Gateway、OpenFeign、Resilience4j、MyBatis、MySQL、RabbitMQ |
| 前端 | Vue 3、Vue Router、Vuex、Element Plus、Axios、Vite |
| 构建 | Maven（后端）、NPM（前端） |

## 项目结构

```
Elm_Cloud/
├── Elm_Common/                 # 公共模块：实体、Feign 客户端、JWT、统一响应、异常处理
├── Eureka_Service_18000/       # 注册中心节点 1
├── Eureka_Service_18001/       # 注册中心节点 2
├── Eureka_Service_18002/       # 注册中心节点 3
├── Config_Service_15000/       # 配置中心节点 1
├── Config_Service_15001/       # 配置中心节点 2
├── Config_Service_15002/       # 配置中心节点 3
├── Gateway_Server_12000/       # API 网关
├── User_Service_11000/         # 用户服务
├── Merchant_Service_11001/     # 商家 + 菜品服务（实例 1，端口 11001）
├── Merchant_Service_11011/     # 商家 + 菜品服务（实例 2，端口 11011）
├── Merchant_Service_11021/     # 商家 + 菜品服务（实例 3，端口 11021）
├── Cart_Service_11002/         # 购物车服务
├── Order_Service_11003/         # 订单服务
├── Address_Service_11004/      # 配送地址服务
├── vue_elm/                    # Vue 3 前端
├── docs/                       # DDD 说明、Config 配置模板
├── mvnw / mvnw.cmd             # Maven Wrapper
└── pom.xml                     # 父 POM（聚合 15 个后端模块）
```

---

## 架构设计

### DDD 微服务划分

| 限界上下文 | 模块 | 端口 | Eureka 名称 | 核心数据表 |
|------------|------|------|-------------|------------|
| 用户域 | User_Service_11000 | 11000 | user-service | user |
| 商家域 | Merchant_Service_11001 / 11011 / 11021 | 11001 / 11011 / 11021 | merchant-service（三实例） | business, food |
| 购物车域 | Cart_Service_11002 | 11002 | cart-service | cart |
| 订单域 | Order_Service_11003 | 11003 | order-service | orders, orderDetailet |
| 地址域 | Address_Service_11004 | 11004 | address-service | deliveryAddress |
| 网关 | Gateway_Server_12000 | 12000 | gateway-server | — |
| 注册中心 | Eureka × 3 | 18000–18002 | — | — |
| 配置中心 | Config × 3 | 15000–15002 | config-service | — |

**跨服务调用关系：**

- 订单服务 → 购物车、商家、地址（OpenFeign）
- 购物车服务 → 商家（OpenFeign）
- 前端 → 全部经 API 网关访问

### 微服务治理能力

| 能力 | 实现方式 |
|------|----------|
| 服务注册中心集群 | 3 节点 Eureka 互注册 |
| 负载均衡 | Gateway / Feign 使用 `lb://服务名`（Spring Cloud LoadBalancer） |
| 远程服务调用 | OpenFeign（`Elm_Common` 中定义客户端） |
| 网关熔断降级 | Gateway + Resilience4j CircuitBreaker → `FallbackController`（JSON）+ 前端 `ServiceUnavailable.vue` |
| 服务内保护 | 订单服务：Retry（购物车）、RateLimiter（商家）、Bulkhead（地址） |
| 微服务网关 | JWT 鉴权、路由转发、公开路径白名单 |
| 配置中心集群 | 3 节点 Config Server，Git 模式（Gitee 远程仓库） |
| 动态配置刷新 | Spring Cloud Bus + RabbitMQ + `@RefreshScope` |
| 统一请求日志 | `Elm_Common` 中 `RequestLoggingInterceptor` + Feign 调用日志（`elm.logging` 可配置） |

### 网关路由

前端统一通过网关 `http://localhost:12000` 访问，路径与课程单体项目保持一致。网关校验 JWT 后，向下游传递 `X-User-Id` 请求头。

| 路径前缀 | 目标服务 | 网关熔断 |
|----------|----------|----------|
| `/UserController/**` | user-service | breakerUser |
| `/BusinessController/**` | merchant-service | breakerMerchant |
| `/FoodController/**` | merchant-service | breakerMerchant |
| `/CartController/**` | cart-service | breakerCart |
| `/OrdersController/**` | order-service | breakerOrder |
| `/DeliveryAddressController/**` | address-service | breakerAddress |

### 前端架构

前端为 **Vue 3 单页应用**，使用 Vite 构建、Element Plus 搭建界面，Vue Router（Hash 模式）实现路由切换，整体采用 **vw** 单位做移动端响应式布局。

| 类别 | 技术选型 |
|------|----------|
| 框架 | Vue 3（Composition API / `<script setup>`） |
| 构建 | Vite |
| UI | Element Plus |
| 路由 | Vue Router 4（Hash 模式） |
| 状态 | Vuex（用户、Token） |
| 请求 | Axios + qs，基地址 `http://localhost:12000`（见 `vue_elm/src/main.js`） |

共 **15 个页面**（14 个业务页 + 1 个降级页）：

| 模块 | 路由 | 页面 | 说明 |
|------|------|------|------|
| 首页 | `/home` | 首页 | 点餐分类、商家推荐、搜索 |
| 首页 | `/businessList` | 商家列表 | 登录后显示各商家购物车数量 |
| 首页 | `/businessInfo` | 商家详情 | 加减菜品、去结算 |
| 用户 | `/login` | 登录 | 成功后返回上一页 |
| 用户 | `/register` | 注册 | — |
| 用户 | `/user` | 个人中心 | 头像、昵称、入口导航 |
| 订单 | `/order` | 确认订单 | 选择地址、提交订单 |
| 订单 | `/orderList` | 历史订单 | 未支付 / 已支付，可展开明细 |
| 订单 | `/payment` | 在线支付 | 展示订单并完成支付 |
| 地址 | `/userAddress` | 地址列表 | 选择 / 新增 / 编辑 / 删除 |
| 地址 | `/addUserAddress` | 新增地址 | — |
| 地址 | `/editUserAddress` | 编辑地址 | — |
| 设置 | `/changeInfo` | 修改资料 | 昵称、头像等 |
| 设置 | `/changePassword` | 修改密码 | — |
| 容错 | `/serviceUnavailable` | 服务降级 | 网关熔断或 5xx 时展示，支持返回重试 |

**公共组件：** `Footer.vue`（底部固定导航）、`BusinessItem.vue`（商家信息卡片）。除登录、注册等少数页面外，主要浏览页均挂载 Footer。

**布局与交互要点：**

- 移动端适配：全局 vw 单位；Footer、顶部栏 `position: fixed`
- 路由：编程式导航，主路由懒加载
- 权限：组件内登录态判断，未登录访问订单、个人中心时跳转登录页
- 反馈：ElNotification（主）+ 全局 ElMessage（`$message`）
- 容错：Axios 拦截器捕获 503 / 5xx / 网络错误 → `/serviceUnavailable`

---

## 快速开始

### 环境准备

| 依赖 | 要求 |
|------|------|
| JDK | 17+ |
| Node.js | 20.19+ 或 22.12+（见 `vue_elm/package.json`） |
| MySQL | 创建数据库 `Elm_Db`（表结构与数据同课程单体项目） |
| RabbitMQ | `localhost:5672`（默认 guest / guest） |

**Hosts 文件**追加：

```
127.0.0.1 eurekaServer18000
127.0.0.1 eurekaServer18001
127.0.0.1 eurekaServer18002
```

**配置中心 Git 仓库：** 业务服务的数据库连接、Resilience4j 等配置存放在 Config Server 关联的 Gitee 仓库中。首次运行前请确认 `Config_Service_15000/src/main/resources/application.yml` 中的 Git 地址与账号可用。

如需自建仓库，请同步维护以下配置文件：

- `user-service-11000-dev.yml`
- `merchant-service-11001-dev.yml`
- `merchant-service-11011-dev.yml`（模板见 `docs/config-templates/`）
- `merchant-service-11021-dev.yml`（可复制 11011 模板并将端口改为 11021）
- `cart-service-11002-dev.yml`
- `order-service-11003-dev.yml`
- `address-service-11004-dev.yml`

### 编译

```powershell
cd Elm_Cloud
.\mvnw.cmd clean package -DskipTests
```

### 启动顺序

按以下顺序在 IDE 中运行各模块主类，或使用 `java -jar` 启动对应 `target/*.jar`：

| 顺序 | 模块 | 主类 |
|------|------|------|
| 1 | RabbitMQ | （独立服务，先启动） |
| 2 | Eureka_Service_18000 | `EurekaApplication18000` |
| 3 | Eureka_Service_18001 | `EurekaApplication18001` |
| 4 | Eureka_Service_18002 | `EurekaApplication18002` |
| 5 | Config_Service_15000 | `ConfigApplication15000` |
| 6 | Config_Service_15001 | `ConfigApplication15001` |
| 7 | Config_Service_15002 | `ConfigApplication15002` |
| 8 | User_Service_11000 | `UserApplication11000` |
| 9 | Merchant_Service_11001 | `MerchantApplication11001` |
| 10 | Merchant_Service_11011 | `MerchantApplication11011`（可选，负载均衡验证） |
| 11 | Merchant_Service_11021 | `MerchantApplication11021`（可选，负载均衡验证） |
| 12 | Cart_Service_11002 | `CartApplication11002` |
| 13 | Order_Service_11003 | `OrderApplication11003` |
| 14 | Address_Service_11004 | `AddressApplication11004` |
| 15 | Gateway_Server_12000 | `GatewayApplication` |
| 16 | 前端 | 见下方命令 |

```powershell
cd vue_elm
npm install
npm run dev
```

> **注意：** 业务服务依赖 Config Server 从 Git 拉取配置，请确保 Config 集群与 Eureka 已就绪后再启动。

### 访问地址

| 服务 | 地址 |
|------|------|
| 前端 | http://localhost:5173 |
| API 网关 | http://localhost:12000 |
| Eureka 控制台 | http://localhost:18000 |
| Config Server | http://localhost:15000 |
| Knife4j（用户服务） | http://localhost:11000/doc.html |
| 配置验证接口 | http://localhost:11000/config/msg |

---

## 功能验证

### 配置动态刷新

1. 在 Config Server 关联的 Git 仓库中修改 `user-service-11000-dev.yml` 的 `msg` 字段
2. 查看配置是否生效：`GET http://localhost:15000/user-service-11000/dev`
3. 触发总线刷新：`POST http://localhost:15000/actuator/busrefresh`
4. 验证刷新结果：`GET http://localhost:11000/config/msg`（返回新的 `msg` 值）

### 熔断降级

**网关层：**

1. 停止 `cart-service` 或 `order-service`
2. 通过网关访问对应接口，Gateway 返回 503 JSON（含 `service`、`message` 字段）

**前端层：**

- Axios 响应拦截器捕获 503 / 5xx / 网络错误，跳转到 `/serviceUnavailable?type=cart` 等降级页
- 降级页文案配置在 `vue_elm/src/js/fallbackConfig.js`，展示组件为 `ServiceUnavailable.vue`
- 降级页提供「返回重试」「回到首页」按钮

**订单服务内（Resilience4j）：**

| 下游 | 保护机制 | 何时进入 fallback |
|------|----------|-------------------|
| 购物车 | `@Retry(retryCart)` | 重试次数耗尽后 |
| 商家 | `@RateLimiter(rateLimitMerchant)` | 仅触发 `RequestNotPermitted`（超配额）时 |
| 地址 | `@Bulkhead(bulkheadAddress)` | 仅触发 `BulkheadFullException`（并发已满）时 |

- 停止购物车服务：会重试后降级，日志 `[Retry-购物车]`
- 停止商家/地址服务：返回「服务暂时不可用」，**不会**误报限流或舱壁
- 限流/舱壁压测：可调用 `OrdersController` 的 `/getBusinessById`、`/getDeliveryAddress` 测试接口

### 负载均衡

项目已为 **商家服务** 预置三个模块，均注册为 `merchant-service`：

| 模块 | 端口 | Config 配置文件 |
|------|------|-----------------|
| Merchant_Service_11001 | 11001 | `merchant-service-11001-dev.yml` |
| Merchant_Service_11011 | 11011 | `merchant-service-11011-dev.yml` |
| Merchant_Service_11021 | 11021 | `merchant-service-11021-dev.yml` |

**验证步骤：**

1. 同时启动三个商家模块（或至少启动其中两个）
2. 打开 Eureka 控制台，确认 `MERCHANT-SERVICE` 下出现多个实例
3. 多次通过网关访问 `GET http://localhost:12000/BusinessController/getAll`
4. 观察各商家服务控制台中的 HTTP 请求日志（`[merchant-service]`），确认请求轮询到不同端口实例

> 其他业务服务（如 `cart-service`）也可按相同方式复制模块、修改端口与 Config 文件名后做负载均衡实验。

---

## 常见问题

| 问题 | 处理建议 |
|------|----------|
| 业务服务启动失败 | 检查 MySQL、Config Server、Eureka 是否已启动；确认 Git 配置仓库可访问 |
| 前端 503 / 降级页 | 确认 Gateway 与对应微服务已注册到 Eureka；网关返回 JSON，前端路由 `/serviceUnavailable` 展示降级页 |
| Bus 刷新无效 | 确认 RabbitMQ 已启动，且各服务已引入 `spring-cloud-starter-bus-amqp` |
| Eureka 节点无法互连 | 检查 Hosts 是否配置三个 `eurekaServer*` 域名 |
| 商家多实例启动失败 | 确认 Config 仓库已维护 `merchant-service-11011-dev.yml` / `11021-dev.yml`；11011 模块含本地兜底 `application.yml` |

---