301 lines
8.4 KiB
Markdown
301 lines
8.4 KiB
Markdown
# 表单验证（Form）
|
||
|
||
表单验证是模块开发的第二步，用于对前端提交的数据进行验证。项目使用 Django 的 `ModelForm` 实现表单验证，所有错误信息使用中文提示。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
application/example/forms.py
|
||
```
|
||
|
||
## 完整代码
|
||
|
||
```python
|
||
from django import forms
|
||
|
||
from application.example import models
|
||
|
||
|
||
# =============================================================
|
||
# 案例表单验证类
|
||
# =============================================================
|
||
|
||
class ExampleForm(forms.ModelForm):
|
||
"""
|
||
案例表单验证类
|
||
|
||
用于创建和更新案例信息时的表单验证。
|
||
包含案例名称, 案例图片, 案例类型等属性
|
||
|
||
验证字段包括：
|
||
- name: 案例名称
|
||
- avatar: 案例图片
|
||
- type: 案例类型
|
||
- status: 案例状态（1-正常, 2-禁用）
|
||
- sort: 排序
|
||
"""
|
||
|
||
# ----------------------------------------------------------
|
||
# 案例名称
|
||
# ----------------------------------------------------------
|
||
# 字段说明: 案例的名称
|
||
# 字段类型: 字符串（CharField）
|
||
# 验证规则: 必填（required=True），最大长度100字符
|
||
# 业务说明: 案例的核心标识字段，用于列表展示和搜索
|
||
name = forms.CharField(
|
||
required=True,
|
||
max_length=100,
|
||
error_messages={
|
||
'required': '案例名称不能为空',
|
||
'max_length': '案例名称长度不得超过100个字符',
|
||
}
|
||
)
|
||
|
||
# ----------------------------------------------------------
|
||
# 案例图片
|
||
# ----------------------------------------------------------
|
||
# 字段说明: 案例的图片
|
||
# 字段类型: 字符串（CharField）
|
||
# 验证规则: 可选（required=False），最大长度255字符
|
||
# 业务说明: 用于案例列表展示和详情页的图片
|
||
avatar = forms.CharField(
|
||
required=False,
|
||
max_length=255,
|
||
error_messages={
|
||
'max_length': '案例图片长度不得超过255个字符',
|
||
}
|
||
)
|
||
|
||
# ----------------------------------------------------------
|
||
# 案例类型
|
||
# ----------------------------------------------------------
|
||
# 字段说明: 案例的分类类型
|
||
# 字段类型: 整数（IntegerField）
|
||
# 验证规则: 必填（required=True），取值范围1-4
|
||
# 业务说明: 对案例进行分类管理，支持按类型筛选
|
||
type = forms.IntegerField(
|
||
required=True,
|
||
min_value=1,
|
||
max_value=4,
|
||
error_messages={
|
||
'required': '案例类型不能为空',
|
||
'min_value': '案例类型值不能小于1',
|
||
'max_value': '案例类型值不能大于4',
|
||
}
|
||
)
|
||
|
||
# ----------------------------------------------------------
|
||
# 案例状态
|
||
# ----------------------------------------------------------
|
||
# 字段说明: 案例的显示状态
|
||
# 字段类型: 整数（IntegerField）
|
||
# 验证规则: 必填（required=True），取值范围1-2
|
||
# 业务说明: 1-正常, 2-禁用，控制案例是否在前端展示
|
||
status = forms.IntegerField(
|
||
required=True,
|
||
min_value=1,
|
||
max_value=2,
|
||
error_messages={
|
||
'required': '案例状态不能为空',
|
||
'min_value': '案例状态值不能小于1',
|
||
'max_value': '案例状态值不能大于2',
|
||
}
|
||
)
|
||
|
||
# ----------------------------------------------------------
|
||
# 排序
|
||
# ----------------------------------------------------------
|
||
# 字段说明: 案例的排序权重
|
||
# 字段类型: 整数（IntegerField）
|
||
# 验证规则: 必填（required=True）
|
||
# 排序规则: 数值越小越靠前
|
||
# 业务说明: 手动控制案例在列表中的显示顺序
|
||
sort = forms.IntegerField(
|
||
required=True,
|
||
error_messages={
|
||
'required': '排序不能为空',
|
||
}
|
||
)
|
||
|
||
# =============================================================
|
||
# 表单元数据配置
|
||
# =============================================================
|
||
|
||
class Meta:
|
||
"""
|
||
表单元数据配置类
|
||
|
||
定义表单绑定的模型和需要验证的字段。
|
||
"""
|
||
|
||
# 绑定模型
|
||
# 指定该表单对应的数据模型为 Example（案例）
|
||
model = models.Example
|
||
|
||
# 指定需要验证的字段
|
||
# 只验证以下字段，其他字段不进行表单验证
|
||
fields = [
|
||
'name',
|
||
'avatar',
|
||
'type',
|
||
'status',
|
||
'sort',
|
||
]
|
||
```
|
||
|
||
## 代码解析
|
||
|
||
### Form 类继承
|
||
|
||
```python
|
||
class ExampleForm(forms.ModelForm):
|
||
```
|
||
|
||
| 基类 | 来源 | 提供能力 |
|
||
|:----|:----|:----|
|
||
| `forms.ModelForm` | Django 内置 | 自动绑定模型、字段验证、cleaned_data |
|
||
|
||
`ModelForm` 会根据绑定的模型自动生成表单字段，但项目中通常手动重新定义每个字段以设置中文错误提示。
|
||
|
||
### 字段定义
|
||
|
||
#### 字符串字段
|
||
|
||
```python
|
||
name = forms.CharField(
|
||
required=True,
|
||
max_length=100,
|
||
error_messages={
|
||
'required': '案例名称不能为空',
|
||
'max_length': '案例名称长度不得超过100个字符',
|
||
}
|
||
)
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|:----|:----|
|
||
| `required=True` | 必填字段 |
|
||
| `max_length=100` | 最大长度 100 字符 |
|
||
| `error_messages` | 自定义错误提示（中文） |
|
||
|
||
#### 整数字段
|
||
|
||
```python
|
||
type = forms.IntegerField(
|
||
required=True,
|
||
min_value=1,
|
||
max_value=4,
|
||
error_messages={
|
||
'required': '案例类型不能为空',
|
||
'min_value': '案例类型值不能小于1',
|
||
'max_value': '案例类型值不能大于4',
|
||
}
|
||
)
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|:----|:----|
|
||
| `required=True` | 必填字段 |
|
||
| `min_value=1` | 最小值 |
|
||
| `max_value=4` | 最大值 |
|
||
| `error_messages` | 自定义错误提示（中文） |
|
||
|
||
#### 可选字段
|
||
|
||
```python
|
||
avatar = forms.CharField(
|
||
required=False,
|
||
max_length=255,
|
||
error_messages={
|
||
'max_length': '案例图片长度不得超过255个字符',
|
||
}
|
||
)
|
||
```
|
||
|
||
`required=False` 表示该字段为可选字段，不填时不会报错。
|
||
|
||
### Meta 类配置
|
||
|
||
```python
|
||
class Meta:
|
||
model = models.Example
|
||
fields = ['name', 'avatar', 'type', 'status', 'sort']
|
||
```
|
||
|
||
| 配置项 | 说明 |
|
||
|:----|:----|
|
||
| `model` | 绑定的数据模型 |
|
||
| `fields` | 需要验证的字段列表 |
|
||
|
||
## 错误信息提取
|
||
|
||
表单验证失败时，使用 `utils/regular.py` 中的 `get_err()` 函数提取错误信息：
|
||
|
||
```python
|
||
from utils import regular
|
||
|
||
form = forms.ExampleForm(data)
|
||
if not form.is_valid():
|
||
return R.failed(msg=regular.get_err(form))
|
||
```
|
||
|
||
`get_err()` 函数的实现：
|
||
|
||
```python
|
||
def get_err(form):
|
||
"""获取表单错误文本，多个错误用'/'分隔"""
|
||
error_list = []
|
||
for item in form.errors.get_json_data().values():
|
||
error_list.append(item[0].get('message'))
|
||
err_str = '/'.join(error_list)
|
||
return err_str
|
||
```
|
||
|
||
例如，如果 `name` 和 `type` 都验证失败，返回的错误信息为：
|
||
|
||
```
|
||
案例名称不能为空/案例类型不能为空
|
||
```
|
||
|
||
## 在 Service 中使用
|
||
|
||
表单验证通常在 Service 层的添加和更新函数中调用：
|
||
|
||
```python
|
||
def add_example(request):
|
||
# 解析请求参数
|
||
data, error = parse_request_body(request)
|
||
if error:
|
||
return R.failed(msg=error)
|
||
|
||
# 表单验证
|
||
form = forms.ExampleForm(data)
|
||
if not form.is_valid():
|
||
return R.failed(msg=regular.get_err(form))
|
||
|
||
# 获取验证后的数据
|
||
cleaned_data = form.cleaned_data
|
||
# ... 创建记录
|
||
```
|
||
|
||
## 常用验证规则
|
||
|
||
| 字段类型 | 验证参数 | 说明 |
|
||
|:----|:----|:----|
|
||
| CharField | `required`, `max_length`, `min_length` | 字符串长度 |
|
||
| IntegerField | `required`, `min_value`, `max_value` | 整数范围 |
|
||
| EmailField | `required` | 邮箱格式 |
|
||
| URLField | `required` | URL 格式 |
|
||
|
||
## 开发要点
|
||
|
||
1. **所有错误信息必须使用中文**：便于前端直接展示给用户
|
||
2. **error_messages 覆盖所有验证规则**：required、max_length、min_value 等
|
||
3. **可选字段设置 `required=False`**：避免不必要的验证错误
|
||
4. **Meta.fields 列出所有需要验证的字段**：未列出的字段不进行验证
|
||
5. **使用 `regular.get_err()` 提取错误信息**：统一的错误信息格式
|
||
|
||
## 总结
|
||
|
||
表单验证使用 Django ModelForm，手动重新定义每个字段以设置中文错误提示。Meta 类绑定数据模型并指定需要验证的字段。验证失败时使用 `regular.get_err()` 提取错误信息，多个错误用 `/` 分隔。
|