模块开发实战概述

本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。

你将学到什么

通过本章的实战演练，你将完整经历以下开发环节：

步骤	文件	说明
1. 数据模型	`models.py`	定义数据库表结构，继承 BaseModel
2. 表单验证	`forms.py`	Django ModelForm 验证，中文错误提示
3. 业务逻辑	`services.py`	实现增删改查、分页、状态管理
4. 视图层	`views.py`	类视图，登录校验 + 权限控制 + 操作日志
5. 路由注册	`urls.py`	模块路由 + 主路由注册
6. 权限配置	菜单管理	配置权限节点 sys:module:action
7. 前端 API	`api/tool/example.ts`	封装 HTTP 请求
8. 前端页面	`views/tool/example/`	列表页 + 编辑弹窗 + 详情弹窗

案例模块：案例管理

选择「案例管理（Example）」作为案例的原因：

结构典型：包含完整的 CRUD + 状态管理 + 批量删除，覆盖大多数业务场景
字段丰富：涵盖字符串、整数、图片、状态枚举、排序等常见字段类型
代码规范：由代码生成器生成，遵循项目统一的开发规范
前后端完整：后端 5 个文件 + 前端 5 个文件，总计约 1500 行代码

模块文件总览

后端（application/example/）
├── models.py          # 数据模型（继承 BaseModel）
├── forms.py           # 表单验证（Django ModelForm）
├── services.py        # 业务逻辑层（CRUD 函数）
├── views.py           # 视图层（类视图 + 装饰器）
├── urls.py            # 路由配置
├── apps.py            # 应用配置
├── admin.py           # Django Admin 注册
└── migrations/        # 数据库迁移文件

前端（ui/src/）
├── api/tool/
│   └── example.ts     # API 请求封装
└── views/tool/example/
    ├── index.vue      # 主页面：搜索 + 表格 + 操作
    ├── edit.vue       # 编辑弹窗：新增/编辑表单
    ├── detail.vue     # 详情弹窗：查看记录详情
    ├── columns.ts     # 表格列定义
    └── querySchemas.ts # 搜索表单 Schema

数据库表结构

案例表 django_example 结构如下：

字段	类型	说明
id	int	主键，自增
name	varchar(100)	案例名称
avatar	varchar(255)	案例图片
type	int	案例类型：1-类型1 2-类型2 3-类型3 4-类型4
status	int	案例状态：1-正常 2-禁用
sort	int	排序权重
create_user	varchar(50)	创建人
create_time	datetime	创建时间
update_user	varchar(50)	更新人
update_time	datetime	更新时间
is_delete	tinyint	软删除标记：0-正常 1-已删除

其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 BaseModel 自动提供，业务字段仅需定义 name、avatar、type、status、sort。

开发顺序

建议按以下顺序逐步开发，每完成一步即可验证：

1. models.py     → 建表，确认数据库中有 django_example 表
2. forms.py      → 定义表单验证规则
3. services.py   → 业务逻辑层（CRUD 函数）
4. views.py      → API 视图（类视图 + 装饰器）
5. urls.py       → 注册路由
6. 权限配置       → 在菜单管理中添加权限节点
7. 前端 API       → 封装 HTTP 请求
8. 前端页面       → 列表页 + 编辑弹窗 + 详情弹窗

本章每一步都附有完整代码和详细注释。建议对照项目中 application/example/ 目录下的实际源码一起阅读，加深理解。

模块开发五步模式

模块开发遵循固定的五步模式：

Model → Form → Service → View → URL

步骤	文件	职责
Model	`models.py`	定义数据模型，继承 BaseModel，配置表名和字段
Form	`forms.py`	定义表单验证，绑定模型，设置中文错误提示
Service	`services.py`	实现业务逻辑，所有 CRUD 操作封装为独立函数
View	`views.py`	定义 HTTP 视图，组合登录校验、权限控制、操作日志
URL	`urls.py`	注册路由，将 URL 路径映射到视图类

统一响应格式

所有 API 接口使用 utils/R.py 提供的统一响应格式：

# 成功响应
{"code": 0, "data": {...}, "msg": "操作成功", "ok": true}

# 失败响应
{"code": 1, "data": null, "msg": "操作失败", "ok": false}

总结

模块开发实战以案例管理（Example）为例，完整演示从 Model → Form → Service → View → URL → 权限配置 → 前端 API → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。

4.9 KiB Raw Permalink Blame History Unescape Escape