Files
lyzsys_backend/doc/架构设计.md
2026-01-19 18:34:10 +08:00

735 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Lyzsys 架构设计文档
## 📖 目录
- [架构概述](#架构概述)
- [架构设计原则](#架构设计原则)
- [分层架构](#分层架构)
- [模块化设计](#模块化设计)
- [数据架构](#数据架构)
- [安全架构](#安全架构)
- [技术架构](#技术架构)
- [部署架构](#部署架构)
- [性能优化](#性能优化)
- [扩展性设计](#扩展性设计)
---
## 架构概述
### 整体架构
Lyzsys 采用**前后端分离**的**模块化单体架构**,基于**领域驱动设计DDD**思想进行模块划分,支持未来向微服务架构演进。
```
┌─────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web 浏览器 │ │ 移动 App │ │ 小程序 │ │
│ │ (Vue3) │ │ (UniApp) │ │ (UniApp) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 接入层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Nginx / │ │ API 网关 │ │ 负载均衡 │ │
│ │ CDN │ │ (可选) │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 应用层 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ lyzsys-server │ │
│ │ (Spring Boot 应用) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Controller │ │ Service │ │ DAL │ │ │
│ │ │ 层 │ │ 层 │ │ 层 │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│lyzsys-module-│ │lyzsys-module-xxx │ │lyzsys-module-│
│ system │ │ (业务模块) │ │ infra │
└──────────────┘ └──────────────────┘ └──────────────┘
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│lyzsys- │ │lyzsys-framework │ │lyzsys- │
│dependencies │ │ (框架组件) │ │common │
└──────────────┘ └──────────────────┘ └──────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MySQL │ │ Redis │ │ MinIO │ │
│ │ (主数据库) │ │ (缓存) │ │ (文件存储) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 外部服务 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ AI 服务 │ │ 短信服务 │ │ 支付服务 │ │
│ │ (OpenAI等) │ │ (阿里云等) │ │ (微信等) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 架构特点
1. **前后端分离**: 前端和后端独立开发、部署、扩展
2. **模块化设计**: 业务模块独立,低耦合、高内聚
3. **分层架构**: 清晰的分层,职责明确
4. **微服务就绪**: 模块化设计便于微服务化改造
5. **多租户支持**: 原生支持 SaaS 多租户场景
6. **高可用**: 支持集群部署,无状态设计
---
## 架构设计原则
### 1. 单一职责原则 (SRP)
每个模块、每个类只负责一个职责。
**示例**:
- `UserController` 只负责接收 HTTP 请求
- `UserService` 只负责业务逻辑处理
- `UserMapper` 只负责数据库操作
### 2. 开闭原则 (OCP)
对扩展开放,对修改关闭。
**示例**:
- 通过实现接口扩展功能,而非修改原有代码
- 使用策略模式实现不同的支付方式
### 3. 里氏替换原则 (LSP)
子类可以替换父类。
**示例**:
- `UserServiceImpl` 可以替换 `UserService`
- `BaseMapperX` 可以替换 `BaseMapper`
### 4. 接口隔离原则 (ISP)
使用多个细粒度的接口,而非单一的总接口。
**示例**:
- `UserService``RoleService``MenuService` 各司其职
- 前端 API 按模块划分(`/system/user``/system/role`
### 5. 依赖倒置原则 (DIP)
高层模块不依赖低层模块,都依赖于抽象。
**示例**:
- Controller 依赖 Service 接口,而非实现
- Service 依赖 Mapper 接口,而非实现
### 6. 迪米特法则 (LoD)
最少知识原则,模块之间尽量少交互。
**示例**:
- 模块之间通过 API 接口交互
- 避免跨层调用(如 Controller 直接调用 Mapper
---
## 分层架构
### 应用分层
```
┌─────────────────────────────────────────────────────────────┐
│ Controller 层 │
│ • 接收 HTTP 请求 │
│ • 参数校验 │
│ • 调用 Service 层 │
│ • 返回响应 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Service 层 │
│ • 业务逻辑处理 │
│ • 事务控制 │
│ • 调用 DAL 层 │
│ • 返回处理结果 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ DAL 层 │
│ • 数据访问 │
│ • 数据库操作 │
│ • 缓存操作 │
│ • 返回数据对象 │
└─────────────────────────────────────────────────────────────┘
```
### 层次交互规则
1. **自上而下调用**: Controller → Service → DAL
2. **跨层访问**: 允许 Service 直接调用多个 DAL
3. **禁止反向调用**: 下层不能调用上层
4. **同层交互**: 同层之间通过接口交互
### 分层示例
#### Controller 层
```java
@RestController
@RequestMapping("/system/user")
@Tag(name = "管理后台 - 用户")
public class UserController {
@Autowired
private UserService userService;
@PostMapping("/create")
@Operation(summary = "创建用户")
public CommonResult<Long> createUser(@Valid @RequestBody UserCreateReqVO reqVO) {
return success(userService.createUser(reqVO));
}
@GetMapping("/get")
@Operation(summary = "获取用户详情")
public CommonResult<UserRespVO> getUser(@RequestParam("id") Long id) {
return success(userService.getUser(id));
}
}
```
#### Service 层
```java
@Service
public class UserServiceImpl implements UserService {
@Autowired
private UserMapper userMapper;
@Autowired
private DeptMapper deptMapper;
@Override
@Transactional(rollbackFor = Exception.class)
public Long createUser(UserCreateReqVO reqVO) {
// 业务逻辑
UserDO user = UserConvert.INSTANCE.convert(reqVO);
userMapper.insert(user);
return user.getId();
}
@Override
public UserRespVO getUser(Long id) {
UserDO user = userMapper.selectById(id);
DeptDO dept = deptMapper.selectById(user.getDeptId());
return UserConvert.INSTANCE.convert(user, dept);
}
}
```
#### DAL 层
```java
@Mapper
public interface UserMapper extends BaseMapperX<UserDO> {
default UserDO selectByUsername(String username) {
return selectOne("username", username);
}
default PageResult<UserDO> selectPage(UserPageReqVO pageReqVO) {
return selectPage(pageReqVO, new LambdaQueryWrapperX<UserDO>()
.likeIfPresent(UserDO::getUsername, pageReqVO.getUsername())
.betweenIfPresent(UserDO::getCreateTime, pageReqVO.getCreateTime())
.orderByDesc(UserDO::getId));
}
}
```
---
## 模块化设计
### 模块划分
项目按照**领域驱动设计DDD**思想进行模块划分。
#### 基础模块
| 模块 | 职责 |
|------|------|
| lyzsys-dependencies | 依赖版本管理 |
| lyzsys-framework | 框架组件封装 |
| lyzsys-server | 应用启动入口 |
#### 业务模块
| 模块 | 领域 | 职责 |
|------|------|------|
| lyzsys-module-system | 系统管理 | 用户、角色、菜单、部门、字典等 |
| lyzsys-module-infra | 基础设施 | 代码生成、文件、配置、任务等 |
| lyzsys-module-bpm | 工作流 | 流程定义、流程实例、任务管理 |
| lyzsys-module-pay | 支付 | 支付订单、退款、回调 |
| lyzsys-module-member | 会员 | 会员、积分、等级 |
| lyzsys-module-mall | 商城 | 商品、订单、营销 |
| lyzsys-module-crm | CRM | 客户、商机、合同 |
| lyzsys-module-erp | ERP | 采购、销售、库存 |
| lyzsys-module-ai | AI | AI 聊天、绘图、知识库 |
| lyzsys-module-mp | 微信公众号 | 公众号管理、粉丝、消息 |
| lyzsys-module-iot | IoT | 设备、产品、数据采集 |
| lyzsys-module-report | 报表 | 报表设计、大屏设计 |
### 模块结构
每个业务模块都遵循统一的结构:
```
lyzsys-module-xxx/
├── api/ # 对外 API
│ ├── xxxApi.java
│ └── xxxApiImpl.java
├── controller/ # 控制器
│ ├── admin/ # 管理后台 API
│ │ ├── xxxController.java
│ │ └── vo/
│ │ ├── xxxReqVO.java
│ │ └── xxxRespVO.java
│ └── app/ # 用户 App API
│ └── xxxController.java
├── service/ # 服务层
│ ├── xxxService.java
│ └── xxxServiceImpl.java
├── dal/ # 数据访问层
│ ├── dataobject/ # 数据对象
│ │ └── xxxDO.java
│ ├── mysql/ # MySQL Mapper
│ │ └── xxxMapper.java
│ └── redis/ # Redis DAO
│ └── xxxRedisDAO.java
├── convert/ # 对象转换
│ └── xxxConvert.java
├── enums/ # 枚举
│ └── xxxEnum.java
└── framework/ # 框架配置
└── xxxConfiguration.java
```
### 模块交互
#### 模块间调用规则
1. **禁止直接依赖**: 模块之间不能直接依赖
2. **通过 API 调用**: 通过 API 接口进行调用
3. **事件驱动**: 通过消息队列进行异步通信
#### 示例
```java
// mall 模块调用 pay 模块
@DubboReference
private PayOrderApi payOrderApi;
public void createOrder(OrderCreateReqVO reqVO) {
// 创建订单
OrderDO order = createOrder(reqVO);
// 调用支付模块
PayOrderCreateReqDTO payReq = new PayOrderCreateReqDTO();
payReq.setOrderId(order.getId());
payOrderApi.createOrder(payReq);
}
```
---
## 数据架构
### 数据存储
```
┌─────────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MySQL │ │ Redis │ │ MinIO │ │
│ │ (主数据库) │ │ (缓存) │ │ (文件存储) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 数据库设计
#### 表命名规范
- 格式: `{模块}_{业务}_{实体}`
- 示例: `system_users``system_roles``mall_orders`
#### 字段命名规范
- 小写字母 + 下划线
- 示例: `user_id``user_name``create_time`
#### 通用字段
每张表都包含以下通用字段:
```sql
id BIGINT 主键
create_time DATETIME 创建时间
update_time DATETIME 更新时间
creator VARCHAR(64) 创建人
updater VARCHAR(64) 更新人
deleted BIT 是否删除
tenant_id BIGINT 租户 ID (多租户表)
```
### 多租户数据隔离
#### 策略
- **共享数据库、共享 Schema**: 所有租户共享数据库,通过 `tenant_id` 隔离
- **自动过滤**: MyBatis Plus 拦截器自动添加租户条件
#### 实现
```java
@TableName("system_users")
public class UserDO extends TenantBaseDO {
private Long id;
private String username;
// tenant_id 由 TenantBaseDO 提供
}
// 查询时自动过滤
List<UserDO> users = userMapper.selectList();
// SQL: SELECT * FROM system_users WHERE deleted = 0 AND tenant_id = ?
```
### 缓存设计
#### 缓存策略
1. **本地缓存**: Caffeine本地缓存
2. **分布式缓存**: Redis分布式缓存
#### 缓存使用
```java
// 使用 Spring Cache
@Cacheable(value = "user", key = "#id")
public UserDO getUser(Long id) {
return userMapper.selectById(id);
}
// 使用 RedisTemplate
@Service
public class UserServiceImpl {
@Autowired
private RedisTemplate<String, UserDO> redisTemplate;
public UserDO getUser(Long id) {
String key = "user:" + id;
UserDO user = redisTemplate.opsForValue().get(key);
if (user == null) {
user = userMapper.selectById(id);
redisTemplate.opsForValue().set(key, user, 1, TimeUnit.HOURS);
}
return user;
}
}
```
---
## 安全架构
### 认证授权
#### 认证流程
```
1. 用户登录
2. 后端验证用户名密码
3. 生成 JWT Token
4. 返回 Token 给前端
5. 前端存储 Token
6. 后续请求携带 Token
7. 后端验证 Token
8. 允许访问
```
#### 授权模型
```
用户 (User)
角色 (Role)
权限 (Permission)
资源 (Resource)
```
### 数据权限
#### 权限范围
| 权限范围 | 说明 |
|---------|------|
| 全部数据权限 | 查看所有数据 |
| 本部门数据权限 | 只能查看本部门数据 |
| 本部门及以下数据权限 | 查看本部门及子部门数据 |
| 仅本人数据权限 | 只能查看自己的数据 |
| 自定义数据权限 | 自定义数据权限规则 |
#### 实现
```java
@DataScope(deptAlias = "d", userAlias = "u")
public List<UserDO> getUserList() {
return userMapper.selectList();
}
// SQL 自动添加
// AND (d.id = ? OR d.id IN (?, ?) OR u.id = ?)
```
### API 安全
#### 接口加密
```java
// 请求加密
@PostMapping("/create")
public CommonResult<Long> createUser(@RequestBody String encryptedData) {
// 解密
String json = decrypt(encryptedData);
UserCreateReqVO reqVO = JSON.parseObject(json, UserCreateReqVO.class);
// 业务处理
Long id = userService.createUser(reqVO);
// 加密返回
return success(encrypt(id));
}
```
#### 接口签名
```java
// 请求签名
@PostMapping("/create")
public CommonResult<Long> createUser(
@RequestHeader("X-Signature") String signature,
@RequestBody UserCreateReqVO reqVO
) {
// 验证签名
if (!verifySignature(signature, reqVO)) {
return error(401, "签名验证失败");
}
// 业务处理
return success(userService.createUser(reqVO));
}
```
---
## 技术架构
### 技术选型
#### 后端技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 2.7.18 | 应用框架 |
| Spring Security | 5.8.16 | 安全框架 |
| MyBatis Plus | 3.5.15 | ORM 框架 |
| Flowable | 6.8.0 | 工作流引擎 |
| Quartz | 2.3.2 | 定时任务 |
| Redisson | 3.52.0 | 分布式锁 |
| Knife4j | 3.0.3 | API 文档 |
#### 前端技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.2+ | 前端框架 |
| TypeScript | 4.x | 类型系统 |
| Vite | 4.x | 构建工具 |
| Element Plus | 2.x | UI 组件库 |
| Pinia | 2.x | 状态管理 |
### 框架封装
#### Web 封装
- 全局异常处理
- 统一响应格式
- 请求日志记录
- 参数校验
#### 安全封装
- JWT 认证
- 权限注解
- 数据权限
- API 加密
#### 数据库封装
- BaseMapperX
- LambdaQueryWrapperX
- 分页插件
- 租户插件
---
## 部署架构
### 单机部署
```
┌─────────────────────────────────────────────────────────────┐
│ 服务器 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Nginx │ │ JDK 8 │ │ MySQL │ │
│ │ (前端) │ │ (后端) │ │ (数据库) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Redis │ │ MinIO │ │
│ │ (缓存) │ │ (文件存储) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 集群部署
```
┌─────────────────────────────────────────────────────────────┐
│ 负载均衡 │
│ (Nginx / F5) │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 应用服务器 1 │ │ 应用服务器 2 │ │ 应用服务器 3 │
│ (后端服务) │ │ (后端服务) │ │ (后端服务) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└────────────────┼────────────────┘
┌─────────────────┐
│ MySQL 主从 │
│ Redis 集群 │
└─────────────────┘
```
### 容器化部署
```
┌─────────────────────────────────────────────────────────────┐
│ Kubernetes 集群 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Pod 1 │ │ Pod 2 │ │ Pod 3 │ │
│ │ (后端服务) │ │ (后端服务) │ │ (后端服务) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MySQL │ │ Redis │ │ MinIO │ │
│ │ (StatefulSet)│ │ (StatefulSet)│ │ (Deployment)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 性能优化
### 数据库优化
1. **索引优化**: 合理创建索引
2. **SQL 优化**: 避免全表扫描
3. **分页查询**: 使用分页插件
4. **读写分离**: 主从数据库配置
5. **连接池**: Druid 连接池优化
### 缓存优化
1. **本地缓存**: Caffeine 本地缓存
2. **分布式缓存**: Redis 缓存
3. **缓存预热**: 系统启动时加载热点数据
4. **缓存更新**: 定时更新缓存
### 接口优化
1. **批量操作**: 批量插入、批量更新
2. **异步处理**: 消息队列异步处理
3. **接口合并**: 减少请求次数
4. **压缩传输**: Gzip 压缩
### 前端优化
1. **代码分割**: 路由懒加载
2. **资源压缩**: Gzip、Brotli 压缩
3. **CDN 加速**: 静态资源 CDN
4. **浏览器缓存**: 合理设置缓存策略
---
## 扩展性设计
### 水平扩展
1. **应用集群**: 多台应用服务器
2. **数据库集群**: 主从、分库分表
3. **缓存集群**: Redis 集群
4. **文件存储**: 分布式文件系统
### 垂直扩展
1. **升级硬件**: CPU、内存、磁盘
2. **优化配置**: JVM、数据库参数
### 微服务化
1. **模块拆分**: 按业务模块拆分
2. **服务注册**: Nacos、Eureka
3. **服务调用**: Dubbo、Feign
4. **网关路由**: Spring Cloud Gateway
---
**文档版本**: v1.0.0
**最后更新**: 2025-01-19
**维护团队**: Lyzsys 架构团队