架构设计

本文档详细说明 HEI Boot 的架构设计理念。项目的基础架构思想参考了 Snowy 快速开发平台。

设计原则

1. 模块化单体架构

HEI Boot 采用模块化单体架构（Modular Monolith），在保持单体应用部署简单性的同时，通过模块边界实现关注点分离：

• 部署简单: 单个 JAR 即可运行，无需复杂的分布式基础设施
• 模块清晰: 按业务领域划分模块，每个模块职责明确
• 低耦合: 模块间通过 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 Boot 继承了这一安全理念：

场景	技术方案
密码传输	SM2 非对称加密，前端公钥加密，后端私钥解密
Token 认证	Sa-Token + JWT（为了兼容其他 Hei 系列的实现）
权限控制	基于 RBAC 的注解权限

4. 前后端分离

• 后端: 专注提供 RESTful API，无页面渲染逻辑
• 前端: 独立部署的 Vue3 SPA，通过 API 交互
• 接口文档: Knife4j 自动生成 OpenAPI 3 规范文档

技术架构

整体分层

┌─────────────────────────────────────────────────────────┐
│                       app (启动层)                       │
│                   应用启动 + 配置聚合                       │
├─────────────────────────────────────────────────────────┤
│                  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      │
└─────────────────────────────────────────────────────────┘

模块依赖关系

app
├── 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 自动填充