134 lines
5.9 KiB
Markdown
134 lines
5.9 KiB
Markdown
# 技术选型说明
|
||
|
||
本章详细阐述系统各技术组件的选型理由与版本约束说明，旨在帮助开发者理解技术选型的依据与权衡。
|
||
|
||
## 后端框架选型
|
||
|
||
### Tornado
|
||
|
||
:::tip 为什么选择 Tornado？
|
||
Tornado 是 Python 生态中成熟的异步 Web 框架，基于自有事件循环实现非阻塞 I/O。对于后台管理系统这类以 CRUD 为主的场景，Tornado 的轻量灵活和稳定可靠使其成为理想选择。
|
||
:::
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| **原生异步** | 基于自有事件循环，`async/await` 一等公民，充分利用 I/O 等待时间 |
|
||
| **请求校验** | Pydantic v2 声明式校验，Service 层自动执行 |
|
||
| **类型安全** | 全链路类型提示，IDE 补全完善 |
|
||
| **轻量灵活** | 核心概念少，无强依赖，学习曲线平缓 |
|
||
| **稳定可靠** | 成熟的生产级框架，广泛应用于高并发场景 |
|
||
|
||
### 选择 Tornado 的核心理由
|
||
|
||
1. **原生异步**：后台管理系统需要处理并发请求（文件上传、批量操作、定时任务），Tornado 的原生异步模型能充分利用 I/O 等待时间
|
||
2. **Pydantic 校验**：声明式的数据校验，减少参数校验代码量
|
||
3. **SQLAlchemy 解耦**：ORM 不与框架强绑定，支持多数据库驱动切换（MySQL / PostgreSQL / SQL Server / SQLite / Oracle）
|
||
4. **轻量灵活**：无强依赖，核心概念少，易于理解和扩展
|
||
5. **稳定可靠**：经过多年生产验证的成熟框架
|
||
|
||
## ORM 选型
|
||
|
||
### SQLAlchemy 2.0
|
||
|
||
:::tip 为什么选择 SQLAlchemy？
|
||
SQLAlchemy 是 Python 生态中最成熟、功能最完备的 ORM 框架，2.0 版本统一了 Core 和 ORM 的 API 风格，同时保持了对多种数据库方言的原生支持。
|
||
:::
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| **声明式模型** | 基于 `declarative_base()` 定义模型类，字段与数据库列一一映射 |
|
||
| **多数据库方言** | 通过 `DB_DRIVER` 切换 MySQL / PostgreSQL / SQL Server / SQLite / Oracle |
|
||
| **会话管理** | `scoped_session` + thread-local 实现请求级会话隔离 |
|
||
| **连接池** | 内置连接池（`QueuePool`），支持 `POOL_SIZE` / `MAX_OVERFLOW` 配置 |
|
||
| **软删除** | 通过 `is_delete` 字段 + Repository 基类自动过滤实现 |
|
||
| **读写分离** | 支持写引擎 + 读引擎分离，通过 `READ_DATABASE_URL` 配置 |
|
||
|
||
版本约束：`SQLAlchemy >= 2.0.51`
|
||
|
||
## 请求校验选型
|
||
|
||
### Pydantic v2
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| **声明式校验** | 通过 `BaseModel` + `Field(...)` 声明字段约束，自动校验 |
|
||
| **自定义验证器** | `@field_validator` 支持复杂的业务校验逻辑 |
|
||
| **高性能** | v2 核心用 Rust 重写，校验速度较 v1 提升 5-50 倍 |
|
||
| **错误聚合** | Service 层 `validate()` 方法将校验错误提取为统一提示 |
|
||
|
||
版本约束：`pydantic >= 2.13.4`
|
||
|
||
## 前端技术栈
|
||
|
||
### Vue3 + Vite + AntDesign
|
||
|
||
| 组件 | 版本 | 选型理由 |
|
||
|:---|:---|:---|
|
||
| **Vue3** | 3.x | Composition API、更好的 TypeScript 支持 |
|
||
| **Vite** | 5.x | 极速 HMR、ESM 原生支持、开箱即用的 TypeScript 支持 |
|
||
| **AntDesign** | 2.x | Vue3 生态最成熟的 UI 组件库，企业级后台管理系统首选 |
|
||
| **Pinia** | 2.x | Vue3 官方推荐的状态管理方案，替代 Vuex |
|
||
| **Vue Router** | 4.x | Vue3 官方路由，支持动态路由、路由守卫 |
|
||
| **Axios** | 1.x | HTTP 客户端，支持请求/响应拦截器、取消请求 |
|
||
|
||
## 缓存与消息中间件
|
||
|
||
### Redis
|
||
|
||
:::tip Redis 在系统中的角色
|
||
Redis 在系统中承担多个关键职责：JWT 令牌黑名单、登录失败锁定、数据字典缓存、权限缓存等。采用同步客户端（`redis`）与全站同步 DB/Redis 调用风格一致。
|
||
:::
|
||
|
||
| 用途 | 数据结构 | 过期策略 |
|
||
|:---|:---|:---|
|
||
| JWT 黑名单 | String | 等于 Token 剩余有效期 |
|
||
| 登录失败锁 | String | 指定锁定时长 |
|
||
| 数据字典缓存 | String (JSON) | TTL 可配置 |
|
||
| 权限列表缓存 | String (JSON) | 变更时主动失效（按版本号） |
|
||
|
||
版本约束：`redis >= 5.0.0`（同步客户端）
|
||
|
||
## 定时任务
|
||
|
||
### APScheduler
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| **调度策略** | 支持 Cron、Interval、Date 三种触发器 |
|
||
| **持久化** | 任务定义存储在数据库，重启后自动恢复 |
|
||
| **日志记录** | 每次执行记录到 `tornado_job_log` 表 |
|
||
|
||
## 密码安全
|
||
|
||
### bcrypt 双盐方案
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| **双盐机制** | 系统生成随机盐 + bcrypt 自带盐，双重保护 |
|
||
| **自动升级** | 登录时检测旧版无盐哈希，自动升级为双盐方案 |
|
||
| **安全存储** | 盐值存储在用户表 `salt` 字段，哈希存储在 `password` 字段 |
|
||
|
||
## 其他关键依赖
|
||
|
||
| 依赖 | 用途 |
|
||
|:---|:---|
|
||
| `PyJWT` | JWT 令牌签发与验证（HS256 算法），`src/core/jwt.py` |
|
||
| `bcrypt` | 密码哈希（带随机盐），`src/core/password.py` |
|
||
| `openpyxl` | Excel 导入导出 |
|
||
| `Pillow` | 验证码图片生成，`src/common/utils/captcha.py` |
|
||
| `python-dotenv` | `.env` 配置文件加载 |
|
||
| `alembic` | 数据库迁移，`migrations/` 目录 |
|
||
| `APScheduler` | 定时任务调度，`src/modules/job/scheduler.py` |
|
||
| `bleach` | 富文本 XSS 清洗，`src/common/utils/rich_text.py` |
|
||
| `ip2region` | IP 地理位置解析，`src/common/utils/ip2region.py` |
|
||
|
||
## 版本锁定策略
|
||
|
||
:::warning 版本管理
|
||
所有依赖版本在 `pyproject.toml` 中锁定（Poetry 管理），`requirements.txt` 为 UTF-8 降级副本。生产环境建议使用 `poetry export` 生成精确版本锁文件。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
项目的技术选型以「高性能、类型安全、可扩展」为核心原则。Tornado + SQLAlchemy 2.0 + Pydantic v2 构成后端铁三角，Vue3 + Vite + AntDesign 提供现代化前端体验，Redis 承担缓存与中间件职责。各组件版本经过充分测试验证，形成稳定的技术底座。选型时优先考虑组件的独立性和可替换性，避免强耦合，为未来的架构演进预留空间。
|