403 lines
13 KiB
Markdown
403 lines
13 KiB
Markdown
:::tip 本章概要
|
||
以 flask_example 演示表为完整案例，演示从建表到生成到使用的全流程。
|
||
:::
|
||
|
||
# 实战案例
|
||
|
||
以 `flask_example` 演示表为完整案例，演示从建表到生成到使用的全流程。
|
||
|
||
## 第 1 步：创建数据表
|
||
|
||
在数据库中执行建表语句：
|
||
|
||
```sql
|
||
CREATE TABLE `flask_example` (
|
||
`id` int NOT NULL AUTO_INCREMENT,
|
||
`name` varchar(100) NOT NULL COMMENT '案例名称',
|
||
`code` varchar(50) NOT NULL COMMENT '案例编码',
|
||
`type` int DEFAULT 1 COMMENT '案例类型：1-类型1 2-类型2 3-类型3',
|
||
`status` int DEFAULT 1 COMMENT '案例状态：1-正常 2-停用',
|
||
`sort` int DEFAULT 0 COMMENT '排序',
|
||
`cover` varchar(255) DEFAULT NULL COMMENT '封面图',
|
||
`content` text COMMENT '案例内容',
|
||
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
|
||
`create_user` varchar(50) DEFAULT NULL,
|
||
`create_time` datetime DEFAULT NULL,
|
||
`update_user` varchar(50) DEFAULT NULL,
|
||
`update_time` datetime DEFAULT NULL,
|
||
`is_delete` int DEFAULT 0,
|
||
PRIMARY KEY (`id`)
|
||
) COMMENT='案例表';
|
||
```
|
||
|
||
## 第 2 步：预览配置
|
||
|
||
```bash
|
||
python generator.py flask_example --dry-run
|
||
```
|
||
|
||
输出：
|
||
|
||
```
|
||
==============================================================
|
||
数据库表结构解析和代码生成工具
|
||
==============================================================
|
||
正在解析表: flask_example
|
||
表结构解析成功
|
||
|
||
------------------------------------------------------------
|
||
生成配置摘要:
|
||
------------------------------------------------------------
|
||
应用名称: example
|
||
模块名称: 案例
|
||
模型类名: Example
|
||
字段数量: 8
|
||
是否有排序: True
|
||
是否有状态: True
|
||
- name: 案例名称 (String)
|
||
- code: 案例编码 (String)
|
||
- type: 案例类型 (Integer)
|
||
选项: [(1, '类型1'), (2, '类型2'), (3, '类型3')]
|
||
- status: 案例状态 (Integer)
|
||
选项: [(1, '正常'), (2, '停用')]
|
||
- sort: 排序 (Integer)
|
||
... 还有 3 个字段
|
||
|
||
==============================================================
|
||
预览模式 - 不执行代码生成（去掉 --dry-run 参数即可生成）
|
||
==============================================================
|
||
```
|
||
|
||
## 第 3 步：生成代码
|
||
|
||
```bash
|
||
python generator.py flask_example
|
||
```
|
||
|
||
输出：
|
||
|
||
```
|
||
==============================================================
|
||
数据库表结构解析和代码生成工具
|
||
==============================================================
|
||
正在解析表: flask_example
|
||
表结构解析成功
|
||
...
|
||
创建输出目录: src/modules/example
|
||
生成文件: src/modules/example/__init__.py
|
||
生成文件: src/modules/example/models.py
|
||
生成文件: src/modules/example/schema.py
|
||
生成文件: src/modules/example/repository.py
|
||
生成文件: src/modules/example/service.py
|
||
生成文件: src/modules/example/router.py
|
||
生成文件: ui/src/views/tool/example/index.vue
|
||
生成文件: ui/src/views/tool/example/edit.vue
|
||
生成文件: ui/src/views/tool/example/detail.vue
|
||
生成文件: ui/src/views/tool/example/querySchemas.ts
|
||
生成文件: ui/src/views/tool/example/columns.ts
|
||
生成文件: ui/src/api/tool/example.ts
|
||
已更新路由注册: src/routes/v1.py
|
||
已自动创建菜单: 案例（10 个权限节点）
|
||
代码生成完成！
|
||
```
|
||
|
||
## 第 4 步：验证生成结果
|
||
|
||
### 检查后端文件
|
||
|
||
```bash
|
||
ls src/modules/example/
|
||
# __init__.py models.py repository.py schema.py service.py router.py
|
||
```
|
||
|
||
### 检查前端文件
|
||
|
||
```bash
|
||
ls ui/src/views/tool/example/
|
||
# index.vue edit.vue detail.vue columns.ts querySchemas.ts
|
||
|
||
ls ui/src/api/tool/example.ts
|
||
# example.ts
|
||
```
|
||
|
||
### 检查路由注册
|
||
|
||
在 `src/routes/v1.py` 中应新增：
|
||
|
||
```python
|
||
from src.modules.example.router import example_blue
|
||
|
||
BLUEPRINTS = [
|
||
# ... 其他模块
|
||
example_blue,
|
||
]
|
||
```
|
||
|
||
## 第 5 步：重启后端
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
## 第 6 步：访问页面
|
||
|
||
1. 登录管理后台
|
||
2. 左侧菜单找到「开发工具 → 案例」
|
||
3. 进入案例管理页面，测试增删改查功能
|
||
|
||
|
||
|
||
## 生成代码逐文件解析
|
||
|
||
### models.py
|
||
|
||
```python
|
||
from src.common.base_db import BaseDB
|
||
from src.common.base_model import BaseModel
|
||
from config.database import DB_PREFIX
|
||
|
||
class Example(BaseModel, BaseDB):
|
||
__tablename__ = DB_PREFIX + "example"
|
||
|
||
name = Column(String(100), nullable=False, comment="案例名称")
|
||
code = Column(String(50), nullable=False, comment="案例编码")
|
||
type = Column(Integer, default=1, comment="案例类型：1-类型1 2-类型2 3-类型3")
|
||
status = Column(Integer, default=1, comment="案例状态：1-正常 2-停用")
|
||
sort = Column(Integer, default=0, comment="排序")
|
||
cover = Column(String(255), nullable=True, comment="封面图")
|
||
content = Column(Text, nullable=True, comment="案例内容")
|
||
remark = Column(String(500), nullable=True, comment="备注")
|
||
```
|
||
|
||
- 自动映射字段类型（varchar→String, int→Integer, text→Text）
|
||
- 自动识别 `cover` 为图片字段
|
||
- 自动识别 `content` 为富文本字段（注释含"内容"关键词）
|
||
- 系统字段（id/create_user/create_time 等）由基类提供，不重复定义
|
||
|
||
### schema.py
|
||
|
||
```python
|
||
from wtforms import StringField, IntegerField
|
||
from wtforms.validators import DataRequired, Length, NumberRange, Optional
|
||
|
||
from src.common.forms.base_form import BaseForm
|
||
|
||
class ExampleForm(BaseForm):
|
||
name = StringField('案例名称', validators=[
|
||
DataRequired(message='案例名称不能为空'),
|
||
Length(min=1, max=100, message='案例名称长度必须在1-100个字符之间')
|
||
])
|
||
code = StringField('案例编码', validators=[
|
||
DataRequired(message='案例编码不能为空'),
|
||
Length(min=1, max=50, message='案例编码长度必须在1-50个字符之间')
|
||
])
|
||
type = IntegerField('案例类型', validators=[
|
||
DataRequired(message='案例类型不能为空'),
|
||
NumberRange(min=1, max=3, message='案例类型必须是1-3')
|
||
])
|
||
status = IntegerField('案例状态', validators=[
|
||
DataRequired(message='案例状态不能为空'),
|
||
NumberRange(min=1, max=2, message='案例状态必须是1或2')
|
||
])
|
||
sort = IntegerField('排序', validators=[
|
||
DataRequired(message='排序不能为空'),
|
||
NumberRange(min=0, max=99999, message='排序必须在0-99999之间')
|
||
])
|
||
cover = StringField('封面图', validators=[Optional()])
|
||
content = StringField('案例内容', validators=[Optional()])
|
||
remark = StringField('备注', validators=[Optional()])
|
||
|
||
class ExampleStatusForm(BaseForm):
|
||
id = IntegerField('案例ID', validators=[
|
||
DataRequired(message='案例ID不能为空'),
|
||
NumberRange(min=1, message='案例ID必须大于0')
|
||
])
|
||
status = IntegerField('案例状态', validators=[
|
||
DataRequired(message='案例状态不能为空'),
|
||
NumberRange(min=1, max=2, message='案例状态必须是1或2')
|
||
])
|
||
```
|
||
|
||
- `name`/`code`/`type`/`status`/`sort` 为必填
|
||
- `cover`/`content`/`remark` 为可选
|
||
- 自动生成 `StatusForm`（因为有 `status` 字段）
|
||
|
||
### service.py
|
||
|
||
```python
|
||
from src.common.base_service import BaseService
|
||
from src.modules.example.models import Example
|
||
from src.modules.example.repository import ExampleRepository
|
||
|
||
class ExampleService(BaseService):
|
||
repository = ExampleRepository
|
||
form = ExampleForm
|
||
status_form = ExampleStatusForm
|
||
model_name = "示例"
|
||
serialize_maps = {'type': 'example_type', 'status': 'example_status'}
|
||
|
||
get_example_page = _example_service.get_page
|
||
get_example_detail = _example_service.get_detail
|
||
add_example = _example_service.add
|
||
update_example = _example_service.update
|
||
delete_example = _example_service.delete
|
||
batch_delete_examples = _example_service.batch_delete
|
||
update_example_status = _example_service.update_status
|
||
```
|
||
|
||
- `name`/`code`/`remark` 为模糊查询字段（字符串类型）
|
||
- `type`/`status` 为精确匹配字段（有选项）
|
||
- 默认按 `sort` 升序、`id` 降序排列
|
||
- `cover` 标记为文件字段（自动处理上传和 URL）
|
||
- `serialize_maps` 自动关联数据字典
|
||
|
||
### router.py
|
||
|
||
```python
|
||
from flask import Blueprint, request
|
||
from src.core.permission import check_permission
|
||
from src.core import response as R
|
||
from src.common.utils.request import parse_request_body, parse_batch_ids
|
||
|
||
example_blue = Blueprint('example', __name__, url_prefix='/example')
|
||
|
||
@example_blue.route('/page', methods=['GET'])
|
||
@check_permission('sys:example:page')
|
||
def page():
|
||
from src.modules.example.service import get_example_page
|
||
return get_example_page()
|
||
|
||
@example_blue.route('/add', methods=['POST'])
|
||
@check_permission('sys:example:add')
|
||
def add():
|
||
from src.modules.example.service import add_example
|
||
from src.modules.example.schema import ExampleForm
|
||
data = parse_request_body(request, ExampleForm)
|
||
return add_example(data)
|
||
|
||
# ... update / delete / batchDelete / status / detail / list
|
||
```
|
||
|
||
- 自动生成 8 个端点（page/detail/list/add/update/delete/batchDelete/status）
|
||
- 写操作自动加 `@check_permission` 装饰器
|
||
|
||
## 批量生成示例
|
||
|
||
创建第二张表：
|
||
|
||
```sql
|
||
CREATE TABLE `flask_product` (
|
||
`id` int NOT NULL AUTO_INCREMENT,
|
||
`name` varchar(200) NOT NULL COMMENT '商品名称',
|
||
`price` decimal(10,2) DEFAULT 0 COMMENT '价格',
|
||
`stock` int DEFAULT 0 COMMENT '库存',
|
||
`status` int DEFAULT 1 COMMENT '状态：1-上架 2-下架',
|
||
`sort` int DEFAULT 0 COMMENT '排序',
|
||
`create_user` varchar(50) DEFAULT NULL,
|
||
`create_time` datetime DEFAULT NULL,
|
||
`update_user` varchar(50) DEFAULT NULL,
|
||
`update_time` datetime DEFAULT NULL,
|
||
`is_delete` int DEFAULT 0,
|
||
PRIMARY KEY (`id`)
|
||
) COMMENT='商品表';
|
||
```
|
||
|
||
Web 界面批量生成：
|
||
|
||
|
||
|
||
```json
|
||
{
|
||
"tableNames": [
|
||
"flask_example|案例表",
|
||
"flask_product|商品表"
|
||
]
|
||
}
|
||
```
|
||
|
||
CLI 循环生成：
|
||
|
||
```bash
|
||
python generator.py flask_example
|
||
python generator.py flask_product
|
||
```
|
||
|
||
## 树状表示例
|
||
|
||
当表中包含 `parent_id` 或 `pid` 字段时，生成器自动切换为树状模板。
|
||
|
||
### 创建树状表
|
||
|
||
```sql
|
||
CREATE TABLE `flask_category` (
|
||
`id` int NOT NULL AUTO_INCREMENT,
|
||
`name` varchar(100) NOT NULL COMMENT '分类名称',
|
||
`parent_id` int DEFAULT 0 COMMENT '父级ID（0为顶级）',
|
||
`sort` int DEFAULT 0 COMMENT '排序',
|
||
`status` int DEFAULT 1 COMMENT '状态：1-正常 2-停用',
|
||
`create_user` varchar(50) DEFAULT NULL,
|
||
`create_time` datetime DEFAULT NULL,
|
||
`update_user` varchar(50) DEFAULT NULL,
|
||
`update_time` datetime DEFAULT NULL,
|
||
`is_delete` int DEFAULT 0,
|
||
PRIMARY KEY (`id`)
|
||
) COMMENT='分类表';
|
||
```
|
||
|
||
### 生成结果差异
|
||
|
||
因为表中包含 `parent_id` 字段，生成器自动：
|
||
|
||
1. **前端模板切换**：使用 `ui2/` 树形模板替代 `ui/` 普通列表模板
|
||
2. **生成文件减少**：不生成 `columns.ts` 和 `querySchemas.ts`（树形组件内联列定义）
|
||
3. **数据加载方式**：全量加载 + 前端 `buildTree` 构建树形结构
|
||
4. **交互差异**：支持展开/折叠、父子级联选择
|
||
|
||
```
|
||
普通列表（ui/） 树状列表（ui2/）
|
||
├── index.vue ├── index.vue（内联列 + buildTree）
|
||
├── edit.vue ├── edit.vue（含父级选择）
|
||
├── detail.vue ├── detail.vue
|
||
├── columns.ts └── （无 columns.ts）
|
||
├── querySchemas.ts └── （无 querySchemas.ts）
|
||
└── api.ts └── api.ts（共用）
|
||
```
|
||
|
||
## 生成后的自定义
|
||
|
||
代码生成后，通常需要根据业务需求进行微调：
|
||
|
||
### 常见自定义项
|
||
|
||
| 自定义项 | 涉及文件 | 说明 |
|
||
|:----|:----|:----|
|
||
| 添加业务校验 | `schema.py` | 添加 `validate_` 自定义校验逻辑 |
|
||
| 添加删除前检查 | `service.py` | 覆盖 `before_delete` 钩子 |
|
||
| 添加创建前处理 | `service.py` | 覆盖 `before_add` 钩子（如密码哈希） |
|
||
| 修改序列化 | `service.py` | 覆盖 `_detail_dict` / `_enrich_page_records` 钩子 |
|
||
| 添加自定义接口 | `router.py` | 新增路由方法 |
|
||
| 调整前端布局 | `index.vue` | 修改表格列宽、操作按钮等 |
|
||
| 调整表单校验 | `edit.vue` | 修改表单规则、默认值等 |
|
||
|
||
### 示例：添加删除前检查
|
||
|
||
```python
|
||
# src/modules/example/service.py
|
||
class ExampleService(BaseService):
|
||
# ... 原有配置 ...
|
||
|
||
@classmethod
|
||
def before_delete(cls, ids):
|
||
"""删除前校验：检查是否有关联数据"""
|
||
for eid in ids:
|
||
if cls.repository.count_children(eid) > 0:
|
||
raise BizError("存在子分类，请先删除子分类")
|
||
```
|
||
|
||
## 总结
|
||
|
||
通过以上 6 步即可完成一个完整业务模块的生成：
|
||
1. 建表 → 2. 预览 → 3. 生成 → 4. 验证 → 5. 重启 → 6. 使用
|
||
|
||
整个过程约 1 分钟，生成约 12 个文件、500+ 行代码，涵盖后端三层 + 前端页面 + 路由注册 + 菜单权限。生成后根据业务需求进行微调即可投入使用。
|