模块开发实战概述

本章以「案例管理（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）」作为案例的原因：

1. 结构典型：包含完整的 CRUD + 状态管理 + 批量删除，覆盖大多数业务场景
2. 字段丰富：涵盖字符串、整数、图片、状态枚举、排序等常见字段类型
3. 代码规范：由代码生成器生成，遵循项目统一的开发规范
4. 前后端完整：后端 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 → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。