# 表单验证（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()` 提取错误信息，多个错误用 `/` 分隔。