Become a sponsor
整体架构图
本章从全局视角阐述系统的整体技术架构，涵盖前端、后端、数据库及基础设施等核心组成部分。
架构总览
┌─────────────────────────────────────────────────────────────────────────┐
│ Browser (Vue3 + AntDesign) │
│ Axios HTTP Request / Vite Dev Proxy │
└──────────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Nginx (反向代理) │
│ 静态资源 / SSL 终止 / 负载均衡 / gzip 压缩 │
└──────────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Tornado Application │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Handler 生命周期 │ │
│ │ set_default_headers() → prepare() → handler_method() → on_finish()│ │
│ │ CORS + trace_id JWT 认证 权限+日志+业务逻辑 释放DB会话 │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Service Layer (业务逻辑层) │ │
│ │ BaseService / 自定义 Service │ │
│ │ 唯一性校验 · 字段组装 · 序列化 · 文件处理 │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Repository Layer (数据访问层) │ │
│ │ BaseRepository │ │
│ │ CRUD · 软删除 · 分页 · 等值查询 · 原始条件查询 │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ SQLAlchemy 2.0 │ │ Redis (同步客户端) │ │
│ │ ORM → SQL 生成 │ │ Token 黑名单 · 登录锁 · 字典缓存 · 权限缓存│ │
│ └──────────┬──────────┘ └──────────────────────────────────────────┘ │
└─────────────┼───────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Database (MySQL / PostgreSQL / SQL Server / SQLite / Oracle)│
│ 表前缀: tornado_ · 软删除: is_delete │
└─────────────────────────────────────────────────────────────────────────┘架构特征
1. 前后端分离
前端 Vue3 应用通过 HTTP API 调用后端 Tornado 服务，两者独立开发、独立部署。前端开发阶段通过 Vite 的 proxy 配置将 /api 请求代理到后端 http://127.0.0.1:8041，生产环境由 Nginx 统一反向代理。
2. 分层架构
后端严格分为四层，每层职责单一、依赖单向：
| 层次 | 目录 | 职责 |
|---|---|---|
| HTTP 层 | modules/{module}/handlers.py | 路由定义、权限装饰器、操作日志、响应返回 |
| 业务层 | modules/{module}/service.py | 业务逻辑、校验规则、序列化加工 |
| 数据层 | modules/{module}/repository.py | 数据库 CRUD、查询条件组装 |
| 模型层 | modules/{module}/models.py | 表结构定义、字段映射 |
3. 模板方法模式
通过 BaseRepository 和 BaseService 基类，将通用 CRUD 流程固化为模板方法。子类只需声明差异点（过滤字段、排序规则、唯一性校验等），即可获得完整的增删改查能力。
4. Handler 生命周期
Tornado 通过 Handler 生命周期方法实现横切关注点：
python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
def set_default_headers(self):
"""① 设置 CORS 头 + trace_id"""
cros_required(self)
apply_trace_id(self)
@login_required
def prepare(self):
"""② JWT 认证（白名单 URL 跳过）"""
pass
def on_finish(self):
"""④ 请求结束后释放数据库会话"""
db.close()
def write_error(self, status_code, **kwargs):
"""⑤ 异常统一响应"""
...Handler 方法中通过装饰器实现权限/演示模式/操作日志：
python
class PositionAddHandler(BaseHandler):
@permission_required("sys:position:add") # RBAC 权限校验
@check_demo # 演示模式拦截
@operation_log("岗位管理", "添加") # 操作日志记录
async def post(self):
return await position_service.add(self)5. 全局异常处理
BaseHandler.write_error() 统一捕获异常并返回标准响应：
| 异常类型 | 触发场景 | 响应 |
|---|---|---|
AuthError | JWT 过期 / 未登录 | {"code": 401, "msg": "登录过期"} |
PermissionDeniedError | 权限不足 | {"code": 403, "msg": "权限不足"} |
BusinessError | 业务逻辑错误 | {"code": 1, "msg": "..."} |
ValidationError | Pydantic 校验失败 | {"code": 1, "msg": "field: message"} |
NotFoundError | 记录不存在 | {"code": 404, "msg": "记录不存在"} |
Exception | 未捕获异常 | {"code": 500, "msg": "服务器内部错误"} |
6. 统一响应格式
所有 API 端点返回统一的 JSON 结构：
json
{
"code": 0,
"data": {},
"msg": "操作成功",
"ok": true
}成功响应 code=0，失败响应 code=1（或其他业务码），前端无需针对不同接口做差异化解析。
7. 软删除策略
所有业务表通过 is_delete 字段实现软删除（0=正常，1=已删除）。BaseRepository 的等值查询方法自动追加 is_delete=0 过滤，业务代码无需关心已删除数据。
8. 事务管理
数据库事务由 Repository 层的 create() / update() / batch_delete() 方法内部 db.commit() 管理。Service 层的 try/finally 块确保 repo.close() 释放会话。BaseHandler.on_finish() 兜底关闭会话，避免长连接泄漏。
9. 多数据库驱动
通过 DB_DRIVER 环境变量切换数据库驱动（MySQL / PostgreSQL / SQL Server / SQLite / Oracle），SQLAlchemy 的方言层屏蔽了底层差异，业务代码无需修改。
10. 应用启动流程
python
# app.py（入口）→ bootstrap.py（启动引导）→ src/app.py（应用工厂）
# 启动流程：
# 1. bootstrap.main() 解析 --port 参数
# 2. create_app() 构建 Application（路由、模板、静态目录）
# 3. register_extensions() 初始化扩展（SQLAlchemy、Redis）
# 4. HTTPServer.listen(port) 开始监听
# 5. init_scheduler() 启动定时任务调度器
# 6. 注册 SIGINT/SIGTERM 信号实现优雅关闭
# 7. ioloop.start() 启动事件循环技术分层图
┌──────────────────────────────────────────────────────────────┐
│ Frontend (Vue3) │
│ AntDesign · Pinia · Vue Router · Axios │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP / JSON
┌──────────────────────────┴───────────────────────────────────┐
│ Tornado Application │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐ │
│ │ Handler │ │ Router │ │ Exception Handler │ │
│ │ ───────── │ │ ───────── │ │ ───────────────── │ │
│ │ CORS │ │ auth │ │ BaseAppError │ │
│ │ trace_id │ │ v1 (login │ │ write_error() │ │
│ │ login_ │ │ required) │ │ 统一 {code,data,msg} │ │
│ │ required │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Handlers (modules/{module}/handlers.py) │ │
│ │ @permission_required · @check_demo · @operation_log │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Services (modules/{module}/service.py) │ │
│ │ BaseService · 自定义 Service │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Repositories (modules/{module}/repository.py) │ │
│ │ BaseRepository · 自定义 Repository │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Models (modules/{module}/models.py) │ │
│ │ BaseModel → SQLAlchemy ORM │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌────────────┐ ┌─────────────┐
│ Database │ │ Redis │
│ (MySQL等) │ │ (同步客户端) │
└────────────┘ └─────────────┘总结
系统采用经典的前后端分离 + 分层架构设计，通过 Handler 生命周期方法和装饰器实现横切关注点（认证、权限、日志），通过基类模板方法消除重复 CRUD 代码，通过 Pydantic 实现请求参数的声明式校验。整体架构在保持简洁的同时，具备良好的可扩展性和可维护性。