Django自定义UserCreationForm的clean_username校验未正常抛出ValidationError

问题场景 #

基于Django的django.contrib.auth扩展了自定义User模型（继承BaseUserManager和AbstractBaseUser），同时实现了自定义注册表单SignUpForm（继承UserCreationForm）。在SignUpForm的clean_username方法中添加了两项校验：

• 禁止仅含非字母数字的用户名（如-@、--_），预期触发时抛出ValidationError
• 校验slug唯一性

测试时发现：明明已经触发了抛出ValidationError的分支（通过打印日志确认），但form.is_valid()仍返回True，导致视图执行后续逻辑，触发User模型的clean方法。由于模型层也有相同校验逻辑，此时会抛出ValueError，无法在表单上展示友好的错误提示，影响用户体验。

原因排查 #

1. 表单重写逻辑疏漏：clean_username方法可能存在异常未被正确抛出、或被意外捕获的情况，导致表单未识别到错误。
2. 模型层异常类型错误：模型clean方法抛出的是ValueError而非Django标准的ValidationError，无法被表单捕获，直接中断流程。

解决方案 #

1. 修正表单的clean_username方法 #

确保方法逻辑正确，异常抛出符合Django规范：

# forms.py
from django import forms
from django.contrib.auth.forms import UserCreationForm
from django.core.exceptions import ValidationError
from .models import CustomUser

class SignUpForm(UserCreationForm):
    class Meta:
        model = CustomUser
        fields = ('username', 'email', 'password1', 'password2')

    def clean_username(self):
        username = self.cleaned_data.get('username')
        # 校验用户名是否包含至少一个字母/数字
        if not any(c.isalnum() for c in username):
            print("触发非字母数字校验异常")
            raise ValidationError("用户名必须包含至少一个字母或数字")
        # 校验slug唯一性（假设slug由用户名生成）
        target_slug = username.replace(' ', '-')
        if CustomUser.objects.filter(slug=target_slug).exists():
            raise ValidationError("该用户名已被使用，请更换")
        # 调用父类方法，保留原生的用户名唯一性校验（可选，根据需求调整）
        return super().clean_username()

2. 修正模型层的clean方法 #

将ValueError替换为Django标准的ValidationError，确保错误能被表单捕获：

# models.py
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager
from django.db import models
from django.core.exceptions import ValidationError

class CustomUserManager(BaseUserManager):
    # 自定义管理器实现（略）
    def create_user(self, username, email, password=None, **extra_fields):
        # 逻辑实现...

class CustomUser(AbstractBaseUser):
    username = models.CharField(max_length=150, unique=True)
    slug = models.SlugField(max_length=150, unique=True)
    email = models.EmailField(unique=True)
    # 其他字段定义...

    objects = CustomUserManager()

    USERNAME_FIELD = 'username'
    REQUIRED_FIELDS = ['email']

    def clean(self):
        super().clean()
        # 用户名格式校验
        if not any(c.isalnum() for c in self.username):
            raise ValidationError({"username": "用户名必须包含至少一个字母或数字"})
        # slug唯一性校验（排除自身，支持更新场景）
        if CustomUser.objects.filter(slug=self.slug).exclude(pk=self.pk).exists():
            raise ValidationError({"slug": "该标识已存在"})

3. 视图层确保错误正确返回 #

在注册视图中，确保表单无效时携带错误信息返回模板：

# views.py
from django.shortcuts import render, redirect
from .forms import SignUpForm

def signup(request):
    if request.method == 'POST':
        form = SignUpForm(request.POST)
        if form.is_valid():
            user = form.save(commit=False)
            # 自动生成slug（如果需要）
            user.slug = user.username.replace(' ', '-')
            user.save()
            return redirect('home')
        # 表单无效时，直接返回带错误的表单
        return render(request, 'signup.html', {'form': form})
    else:
        form = SignUpForm()
        return render(request, 'signup.html', {'form': form})

关键注意事项 #

• 表单字段的clean方法中，抛出ValidationError后无需返回值（异常会中断clean流程）；如果需要保留父类的校验逻辑，务必调用super().clean_username()并返回结果。
• 模型层的clean方法必须使用ValidationError（可指定错误关联的字段），不能用普通的ValueError，否则错误无法被表单捕获展示。
• 确保表单的Meta类正确关联自定义User模型，且包含需要校验的字段。

内容的提问来源于stack exchange，提问作者DevinG