# software_practice_complex_microservice

**Repository Path**: xenogene/software_practice_complex_microservice

## Basic Information

- **Project Name**: software_practice_complex_microservice
- **Description**: 天津大学  软件工程高级实践完整项目
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-11
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 饿了没 - 全端外卖平台 V2.0 （微服务 React18 AI推荐）

## 此项目达到了天津大学软件工程高级实践的验收需求

![项目预览](./img/readmeimg2.png)
![项目预览](./img/readmeimg1.png)

这是一个从传统单体版本演进而来的**微服务外卖平台**。项目包含：

- **用户端 (React 18)** `frontend/elmclient-react` — 现代 React 重构版
- **商家端 (React 18)** `frontend/elmbusiness-react` — 现代 React 重构版
- **骑手端 (React 18)** `frontend/elmdeliver-react` — 现代 React 重构版
- **旧版用户端 (Vue)** `frontend/elmclient` — 遗留 Vue 版本
- **旧版商家端 (Vue)** `frontend/elmbusiness` — 遗留 Vue 版本
- **旧版骑手端 (Vue)** `frontend/elmdeliver` — 遗留 Vue 版本
- **后端微服务集群** `backend/*`

系统覆盖外卖业务的完整主链路：

- 用户注册、登录、浏览商家、购物车、下单、支付
- 商家管理店铺、菜品、订单
- 骑手接单、配送、提现
- 钱包、积分、优惠券、任务、活动、抽奖等营销能力
- 客户端 AI 推荐吃什么（对话式推荐）

---

## 目录结构

```text
software_practice_complex/
├── backend/
│   ├── elm-cloud-parent/           # Spring Cloud 父工程
│   ├── elm-eureka-server1/         # Eureka 1
│   ├── elm-eureka-server2/         # Eureka 2
│   ├── elm-eureka-server3/         # Eureka 3
│   ├── elm-config-server1/         # Config 1
│   ├── elm-config-server2/         # Config 2
│   ├── elm-gateway/                # Gateway 网关
│   ├── elm-user-service/           # 用户服务
│   ├── elm-business-service/       # 商家服务
│   ├── elm-order-service/          # 订单服务
│   ├── elm-coupon-service/         # 优惠券服务
│   ├── elm-wallet-service/         # 钱包服务
│   ├── elm-points-service/         # 积分服务
│   ├── elm-task-service/           # 任务服务
│   ├── elm-activity-service/       # 活动服务
│   ├── start-all-services.sh       # 后端一键启动脚本
│   └── stop-all-services.sh        # 后端一键停止脚本
├── frontend/
│   ├── elmclient-react/            # 用户端前端 (React 18 + TypeScript)
│   ├── elmbusiness-react/          # 商家端前端 (React 18 + TypeScript)
│   └── elmdeliver-react/           # 骑手端前端 (React 18 + TypeScript)
├── elm.sql                         # 数据库初始化脚本
├── img/                            # README 图片资源
└── README.md
```

---

## 运行环境

### 基础要求（Docker 方式）

- **Docker Desktop**（macOS / Windows）
- **Docker Compose v2**（通常随 Docker Desktop 安装）

### 首次启动

在项目根目录执行：

```bash
docker compose up -d --build
```

或使用封装脚本（推荐）：

```bash
./docker-start.sh
```

说明：

- 容器内会自动初始化数据库（`elm.sql`）
- MySQL 映射端口为 `3307`
- API Gateway 对外端口为 `8080`

---

## 启动方式（Docker）

### 一键启动（重建镜像）

```bash
docker compose up -d --build
```

### 日常重启（不重建）

```bash
docker compose restart
```

### 重启单个服务（示例）

```bash
docker compose restart gateway
docker compose restart business-service
docker compose restart elmclient
```

### 查看状态与日志

```bash
docker compose ps
docker compose logs -f gateway
docker compose logs -f business-service
```

### 停止与清理

```bash
docker compose down
docker compose down -v
```

`down -v` 会清空数据库卷，仅在需要重置数据时使用。

### 启动完成后可访问

- **用户端（React 18，推荐）：`http://localhost:8093`**
- **商家端（React 18）：`http://localhost:8094`**
- **骑手端（React 18）：`http://localhost:8095`**
- 用户端（旧版 Vue）：`http://localhost:8090`
- 商家端（旧版 Vue）：`http://localhost:8091`
- 骑手端（旧版 Vue）：`http://localhost:8092`
- Gateway：`http://localhost:8080`
- Eureka：`http://localhost:8761`
- MySQL：`localhost:3307`

---

## 后端总体架构

本项目后端采用**Spring Boot + Spring Cloud** 的分布式微服务架构，分为两层：

- **基础设施层**
- **业务服务层**

### 基础设施层

| 服务 | 目录 | 作用 |
| ---- | ---- | ---- |
| Eureka Server 1 | `backend/elm-eureka-server1` | 服务注册中心节点 1 |
| Eureka Server 2 | `backend/elm-eureka-server2` | 服务注册中心节点 2 |
| Eureka Server 3 | `backend/elm-eureka-server3` | 服务注册中心节点 3 |
| Config Server 1 | `backend/elm-config-server1` | 配置中心节点 1 |
| Config Server 2 | `backend/elm-config-server2` | 配置中心节点 2 |
| Gateway | `backend/elm-gateway` | 统一入口、路由转发、网关过滤 |

### 业务服务层

| 服务 | 目录 | 核心职责 |
| ---- | ---- | -------- |
| User Service | `backend/elm-user-service` | 用户、地址、登录注册、购物车等 |
| Business Service | `backend/elm-business-service` | 商家、食品、评价、收藏 |
| Order Service | `backend/elm-order-service` | 订单创建、支付流转、骑手配送流转 |
| Coupon Service | `backend/elm-coupon-service` | 优惠券校验、领取、使用 |
| Wallet Service | `backend/elm-wallet-service` | 钱包、余额、交易、充值、支付密码 |
| Points Service | `backend/elm-points-service` | 积分账户、积分流水、积分增减 |
| Task Service | `backend/elm-task-service` | 任务中心、奖励领取、任务统计 |
| Activity Service | `backend/elm-activity-service` | 签到、抽奖、活动逻辑 |

### 架构关系

```text
Frontend Apps
   │
   ▼
Spring Cloud Gateway
   │
   ├── User Service
   ├── Business Service
   ├── Order Service
   ├── Coupon Service
   ├── Wallet Service
   ├── Points Service
   ├── Task Service
   └── Activity Service

All services register to Eureka cluster
All service configuration is loaded from Config cluster
```

### 关键业务调用关系

- **订单服务**
  - 调用用户服务获取用户等级/地址
  - 调用商家服务获取商家信息
  - 调用优惠券服务校验与使用优惠券
  - 调用钱包服务完成钱包支付
  - 调用积分服务发放订单积分

- **任务服务**
  - 调用积分服务发放任务奖励

- **活动服务**
  - 调用积分服务扣减抽奖积分、发放抽奖奖励

---

## 微服务设计说明（按要求逐条说明）

## 2. 根据需求创建若干 Spring Boot 项目，作为整个架构的若干个微服务

本项目将系统按业务边界拆分为多个 Spring Boot 工程：

- 用户域：`elm-user-service`
- 商家域：`elm-business-service`
- 订单域：`elm-order-service`
- 优惠券域：`elm-coupon-service`
- 钱包域：`elm-wallet-service`
- 积分域：`elm-points-service`
- 任务域：`elm-task-service`
- 活动域：`elm-activity-service`

拆分后每个服务都可以：

- 独立开发
- 独立部署
- 独立扩容
- 独立演进数据模型和接口

## 3. 创建基于 RestTemplate 的微服务调用

项目中保留了基于 Spring Cloud 负载均衡能力的服务间 HTTP 调用能力，适用于：

- 简单同步调用
- 兼容旧实现
- 对调用细节需要显式控制的场景

`RestTemplate` 的价值在于：

- 上手简单
- 调用链清晰
- 可作为 Feign 之外的基础调用手段

## 4. 创建基于 Eureka 的高可用集群

本项目配置了 **3 个 Eureka Server**：

- `elm-eureka-server1`
- `elm-eureka-server2`
- `elm-eureka-server3`

作用：

- 服务注册
- 服务发现
- 提高注册中心可用性

高可用价值：

- 任一注册中心节点异常时，其余节点仍可继续提供注册/发现能力
- 避免单点故障导致整个系统不可用

## 5. 创建基于 Feign 的服务调用及负载均衡

项目中多个服务使用 **OpenFeign** 进行声明式调用，例如：

- 订单服务调用：
  - 用户服务
  - 商家服务
  - 优惠券服务
  - 钱包服务
  - 积分服务
- 活动服务调用积分服务
- 任务服务调用积分服务

优势：

- 接口式声明调用，代码更清晰
- 与 Spring Cloud 集成紧密
- 可直接结合 Eureka 做服务发现与负载均衡

## 6. 创建基于 Hystrix 的熔断降级

项目中服务调用已经实现了**降级思路和 fallback 机制**，例如 Feign fallback。  
从课程/架构说明角度，这一层可归入**熔断降级能力**建设。

它的目标是：

- 当下游服务不可用时，避免级联故障
- 提供默认返回/兜底逻辑
- 提高系统容错性

在本项目中，你可以从已有的 `Fallback` 类和服务调用兜底逻辑看到这一设计意图。

## 7. 创建基于 Gateway 的微服务网关

本项目使用 `elm-gateway` 作为统一网关，负责：

- 统一入口
- 路由转发
- 全局过滤
- 后续可扩展统一认证、限流、日志、灰度发布

网关价值：

- 前端不直接面向所有后端服务
- 隐藏内部服务拓扑
- 统一治理跨服务访问规则

## 8. 创建基于 Config 的集中配置管理集群

本项目包含两个 Config Server：

- `elm-config-server1`
- `elm-config-server2`

职责：

- 为各微服务提供统一配置源
- 便于环境配置集中维护
- 减少重复配置和手工同步风险

价值：

- 配置统一管理
- 便于扩展多环境
- 配置变更路径更清晰

## 9. 创建基于 Bus 的配置刷新

从架构设计目标上，集中配置不仅要“集中存放”，还要支持“动态刷新”。  
这一部分的目标是：

- 配置更新后能够广播到各服务
- 减少逐个重启服务的成本
- 提升运维效率

在课程/架构说明层面，这一能力对应的是 **Spring Cloud Bus + Config Refresh** 的设计思路。

---

## 当前项目包含的核心技术

### 前端（新版三端）

- **React 18** + TypeScript
- **Vite** 构建工具
- **react-router 6** 路由
- **TanStack Query** 数据获取与缓存
- **Axios** HTTP 客户端
- **Lucide React** 图标系统
- 响应式设计 + OKLCH 色彩系统

### 前端（旧版遗留）

- Vue 2
- Vue Router
- Axios

### 后端

- Spring Boot
- Spring Cloud
- Eureka
- OpenFeign
- Gateway
- Config
- MyBatis
- MySQL

### 新版三端（React 18）

三个前端全部使用 React 18 + TypeScript 重写，采用统一设计系统（`.claude` 设计规范），与旧 Vue 版本并存。

| 端 | 目录 | 端口 | 技术栈 |
|----|------|------|--------|
| 用户端 | `frontend/elmclient-react` | 8093 | Vite + React 18 + TS + react-router 6 + TanStack Query + axios + lucide-react |
| 商家端 | `frontend/elmbusiness-react` | 8094 | Vite + React 18 + TS + react-router 6 + TanStack Query + axios + lucide-react |
| 骑手端 | `frontend/elmdeliver-react` | 8095 | Vite + React 18 + TS + react-router 6 + TanStack Query + axios + lucide-react |

**统一设计规范：**
- 色彩：OKLCH 苔绿主题（品牌色 `#4CAF50` / `#22c55e`）
- 字体：Smiley Sans + Noto Sans SC + Geist 字体栈
- 间距：4pt 基础间距系统
- 交互：简洁动效、避免 AI slop 反模式

**功能覆盖：**
- 用户端：首页 / AI 推荐 / 发现 / 订单（下单 → 支付 → 详情 → 评价）/ 钱包 / 优惠券 / 积分商城 / 任务中心 / 收藏 / 地址 / 超级会员 / 贪吃蛇 / 我的
- 商家端：登录 / 仪表盘 / 订单管理 / 菜品管理 / 店铺信息 / 数据统计 / 评论管理
- 骑手端：登录 / 任务大厅 / 订单配送 / 我的钱包 / 提现 / 订单历史

### AI 推荐功能（客户端）

新版 React 客户端内置 AI 推荐模块，位于底部导航栏，提供对话式「吃什么」智能建议。

- **页面路由**：`/aiRecommend`
- **交互形式**：聊天气泡 + 预设快捷问题
- **核心能力**：
  - 基于用户历史订单的个性化推荐
  - 预算约束下的店铺/菜品推荐
  - 实时对话式交互

**预设问题模板：**
- "我现在可以吃什么？"
- "有没有什么好吃的店铺推荐？"
- "预算30元，推荐一份晚餐"
- "附近有什么评分高的店？"

**AI 服务接入（默认本地）：**
```
GET  /api/v1/models                    # 获取可用模型列表
POST /api/v1/chat                      # 对话接口
POST /api/v1/models/load               # 加载模型
POST /api/v1/models/download           # 下载模型
GET  /api/v1/models/download/status    # 查询下载状态
```

示例调用：
```bash
curl http://localhost:1234/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-e2b",
    "system_prompt": "你是一个外卖推荐助手，根据用户需求推荐合适的餐厅和菜品。",
    "input": "预算50元，两个人，想吃辣的"
  }'
```

示例：

```bash
curl http://localhost:1234/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-e2b",
    "system_prompt": "You answer only in rhymes.",
    "input": "What is your favorite color?"
}'
```

---

## 启动顺序建议

推荐使用 Docker 一步启动：

1. `docker compose up -d --build`
2. `docker compose ps` 确认服务健康
3. 访问三个前端端口验证
4. 若使用 AI 推荐功能，确认本地 `1234` AI 服务已启动

---

## 与之前版本相比的新技术栈与优势

相较于之前的单体版本，这个项目最大的变化是：**从单体应用升级为微服务架构**。

### 新技术栈

- **Spring Cloud Eureka**
- **Spring Cloud Gateway**
- **Spring Cloud OpenFeign**
- **Spring Cloud Config**
- **微服务集群化部署**
- **服务间远程调用与降级设计**

### 优势

- **[更清晰的业务拆分]**
  - 用户、订单、钱包、积分、任务、活动各自独立

- **[更高的可维护性]**
  - 单个服务职责单一，修改影响范围更小

- **[更好的扩展性]**
  - 高流量模块可单独扩容，例如订单服务、网关、注册中心

- **[更强的容错性]**
  - 注册中心集群、配置中心集群、服务调用降级都提升了系统稳定性

- **[更适合团队协作]**
  - 不同成员可并行开发不同服务，减少代码冲突

- **[更符合真实企业项目形态]**
  - 具备服务治理、网关、配置中心、远程调用、容错等完整微服务基础设施

---

## 说明

实际运行时，请以 `docker compose` 与 `docker-start.sh` 为准。

## Docker 快速参考

### 一键启动全栈
```bash
docker compose up -d --build
```

### 单独重启前端（开发调试）
```bash
# 用户端
docker compose up -d --build elmclient-react

# 商家端
docker compose up -d --build elmbusiness-react

# 骑手端
docker compose up -d --build elmdeliver-react
```

### 查看服务健康状态
```bash
docker compose ps
docker compose logs -f gateway
```

### 常用端口速查
| 服务 | 端口 | 说明 |
|------|------|------|
| 用户端 (React) | 8093 | 新版推荐 |
| 商家端 (React) | 8094 | 新版推荐 |
| 骑手端 (React) | 8095 | 新版推荐 |
| 用户端 (Vue) | 8090 | 旧版兼容 |
| 商家端 (Vue) | 8091 | 旧版兼容 |
| 骑手端 (Vue) | 8092 | 旧版兼容 |
| Gateway | 8080 | API 网关 |
| Eureka | 8761 | 注册中心 |
| MySQL | 3307 | 数据库 |
| Redis | 6379 | 缓存 |