Django表单验证失败的常见陷阱与完整解决方案

在Django开发中，表单验证失败却找不到明确错误提示的现象相当普遍。例如，日志显示 telefone 和 foto 字段“required”，但前端明明已填写这些字段。问题根源在哪？

通常，这并非数据未提交，而是自定义 clean() 方法破坏了Django表单的数据流机制，这是验证失败的根本原因。

考虑一个具体场景：用户填写所有字段后提交，却收到验证错误。服务端表单定义——特别是 clean() 方法未按预期工作——可能是罪魁祸首。

问题核心：clean() 方法必须返回 cleaned_data

Django表单的 clean() 方法执行两项任务：一是执行自定义验证逻辑，二是返回清洗后的数据字典。若遗漏 return cleaned_data，Django 会将 cleaned_data 视为 None，导致所有字段（包括非空字段）被判定为“缺失”，进而触发 required=True 的默认校验失败。

例如，forms.py 中可能缺少返回值：

def clean(self):
    cleaned_data = super().clean()
    # 验证逻辑（如电话格式、邮箱校验）
    #  缺少这一行
    # return cleaned_data  ← 必须添加

正确的做法是在 clean() 方法末尾显式返回 cleaned_data。以下是一个修正后的完整示例，同时解决了其他常见问题：

from django import forms
from django.core.exceptions import ValidationError
from django.core.validators import validate_email
import re

class CadastroForm(forms.Form):
    nome = forms.CharField(label="Nome completo", max_length=100, required=True)
    telefone = forms.CharField(label="Telefone", max_length=20, required=True)
    email = forms.EmailField(label="Email", required=True)
    iesb = forms.ChoiceField(
        label="Frequenta o IESB",
        choices=[('Yes', 'Sim'), ('No', 'No')],
        widget=forms.RadioSelect,
        required=True
    )
    mat = forms.IntegerField(label="Matrícula", required=False)  # radio控制是否必填
    foto = forms.ImageField(label="Foto", required=False)  # 文件字段非必需

    def clean(self):
        cleaned_data = super().clean()
        nome = cleaned_data.get("nome")
        telefone = cleaned_data.get("telefone")
        email = cleaned_data.get("email")
        iesb = cleaned_data.get("iesb")
        mat = cleaned_data.get("mat")

        if nome and isinstance(nome, str):
            cleaned_data["nome"] = nome.title()

        if telefone and re.search(r'[a-zA-Z]', telefone):
            raise ValidationError("O número de telefone no pode possuir letras")

        try:
            validate_email(email)
        except ValidationError:
            raise ValidationError("Endereo de e-mail inválido")

        if iesb == "Yes" and (mat is None or mat <= 0):
            raise ValidationError("Se frequenta o IESB, deve informar uma matrícula válida")

        #  关键修复：必须返回清洗后的数据
        return cleaned_data

视图层处理：正确渲染与重定向

原视图若缺少 render() 调用，GET请求将无法响应。此外，文件上传必须启用 request.FILES：

from django.shortcuts import render, HttpResponseRedirect
from django.urls import reverse
from .forms import CadastroForm
from .utils import insert_data

def get_form(request):
    if request.method == 'POST':
        form = CadastroForm(request.POST, request.FILES)  #  添加 request.FILES
        if form.is_valid():
            cd = form.cleaned_data
            insert_data(
                nome=cd['nome'],
                mat=cd.get('mat'),
                telefone=cd['telefone'],
                email=cd['email']
            )
            return HttpResponseRedirect(reverse('all-borrowed'))
    else:
        form = CadastroForm()

    #  必须返回渲染结果
    return render(request, 'cadastro.html', {'form': form})

模板层：使用Django表单渲染，避免手写HTML

手动编写 标签容易出错（如name不匹配、CSRF token遗漏、错误信息不显示）。推荐使用 {{ form }} 或 {{ form.field }} 渲染：

{% block page_content %}
Cadastro

{% csrf_token %} {{ form.as_p }}

{% endblock %}

必须留意的细节

• 文件上传需设置 enctype="multipart/form-data"——缺少此项，request.FILES 将为空。
• RadioSelect 必须配合 ChoiceField 使用——b_iesb = forms.RadioSelect(...) 不正确，因为 RadioSelect 是 widget，非字段。
• clean() 中修改 cleaned_data 后必须 return——这是核心且易被忽略的规则。
• 前端JS控制disabled状态不影响后端校验——后端仍需按业务逻辑校验，如 iesb=="Yes" 时 mat 是否有效。
• 敏感操作建议使用 get_absolute_url() 或命名URL——避免硬编码 action="../../views.py"，既不安全也易出错。

将上述修正全部落实后，表单将准确响应用户输入，错误信息清晰可见，数据流完整可控——这是Django表单开发的推荐做法。