项目结构
深入了解 HEI Cloud 的模块组织和分层设计。
总体架构
HEI Cloud 采用微服务架构，通过 Maven 多模块管理实现清晰的边界划分。
hei-cloud/
├── pom.xml # 根 POM，统一管理依赖版本
├── api/ # API 接口模块（供跨服务调用）
│ ├── pom.xml
│ ├── auth-api/ # 认证模块 API
│ │ └── src/main/java/io/github/jiangbyte/
│ │ ├── annotation/ # 认证相关注解
│ │ │ ├── SaClientCheckLogin.java
│ │ │ ├── SaClientCheckPermission.java
│ │ │ └── SaClientCheckRole.java
│ │ ├── api/ # 远程服务接口
│ │ │ ├── LoginUserApi.java
│ │ │ └── LoginClientUserApi.java
│ │ ├── config/ # 认证配置
│ │ ├── convert/ # 对象转换器
│ │ ├── pojo/ # 数据传输对象
│ │ │ ├── LoginUserInfo.java
│ │ │ └── LoginClientUserInfo.java
│ │ └── util/ # 工具类
│ │ └── StpClientUtil.java
│ ├── sys-api/ # 系统模块 API
│ ├── client-api/ # C 端模块 API
│ └── biz-api/ # 业务模块 API
├── common/ # 公共基础模块
│ ├── pom.xml
│ └── core/ # 公共核心模块
│ └── src/main/java/io/github/jiangbyte/
│ ├── config/ # 公共配置类
│ │ ├── RedisConfig.java
│ │ └── Ip2RegionConfig.java
│ ├── constant/ # 常量定义
│ │ ├── AuthConstant.java
│ │ └── GlobalConstants.java
│ ├── enums/ # 枚举定义
│ │ ├── ExportTypeEnum.java
│ │ └── StatusEnum.java
│ ├── exception/ # 异常类
│ │ └── BusinessException.java
│ ├── pojo/ # 基础对象
│ │ ├── BaseEntity.java
│ │ ├── BaseEntityWithTrans.java
│ │ ├── IdParam.java
│ │ ├── IdsParam.java
│ │ └── PageBounds.java
│ ├── result/ # 统一返回结构
│ │ ├── Result.java
│ │ ├── ResultCode.java
│ │ └── IResultCode.java
│ └── utils/ # 工具类
│ ├── IpUtils.java
│ ├── IpRegionResult.java
│ ├── Sm2CryptoUtil.java
│ └── FesodUtils.java
├── modules/ # 业务实现模块
│ ├── pom.xml
│ ├── auth/ # 认证模块实现
│ │ └── src/main/java/io/github/jiangbyte/
│ │ ├── config/ # 模块配置
│ │ │ └── Sm2Config.java
│ │ └── logic/ # 业务逻辑
│ │ └── UsernameAuthLogic.java
│ ├── sys/ # 系统模块实现（规划中）
│ ├── client/ # C 端模块实现（规划中）
│ └── biz/ # 业务模块实现（规划中）
├── apps/ # 启动模块（规划中）
│ └── pom.xml
└── scripts/ # 脚本工具
├── sqls/ # SQL 脚本
│ └── 260603.sql
└── sm2-encrypt.js # SM2 加密工具模块职责
common/core（公共核心）
最基础的公共模块，被所有其他模块依赖。提供：
- 基础实体类:
BaseEntity、BaseEntityWithTrans - 统一返回:
Result<T>封装，包含分页数据结构 - 异常体系:
BusinessException - 工具类: 国密 SM2 加密、IP 解析、Fesod 工具等
api（API 接口模块）
存放跨服务调用的接口定义，实现 API 与实现分离：
- 模块 API: 定义其他服务需要对外暴露的服务接口
- DTO/VO: 跨服务传输的数据对象
- 注解: B端/C端认证、权限等注解定义
- 配置: Sa-Token 认证配置
modules（业务模块）
按业务领域划分的具体实现模块：
| 模块 | 说明 | 主要功能 |
|---|---|---|
auth | 认证模块 | 用户名密码登录、验证码、SM2 加密认证 |
sys | 系统模块 | 用户、角色、Banner 管理（规划中） |
client | C 端模块 | C 端用户管理（规划中） |
biz | 业务模块 | 业务功能扩展（规划中） |
apps（启动模块）
服务启动入口模块，负责：
- 应用启动类
- 多环境配置文件
- 模块聚合依赖
分层设计
每个业务模块内部遵循标准的三层架构：
├── controller/ # 控制层：接收请求，参数校验，调用 service
├── service/ # 业务层：业务逻辑处理，事务管理
│ └── impl/ # 服务实现
├── mapper/ # 数据层：数据库操作
├── entity/ # 实体类：数据库表映射
├── params/ # 参数类：接收前端参数的 DTO
├── result/ # 返回类：响应数据封装
└── convert/ # 转换器：MapStruct 对象转换数据流示例
请求 → Controller → Service → Mapper → 数据库
↓
Entity → Convert → 返回实体继承体系
BaseEntity（基础实体）
java
BaseEntity
├── isDeleted # 逻辑删除标识
├── createdBy # 创建者 ID
├── updatedBy # 更新者 ID
├── createdAt # 创建时间
└── updatedAt # 更新时间BaseEntityWithTrans（带翻译的实体）
继承 BaseEntity 并实现 TransPojo 接口，支持 Easy-Trans 数据翻译。
统一返回结构
所有接口统一使用 Result<T> 封装返回结果：
json
{
"code": 200,
"success": true,
"message": "操作成功",
"data": { ... }
}分页返回使用 Result.PageData<T> 或直接返回 Page<T>：
json
{
"code": 200,
"success": true,
"data": {
"records": [...],
"total": 100,
"pages": 10,
"size": 10,
"current": 1
}
}