121 lines
4.9 KiB
Markdown
121 lines
4.9 KiB
Markdown
# 模块开发实战概述
|
||
|
||
本章以「案例管理（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` 提供的统一响应格式：
|
||
|
||
```python
|
||
# 成功响应
|
||
{"code": 0, "data": {...}, "msg": "操作成功", "ok": true}
|
||
|
||
# 失败响应
|
||
{"code": 1, "data": null, "msg": "操作失败", "ok": false}
|
||
```
|
||
|
||
## 总结
|
||
|
||
模块开发实战以案例管理（Example）为例，完整演示从 Model → Form → Service → View → URL → 权限配置 → 前端 API → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。
|