项目结构

深入了解 HEI FastAPI 的模块组织和分层设计。

总体架构

HEI FastAPI 采用模块化单体架构，通过清晰的目录结构实现边界划分。

hei-fastapi/
├── config/                          # 配置模块
│   └── settings.py                  # Pydantic BaseSettings（支持 env 覆盖）
├── core/                            # 核心模块
│   ├── app/                         # 应用设置
│   │   ├── setup.py                 # FastAPI 应用工厂
│   │   ├── router.py                # 路由注册（手动注册所有模块 router）
│   │   ├── lifespan.py              # 生命周期（DB/Redis/SM2/JWT/权限初始化）
│   │   └── health.py                # 健康检查 GET /
│   ├── auth/                        # 认证授权
│   │   ├── auth/                    # 认证工具
│   │   │   ├── hei_auth_tool.py     # B 端 JWT 认证工具
│   │   │   └── hei_client_auth_tool.py  # C 端 JWT 认证工具
│   │   ├── decorator/               # 权限装饰器
│   │   │   ├── hei_check_login.py         # @HeiCheckLogin
│   │   │   ├── hei_check_permission.py    # @HeiCheckPermission("module:action")
│   │   │   ├── hei_check_role.py          # @HeiCheckRole("admin")
│   │   │   ├── hei_client_check_login.py  # C 端 @HeiClientCheckLogin
│   │   │   └── hei_client_check_permission.py  # C 端 @HeiClientCheckPermission
│   │   ├── permission/              # 权限查询接口
│   │   │   ├── hei_permission_interface.py         # 权限查询接口定义
│   │   │   ├── hei_permission_interface_manager.py  # 接口管理器
│   │   │   └── hei_permission_tool.py               # 权限查询门面
│   │   └── permission_scan.py       # 权限自动扫描（启动时扫描装饰器 → Redis）
│   ├── db/                          # 数据库连接
│   │   ├── mysql.py                 # SQLAlchemy 同步引擎 + sessionmaker
│   │   ├── base_dao.py              # BaseDAO 通用 CRUD（软删除透明过滤）
│   │   └── redis.py                 # Redis 异步客户端（redis-py）
│   ├── middleware/                  # 中间件
│   │   ├── auth.py                  # AuthMiddleware（按路径分流 B/C/Public）
│   │   ├── cors.py                  # CORS 中间件
│   │   └── exception.py             # 全局异常处理
│   ├── result/                      # 统一返回
│   │   └── result.py                # success() / failure() / page_data()
│   ├── exception/                   # 异常定义
│   │   └── business_exception.py    # BusinessException
│   ├── enums/                       # 枚举类型
│   │   ├── data_scope_enum.py       # 数据范围枚举（ALL/CUSTOM/ORG/ORG_AND_BELOW/SELF）
│   │   ├── status_enum.py           # 状态枚举
│   │   ├── soft_delete_enum.py      # 软删除枚举
│   │   ├── export_type_enum.py      # 导出类型枚举
│   │   └── ...                      # 其他枚举
│   ├── pojo/                        # 公共数据对象
│   │   ├── page_bounds.py           # 分页参数（PageBounds）
│   │   └── ...                      # IdParam, IdsParam 等
│   └── utils/                       # 工具类
│       ├── sm2_crypto_util.py       # SM2 国密加解密
│       ├── excel_utils.py           # Excel 导出导入
│       ├── ip_utils.py              # 客户端 IP 提取
│       ├── snowflake_utils.py       # 雪花 ID 生成
│       └── model_utils.py           # 模型工具（系统字段剥离、更新、模板）
├── modules/                         # 业务模块
│   ├── auth/                        # 认证模块
│   │   ├── captcha/                 # 图形验证码生成与校验
│   │   └── username/                # 用户名密码登录/注册/登出
│   ├── sys/                         # 系统管理模块
│   │   ├── banner/                  # Banner 管理
│   │   ├── dict/                    # 字典管理（树形结构）
│   │   ├── group/                   # 用户组管理
│   │   ├── notice/                  # 通知管理
│   │   ├── org/                     # 组织管理
│   │   ├── permission/              # 权限管理
│   │   ├── position/                # 职位管理
│   │   ├── resource/                # 资源与模块管理
│   │   ├── role/                    # 角色管理（含权限/资源分配）
│   │   └── user/                    # 用户管理（含角色/组分配）
│   ├── client/                      # C 端模块
│   │   └── user/                    # C 端用户管理
│   └── dev/                         # 代码生成器
│       ├── gen_basic_service.py     # 表信息读取 + 代码生成
│       ├── gen_config_service.py    # 字段配置
│       ├── type_utils.py            # 类型映射工具
│       └── templates/               # Jinja2 模板
├── scripts/                         # 脚本文件
│   └── sqls/
│       └── hei_ddl.sql              # 数据库建表 DDL
├── .env                             # 环境配置
├── main.py                          # 应用入口
├── pyproject.toml                   # 项目配置
└── requirements.txt                 # 依赖列表

模块职责

config（配置模块）

应用配置管理，使用 pydantic-settings 读取环境变量：

AppConfig: 应用名称、版本、端口、调试模式
DatabaseConfig: MySQL 连接信息 + 连接池 + 软删除配置
RedisConfig: Redis 连接信息 + 连接池配置
JWTConfig: Token 签发参数
SM2Config: 国密密钥对
CORSConfig: 跨域配置
SnowflakeConfig: 雪花算法实例 ID

core（核心模块）

最基础的公共模块，被所有业务模块依赖：

app: FastAPI 应用创建、路由注册、生命周期管理、健康检查
auth: 认证装饰器、JWT 认证工具、权限查询接口、权限自动扫描
db: MySQL 引擎 + sessionmaker、BaseDAO 通用 CRUD、Redis 客户端
middleware: CORS、认证（按路径分流）、全局异常处理
result: 统一返回结构 success() / failure() / page_data()
exception: BusinessException 业务异常
enums: 数据范围、状态、导出类型、软删除等枚举
pojo: 分页参数、ID 参数等公共数据对象
utils: SM2 加密、Excel、IP、雪花ID、模型工具等

modules（业务模块）

按业务领域划分的具体实现模块：

模块路径	说明	主要功能
`auth/captcha`	验证码	图形验证码生成与校验
`auth/username`	用户名认证	B 端登录/注册/登出，SM2 解密 + bcrypt 验证
`sys/banner`	Banner 管理	Banner 轮播图 CRUD
`sys/dict`	字典管理	树形字典，支持父子层级和分类
`sys/group`	用户组管理	用户组 CRUD + 角色分配
`sys/notice`	通知管理	系统通知 CRUD
`sys/org`	组织管理	组织架构 CRUD
`sys/permission`	权限管理	系统权限 CRUD + 模块列表查询
`sys/position`	职位管理	职位 CRUD
`sys/resource`	资源与模块管理	模块 + 菜单资源 CRUD
`sys/role`	角色管理	角色 CRUD + 权限/资源分配
`sys/user`	用户管理	用户 CRUD + 角色/组分配
`client/user`	C 端用户管理	客户端用户 CRUD（C 端认证）
`dev`	代码生成器	从数据库表自动生成完整 CRUD 模块

垂直切片设计

每个业务模块遵循标准的分层架构，每模块一组 5 个文件：

modules/<domain>/
├── models.py        # SQLAlchemy ORM 模型（Mapped + mapped_column）
├── params.py        # Pydantic v2 请求/响应模型（VO, PageParam, ExportParam, ImportParam）
├── dao.py           # 数据访问层（继承 BaseDAO）
├── service.py       # 业务逻辑层
└── api/v1/api.py    # FastAPI 路由定义 + @HeiCheckPermission 装饰器

数据流

请求 → [中间件] → [路由] → [权限装饰器] → [Service] → [DAO] → 数据库
                                         ↓
                                    Result 统一响应 → 返回

模块结构约定

每个业务模块的 API 端点遵循统一的命名规范：

端点	方法	权限标识	说明
`/{module}/page`	GET	`{module}:page`	分页查询
`/{module}/create`	POST	`{module}:create`	新增
`/{module}/modify`	POST	`{module}:modify`	修改
`/{module}/remove`	POST	`{module}:remove`	删除（支持批量）
`/{module}/detail`	GET	`{module}:detail`	详情
`/{module}/export`	GET	`{module}:export`	Excel 导出
`/{module}/template`	GET	`{module}:template`	导入模板下载
`/{module}/import`	POST	`{module}:import`	Excel 导入
`/{module}/grant-*`	POST	`{module}:grant*`	分配关联（如角色分配权限）
`/{module}/own-*`	GET	`{module}:own*`	获取已分配关联

统一返回结构

所有接口统一使用标准封装返回结果：

json

{
  "code": 200,
  "message": "请求成功",
  "data": { ... },
  "success": true
}

分页返回：

json

{
  "code": 200,
  "message": "请求成功",
  "data": {
    "records": [...],
    "total": 100,
    "page": 1,
    "size": 20,
    "pages": 5
  },
  "success": true
}

认证中间件

AuthMiddleware 自动根据 API 路径进行认证检查：

python

# 路径匹配规则
PUBLIC_B_PATTERN     = r"^/api/v\d+/public/b/"      # B端公开
PUBLIC_C_PATTERN     = r"^/api/v\d+/public/c/"      # C端公开
PRIVATE_C_PATTERN    = r"^/api/v\d+/c/"              # C端私有
PRIVATE_B_PATTERN    = r"^/api/v\d+/b/"              # B端私有（显式）
DEFAULT_B_PATTERN    = r"^/api/v\d+/(?!b|c|public)[^/]+/"  # B端私有（默认）

权限装饰器

B 端权限装饰器

python

from core.auth.decorator import HeiCheckLogin, HeiCheckRole, HeiCheckPermission

@router.get("/api/v1/sys/example/page")
@HeiCheckPermission("sys:example:page")
async def page(request: Request, db: Session = Depends(get_db)):
    return success(service.page(param))

装饰器必须位于 @router.* 下方（紧贴函数）。

C 端权限装饰器

python

from core.auth.decorator import HeiClientCheckLogin, HeiClientCheckPermission

@router.get("/api/v1/c/example/page")
@HeiClientCheckPermission("c:example:page")
async def c_page(request: Request, db: Session = Depends(get_db)):
    return success(service.page(param))

权限数据链路

User ──→ RalUserRole ──→ Role ──→ RalRolePermission ──→ Permission
User ──→ RalUserGroup ──→ Group ──→ RalGroupRole ──→ Role ──→ ...
User ──→ RalUserPermission ──→ Permission (直授)

数据范围存储在关系表中，多角色多路径下按最严策略合并。

Skills

Create New Modules

Create New Modules Code

Skills

Create New Modules

Create New Modules Code

项目结构

总体架构

模块职责

config（配置模块）

core（核心模块）

modules（业务模块）

垂直切片设计

数据流

模块结构约定

统一返回结构

认证中间件

权限装饰器

B 端权限装饰器

C 端权限装饰器

权限数据链路

Create New Modules

Create New Modules Code

Create New Modules

Create New Modules Code

项目结构 ​

总体架构 ​

模块职责 ​

config（配置模块） ​

core（核心模块） ​

modules（业务模块） ​

垂直切片设计 ​

数据流 ​

模块结构约定 ​

统一返回结构 ​

认证中间件 ​

权限装饰器 ​

B 端权限装饰器 ​

C 端权限装饰器 ​

权限数据链路 ​

项目结构

总体架构

模块职责

config（配置模块）

core（核心模块）

modules（业务模块）

垂直切片设计

数据流

模块结构约定

统一返回结构

认证中间件

权限装饰器

B 端权限装饰器

C 端权限装饰器

权限数据链路