第四章架构设计 - 系统架构总览

4.1 整体架构

项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + NaiveUI 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。

架构图

浏览器 (Vue3 + NaiveUI)
    |
    v
Nginx (反向代理)
    |
    v
Django Application
    |
    +-- Middleware Chain
    |   +-- CORS (django-cors-headers)
    |   +-- check_login (JWT认证)
    |   +-- PermissionRequired (RBAC鉴权)
    |
    +-- URL Router (application/urls.py)
    |   +-- include() -> 各模块urls.py
    |
    +-- View Layer (views.py)
    |   +-- Class-based Views + decorators
    |
    +-- Service Layer (services.py)
    |   +-- 业务逻辑 + Django ORM
    |
    +-- Model Layer (models.py)
        +-- BaseModel -> 业务模型
    |
    v
MySQL + Redis

4.2 核心分层

系统采用经典的分层架构设计，各层职责明确：

层级	职责	典型文件
视图层 (View)	接收HTTP请求、参数校验、调用Service、返回响应	`views.py`
服务层 (Service)	业务逻辑处理、数据组装、事务控制	`services.py`
表单层 (Form)	数据验证、类型转换、错误信息生成	`forms.py`
模型层 (Model)	数据库表定义、字段约束、关联关系	`models.py`
路由层 (URL)	URL到视图的映射注册	`urls.py`

4.3 请求处理流程

一个典型的 API 请求经过以下处理链路：

1. 浏览器发起请求 (携带 Authorization: Bearer <token>)
2. CORS中间件 - 处理跨域预检请求
3. check_login - 验证JWT token有效性
4. URL路由匹配 - 分发到对应视图类
5. PermissionRequired - 验证用户权限节点
6. View.get/post/put/delete - 处理请求
7. Service函数 - 执行业务逻辑
8. R.ok()/R.failed() - 构造统一响应
9. JsonResponse - 返回JSON数据

4.4 模块化设计

每个业务模块（如 example、user、role 等）遵循统一的文件结构：

application/<module>/
    __init__.py      # 包初始化
    apps.py          # Django应用配置
    models.py        # 数据模型
    forms.py         # 表单验证
    services.py      # 业务逻辑
    views.py         # 视图处理
    urls.py          # 路由配置
    admin.py         # Admin后台注册
    migrations/      # 数据库迁移文件

4.5 关键设计决策

前后端分离

后端仅提供 JSON API，不渲染模板
前端通过 Vite 开发服务器代理请求到 Django
生产环境由 Nginx 统一处理静态资源和 API 转发

JWT 认证替代 Session

无状态认证，适合分布式部署
Token 通过 Authorization 请求头传递
支持 Token 黑名单机制（Redis 存储）

软删除策略

所有业务表包含 is_delete 字段
删除操作仅标记 is_delete=True，不物理删除
所有查询自动过滤 is_delete=False

代码生成器

通过数据库表定义自动生成完整模块
包含后端 Model/Form/Service/View/URL
包含前端 Vue 页面和 API 模块
自动注册菜单和权限节点

4.6 技术栈概览

类别	技术选型	版本
后端框架	Django	6.0.3
数据库	MySQL	8.0+
缓存	Redis	6.0+
认证	JWT (PyJWT)	-
前端框架	Vue3	3.x
UI组件库	NaiveUI	-
构建工具	Vite	-
状态管理	Pinia	-

4.7 目录结构

DjangoAdmin_Django_NaiveVue/
+-- application/           # Django后端应用
|   +-- settings.py        # 项目配置
|   +-- urls.py            # 主路由
|   +-- models.py          # BaseModel定义
|   +-- <module>/          # 业务模块
+-- middleware/             # 中间件
|   +-- login_middleware.py # JWT认证
|   +-- permission_middleware.py # 权限控制
+-- utils/                  # 工具函数
|   +-- R.py               # 统一响应
|   +-- jwt.py             # JWT工具
|   +-- security.py        # 安全工具
+-- config/                 # 配置文件
|   +-- env.py             # 环境变量
+-- ui/                     # Vue前端
    +-- src/
        +-- views/         # 页面组件
        +-- api/           # API接口
        +-- components/    # 公共组件

4.8 扩展性设计

系统通过以下机制保证良好的扩展性：

Django App 机制：每个模块独立为一个 Django App，可独立开发和部署
代码生成器：新模块通过数据库表定义自动生成，减少重复开发
模板定制：代码生成器使用 Jinja2 模板，可根据项目需求定制生成规则
中间件扩展：通过 Django 中间件机制可灵活添加请求/响应处理逻辑
权限节点：基于 sys:<module>:<action> 的权限标识，支持细粒度权限控制

4.8 KiB Raw Blame History

第四章 架构设计 - 系统架构总览