Form层规范

概述

Form 层负责数据验证，使用 Django ModelForm 实现。每个模块的 forms.py 定义表单验证类，包含字段验证规则和中文错误提示。

设计原则

• 继承 forms.ModelForm
• 每个字段定义中文 error_messages
• 使用 Meta.fields 指定验证字段
• 验证在 Service 层 ORM 操作之前执行

完整示例

以案例模块为例，application/example/forms.py：

from django import forms
from application.example import models


class ExampleForm(forms.ModelForm):
    """案例表单验证类"""

    # 案例名称
    name = forms.CharField(
        required=True,
        max_length=100,
        error_messages={
            'required': '案例名称不能为空',
            'max_length': '案例名称长度不得超过100个字符',
        }
    )

    # 案例图片
    avatar = forms.CharField(
        required=False,
        max_length=255,
        error_messages={
            'max_length': '案例图片长度不得超过255个字符',
        }
    )

    # 案例类型
    type = forms.IntegerField(
        required=True,
        min_value=1,
        max_value=4,
        error_messages={
            'required': '案例类型不能为空',
            'min_value': '案例类型值不能小于1',
            'max_value': '案例类型值不能大于4',
        }
    )

    # 案例状态
    status = forms.IntegerField(
        required=True,
        min_value=1,
        max_value=2,
        error_messages={
            'required': '案例状态不能为空',
            'min_value': '案例状态值不能小于1',
            'max_value': '案例状态值不能大于2',
        }
    )

    # 排序
    sort = forms.IntegerField(
        required=True,
        error_messages={
            'required': '排序不能为空',
        }
    )

    class Meta:
        model = models.Example
        fields = ['name', 'avatar', 'type', 'status', 'sort']

字段类型

Django 表单字段	说明	常用参数
CharField	字符串	max_length, min_length
IntegerField	整数	min_value, max_value
FloatField	浮点数	min_value, max_value
DecimalField	精确小数	max_digits, decimal_places
BooleanField	布尔值	-
DateTimeField	日期时间	input_formats
DateField	日期	input_formats
EmailField	邮箱	max_length
URLField	URL	max_length

错误消息规范

每个字段必须定义中文 error_messages：

name = forms.CharField(
    required=True,
    max_length=100,
    error_messages={
        'required': '案例名称不能为空',        # 必填验证
        'max_length': '案例名称长度不得超过100个字符',  # 长度验证
        'min_length': '案例名称长度不能少于2个字符',    # 最小长度
    }
)

type = forms.IntegerField(
    required=True,
    min_value=1,
    max_value=4,
    error_messages={
        'required': '案例类型不能为空',    # 必填验证
        'min_value': '案例类型值不能小于1',  # 最小值验证
        'max_value': '案例类型值不能大于4',  # 最大值验证
        'invalid': '案例类型格式不正确',    # 格式验证
    }
)

常用错误消息键

键	说明	适用字段
required	必填验证	所有字段
max_length	最大长度	CharField
min_length	最小长度	CharField
max_value	最大值	IntegerField/FloatField
min_value	最小值	IntegerField/FloatField
invalid	格式验证	所有字段
unique	唯一性验证	需手动实现

Meta 类配置

class Meta:
    # 绑定模型
    model = models.Example

    # 指定验证字段（只验证以下字段）
    fields = ['name', 'avatar', 'type', 'status', 'sort']

    # 排除字段（不验证以下字段）
    # exclude = ['create_user', 'update_user']

fields vs exclude

• fields：白名单，只验证列出的字段
• exclude：黑名单，排除列出的字段
• 推荐使用 fields，更明确

在 Service 中使用

from application.example import forms
from utils import R, regular

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))

    try:
        cleaned_data = form.cleaned_data
        # 使用 cleaned_data 创建记录
        Example.objects.create(
            name=cleaned_data.get('name'),
            type=cleaned_data.get('type'),
            status=cleaned_data.get('status'),
            sort=cleaned_data.get('sort'),
        )
        return R.ok(msg="创建成功")
    except Exception as e:
        return R.failed(msg="添加失败")

错误信息提取

使用 regular.get_err(form) 提取表单验证错误信息：

from utils import regular

form = forms.ExampleForm(data)
if not form.is_valid():
    error_msg = regular.get_err(form)  # 返回第一个错误的中文提示
    return R.failed(msg=error_msg)

自定义验证方法

class ExampleForm(forms.ModelForm):
    name = forms.CharField(required=True, max_length=100)

    def clean_name(self):
        """自定义验证：检查名称是否包含敏感词"""
        name = self.cleaned_data.get('name')
        if '敏感词' in name:
            raise forms.ValidationError('名称包含敏感词')
        return name

    def clean(self):
        """全局验证：检查字段间的关系"""
        cleaned_data = super().clean()
        start_date = cleaned_data.get('start_date')
        end_date = cleaned_data.get('end_date')
        if start_date and end_date and start_date > end_date:
            raise forms.ValidationError('开始日期不能晚于结束日期')
        return cleaned_data

总结

Form 层使用 Django ModelForm 实现数据验证，每个字段定义中文 error_messages。在 Service 层 ORM 操作之前执行验证，使用 regular.get_err(form) 提取错误信息。支持自定义验证方法（clean_{field}）和全局验证（clean）。