架构概览

本文档详细说明 HEI FastAPI 的架构设计理念。

设计原则

1. 模块化单体架构

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

• 部署简单: 单个进程即可运行，无需复杂的分布式基础设施
• 模块清晰: 按业务领域划分模块，每个模块职责明确
• 低耦合: 模块间通过明确的接口通信，避免循环依赖
• 易扩展: 新业务功能可作为独立模块加入，不侵入现有代码

2. 国密安全体系

项目支持 SM2 国密加密，保障数据传输安全：

场景	技术方案
密码传输	SM2 非对称加密，前端公钥加密，后端私钥解密
密码存储	bcrypt 加盐哈希存储
Token 认证	JWT + Redis 服务端缓存
权限控制	基于装饰器的权限检查 + Redis 缓存权限定义

3. 前后端分离

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

4. 类型安全

基于 Pydantic v2 的数据验证：

• 请求验证: 自动验证请求参数类型
• 响应序列化: 自动序列化响应数据
• 类型提示: 基于 Mapped + mapped_column 的 ORM 类型注解

5. RBAC 三层权限模型

• 用户 → 角色 → 权限: 标准 RBAC 链路
• 用户 → 组 → 角色 → 权限: 通过用户组继承角色
• 用户 → 权限: 直授权限（覆盖模式）

技术架构

整体分层

┌─────────────────────────────────────────────────────────┐
│                    main.py (入口层)                       │
│                   应用启动 + Uvicorn                       │
├─────────────────────────────────────────────────────────┤
│                  modules (业务模块层)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │   auth   │  │   sys    │  │  client  │  │   dev    │ │
│  │  认证模块  │  │  系统模块  │  │ C端模块  │  │ 代码生成  │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘ │
├─────────────────────────────────────────────────────────┤
│              core (公共核心层)                           │
│  ┌──────┐  ┌────┐  ┌──────┐  ┌──────┐  ┌──────┐       │
│  │ auth │  │ db │  │result│  │utils │  │middle│       │
│  │认证授权│  │数据库 │  │统一返回│  │ 工具  │  │中间件  │       │
│  └──────┘  └────┘  └──────┘  └──────┘  └──────┘       │
├─────────────────────────────────────────────────────────┤
│              config (配置层)                             │
│      应用 · 数据库 · Redis · JWT · SM2 · CORS           │
├─────────────────────────────────────────────────────────┤
│                    技术栈支撑层                            │
│ FastAPI · SQLAlchemy · Pydantic · Redis · JWT            │
└─────────────────────────────────────────────────────────┘

请求处理流程

HTTP 请求
    ↓
[CORS 中间件] OPTIONS 预检直接返回
    ↓
[认证中间件] AuthMiddleware 按路径分流
    ├─ /api/v1/public/*   → 跳过认证
    ├─ /api/v1/c/*        → C 端 JWT 认证
    ├─ /api/v1/b/*        → B 端 JWT 认证
    └─ /api/v1/sys/*      → 默认 B 端 JWT 认证
    ↓
[异常处理中间件] 全局异常捕获
    ↓
[路由] FastAPI 分发到对应 API
    ↓
[权限装饰器] @HeiCheckPermission 权限检查（可选）
    ↓
[Service] 业务逻辑层处理
    ↓
[DAO] 数据访问层操作数据库
    ↓
MySQL / Redis

核心架构组件

认证授权体系

┌─────────────────────────────────────────────┐
│           认证中间件 (AuthMiddleware)          │
│  按路径自动分流 B 端 / C 端 / 公开接口         │
├─────────────────────────────────────────────┤
│           JWT 认证工具  (HeiAuthTool)         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ login()  │  │logout()  │  │isLogin() │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │getUserId │  │hasPerm() │  │getRole() │  │
│  └──────────┘  └──────────┘  └──────────┘  │
├─────────────────────────────────────────────┤
│         权限装饰器 (权限检查)                  │
│  ┌──────────────┐  ┌──────────────────┐     │
│  │登录检查 @Hei  │  │权限检查 @HeiCheck│     │
│  │CheckLogin    │  │Permission        │     │
│  └──────────────┘  └──────────────────┘     │
├─────────────────────────────────────────────┤
│          SM2 国密加密层                       │
│     密码加密传输，防中间人攻击                  │
├─────────────────────────────────────────────┤
│          bcrypt 密码哈希存储                  │
├─────────────────────────────────────────────┤
│          Redis Token 存储                   │
│     支持服务端主动失效（登出）                  │
└─────────────────────────────────────────────┘

B/C 端双认证体系

项目支持 B 端和 C 端两套独立的认证体系：

端	路径前缀	用户表	认证工具	登录装饰器	权限装饰器
B 端	/api/v1/b/* 或 /api/v1/sys/*	sys_user	HeiAuthTool	@HeiCheckLogin	@HeiCheckPermission
C 端	/api/v1/c/*	client_user	HeiClientAuthTool	@HeiClientCheckLogin	@HeiClientCheckPermission

API 路径规则

中间件根据 API 路径自动判断认证类型：

路径模式	说明	认证要求
/api/v1/public/b/*	B端公开接口	无需认证
/api/v1/public/c/*	C端公开接口	无需认证
/api/v1/b/*	B端私有接口	需要 B 端 JWT Token
/api/v1/c/*	C端私有接口	需要 C 端 JWT Token
/api/v1/sys/*	系统管理接口	需要 B 端 JWT Token

数据访问层

BaseDAO 通用 CRUD

所有 DAO 继承自 core.db.base_dao.BaseDAO，提供：

方法	说明
find_by_id(id)	按 ID 查询（自动过滤软删除）
find_by_ids(ids)	按 ID 列表批量查询
find_by_field(name, value)	按字段查询单条记录
find_all()	查询全部记录
find_page(current, size)	分页查询，返回 {records, total}
count_all()	统计总数
insert(entity)	新增记录（自动设置雪花ID和时间戳）
insert_batch(entities)	批量新增
update(entity)	更新记录（自动更新时间戳）
delete_by_id(id)	软删除：设置 is_deleted='YES'；物理删除：直接 DELETE
delete_by_ids(ids)	批量删除

软删除机制

• 默认全局启用，通过 DB__SOFT_DELETE_ENABLED 控制
• 查询自动加 WHERE is_deleted = 'NO' 条件
• 删除操作为 UPDATE SET is_deleted = 'YES'
• 每个业务模型通过 is_deleted 字段参与

启动生命周期

应用启动时依次执行以下初始化：

1. 数据库连接验证: 验证 MySQL 连通性
2. Redis 初始化: 建立 Redis 连接池
3. SM2 密钥加载: 加载国密密钥对
4. JWT 认证初始化: 配置 B 端和 C 端 JWT 工具
5. 权限管理接口注册: 注册 HeiPermissionInterface（运行时查询用户权限）
6. 权限自动扫描: 扫描所有路由的 @HeiCheckPermission 装饰器，缓存到 Redis
7. 验证码服务初始化: 绑定 Redis 客户端
8. 登录 API 注册: 注册 LoginUserApiProvider（从数据库查询用户信息）

约定优于配置

约定	说明
API 路径	/api/v1/{domain}/{module}/{action}
权限标识	{module}:{action} 如 sys:banner:page
返回格式	统一 {code, message, data, success} 封装
分页参数	current（当前页）、size（每页大小）
主键策略	雪花算法（Snowflake ID）
逻辑删除	is_deleted 字段（YES/NO）
审计字段	created_at、created_by、updated_at、updated_by

与 Hei Boot 的区别

特性	Hei Boot	Hei FastAPI
语言	Java 21	Python 3.13+
框架	Spring Boot 3.x	FastAPI 0.115+
ORM	MyBatis-Plus	SQLAlchemy 2.0
认证框架	Sa-Token	自研 JWT 工具
配置方式	YAML	Pydantic-Settings (.env)
部署	JAR + Servlet 容器	Uvicorn ASGI 服务