架构设计
本文档详细说明 HEI Cloud 的架构设计理念。项目的基础架构思想参考了 Snowy 快速开发平台。
设计原则
1. 微服务架构
HEI Cloud 采用微服务架构，将单体应用拆分为多个独立的服务：
- 服务独立部署: 每个服务可以独立部署和扩展
- 服务自治: 每个服务拥有独立的数据库和业务逻辑
- 松耦合: 服务间通过 API 通信，降低依赖
- 高可用: 支持服务熔断、降级、负载均衡
2. API 与实现分离
参考 Snowy 的设计理念，将模块的 API 定义与具体实现分离：
api/ # API 定义（接口、DTO）
├── auth-api/ # 认证模块对外暴露的接口
├── sys-api/ # 系统模块对外暴露的接口
├── client-api/ # C 端模块对外暴露的接口
└── biz-api/ # 业务模块对外暴露的接口
modules/ # 具体实现
├── auth/ # 认证模块实现（依赖 auth-api）
├── sys/ # 系统模块实现（依赖 sys-api）
├── client/ # C 端模块实现
└── biz/ # 业务模块实现设计优势：
- 服务间调用只依赖 API 接口，不引入实现模块的完整依赖树
- 模块内部实现可以自由重构，不影响外部调用方
- 便于服务拆分和独立部署
3. 国密安全体系
Snowy 是国内首个国密前后端分离的快速开发平台，HEI Cloud 继承了这一安全理念：
| 场景 | 技术方案 |
|---|---|
| 密码传输 | SM2 非对称加密，前端公钥加密，后端私钥解密 |
| Token 认证 | Sa-Token + JWT（为了兼容其他 Hei 系列的实现） |
| 权限控制 | 基于 RBAC 的注解权限 |
4. 前后端分离
- 后端: 专注提供 RESTful API，无页面渲染逻辑
- 前端: 独立部署的 Vue3 SPA，通过 API 交互
- 接口文档: Knife4j 自动生成 OpenAPI 3 规范文档
技术架构
整体分层
┌─────────────────────────────────────────────────────────┐
│ apps (启动层) │
│ 应用启动 + 配置聚合 │
├─────────────────────────────────────────────────────────┤
│ modules (业务模块层) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ auth │ │ sys │ │ client │ │ biz │ │
│ │ 认证模块 │ │ 系统模块 │ │ C 端模块 │ │ 业务模块 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────┤
│ api (API 接口层) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ auth-api │ │ sys-api │ │client-api│ │ biz-api │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────┤
│ common/core (公共核心层) │
│ 实体 · 异常 · 工具 · 结果封装 · 常量定义 │
├─────────────────────────────────────────────────────────┤
│ 技术栈支撑层 │
│ Spring Boot 3.5.9 · MyBatis-Plus · Sa-Token · Redis │
└─────────────────────────────────────────────────────────┘模块依赖关系
apps
├── modules-auth ──→ auth-api ──→ common-core
├── modules-sys ──→ sys-api ──→ common-core
├── modules-client
├── modules-biz
└── common-core请求处理流程
HTTP 请求
↓
[过滤器链] IP 解析
↓
[Sa-Token 拦截器] Token 校验
↓
[Controller] 接收请求，参数校验
↓
[Service] 业务逻辑处理
↓
[Mapper] 数据访问
↓
[数据库] MySQL核心架构组件
认证授权体系
┌─────────────────────────────────────────┐
│ Sa-Token 认证网关 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 登录校验 │ │ 权限校验 │ │ 角色校验 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────┤
│ SM2 国密加密层 │
│ 密码加密传输，防中间人攻击 │
├─────────────────────────────────────────┤
│ JWT Token 签发 │
│ 独立 Redis 存储，30 天有效期 │
└─────────────────────────────────────────┘B/C 端双认证体系
项目支持 B 端和 C 端两套独立的认证体系：
| 端 | 用户表 | 认证工具 | 注解 |
|---|---|---|---|
| B 端 | sys_user | StpUtil | @SaCheckLogin、@SaCheckPermission、@SaCheckRole |
| C 端 | client_user | StpClientUtil | @SaClientCheckLogin、@SaClientCheckPermission、@SaClientCheckRole |
数据访问层
┌─────────────────────────────────────────┐
│ MyBatis-Plus 持久层 │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ 逻辑删除 │ │ 自动填充 │ │ 分页插件│ │
│ └──────────┘ └──────────┘ └────────┘ │
├─────────────────────────────────────────┤
│ Easy-Trans 数据翻译 │
│ 自动翻译字典、关联字段 │
└─────────────────────────────────────────┘约定优于配置
| 约定 | 说明 |
|---|---|
| 包命名 | io.github.jiangbyte.modules.{业务}.{模块} |
| API 路径 | /api/{版本}/{模块}/{操作} |
| 权限标识 | {模块}/{操作} 如 sys/user/page |
| 返回格式 | 统一 Result<T> 封装 |
| 主键策略 | 雪花算法 ASSIGN_ID |
| 逻辑删除 | is_deleted 字段 |
| 审计字段 | createdBy、updatedBy、createdAt、updatedAt 自动填充 |
与 Hei Boot 的区别
| 特性 | Hei Boot | Hei Cloud |
|---|---|---|
| 架构 | 单体应用 | 微服务架构 |
| 部署 | 单个 JAR | 多服务独立部署 |
| 数据库 | 共享数据库 | 服务独立数据库 |
| 通信 | 方法调用 | RPC/HTTP 调用 |
| 配置中心 | 无 | Nacos（规划中） |
| 服务网关 | 无 | Spring Cloud Gateway（规划中） |