Become a sponsor
技术选型说明
本章详细阐述系统各技术组件的选型理由与版本约束说明，旨在帮助开发者理解技术选型的依据与权衡。
后端框架选型
Tornado
为什么选择 Tornado？
Tornado 是 Python 生态中成熟的异步 Web 框架，基于自有事件循环实现非阻塞 I/O。对于后台管理系统这类以 CRUD 为主的场景，Tornado 的轻量灵活和稳定可靠使其成为理想选择。
| 特性 | 说明 |
|---|---|
| 原生异步 | 基于自有事件循环，async/await 一等公民，充分利用 I/O 等待时间 |
| 请求校验 | Pydantic v2 声明式校验，Service 层自动执行 |
| 类型安全 | 全链路类型提示，IDE 补全完善 |
| 轻量灵活 | 核心概念少，无强依赖，学习曲线平缓 |
| 稳定可靠 | 成熟的生产级框架，广泛应用于高并发场景 |
选择 Tornado 的核心理由
- 原生异步：后台管理系统需要处理并发请求（文件上传、批量操作、定时任务），Tornado 的原生异步模型能充分利用 I/O 等待时间
- Pydantic 校验：声明式的数据校验，减少参数校验代码量
- SQLAlchemy 解耦：ORM 不与框架强绑定，支持多数据库驱动切换（MySQL / PostgreSQL / SQL Server / SQLite / Oracle）
- 轻量灵活：无强依赖，核心概念少，易于理解和扩展
- 稳定可靠：经过多年生产验证的成熟框架
ORM 选型
SQLAlchemy 2.0
为什么选择 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
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 |
版本锁定策略
版本管理
所有依赖版本在 pyproject.toml 中锁定（Poetry 管理），requirements.txt 为 UTF-8 降级副本。生产环境建议使用 poetry export 生成精确版本锁文件。
总结
项目的技术选型以「高性能、类型安全、可扩展」为核心原则。Tornado + SQLAlchemy 2.0 + Pydantic v2 构成后端铁三角，Vue3 + Vite + AntDesign 提供现代化前端体验，Redis 承担缓存与中间件职责。各组件版本经过充分测试验证，形成稳定的技术底座。选型时优先考虑组件的独立性和可替换性，避免强耦合，为未来的架构演进预留空间。