Django自定义User模型与Mypy类型检查：解决字段重定义不兼容错误

1. 问题背景：Django自定义User模型与Mypy类型冲突

在django项目中，为了满足特定的业务需求，通常会自定义用户模型。最常见的方式是继承django内置的abstractuser类。abstractuser提供了一个功能完备的用户模型，包含了如用户名、密码、电子邮件、姓名、激活状态、员工状态、超级用户状态以及权限系统等常用字段。然而，当开发者需要对abstractuser中已定义的某个字段进行修改（例如，改变email字段的null、blank或unique属性，或其索引行为）时，可能会遇到类型检查工具mypy报错。

例如，以下代码尝试重定义email字段：

from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    # ... 其他字段或方法 ...
    email = models.EmailField(db_index=True, blank=True, null=True, unique=True)
    # ...

当运行mypy进行类型检查时，可能会收到如下错误信息：

error: Incompatible types in assignment (expression has type "EmailField[str | int | Combinable | None, str | None]", base class "AbstractUser" defined the type as "EmailField[str | int | Combinable, str]") [assignment]

这个错误表明，在User类中对email字段的重新赋值，其类型与父类AbstractUser中email字段的定义不兼容。mypy认为AbstractUser已经为email字段设定了严格的类型（例如，不允许None值），而自定义的定义（例如，null=True）引入了None的可能性，从而导致类型不匹配。简单地使用# type: ignore来忽略此错误会导致更深层次的问题，因为mypy将无法确定email字段的类型，从而在整个代码库中引发大量的Cannot determine type of "email"错误，失去了类型检查的意义。

2. 解决方案：转向AbstractBaseUser

解决此类型不兼容问题的根本方法是改变自定义User模型的继承基类。AbstractUser是AbstractBaseUser的一个具体实现，它在AbstractBaseUser的基础上添加了许多常用字段。AbstractBaseUser则是一个更底层的抽象类，它只提供了用户认证所需的核心功能（如密码散列和会话管理），但不包含任何具体的用户信息字段（如用户名、电子邮件、姓名、权限等）。

通过继承AbstractBaseUser，开发者可以完全自由地定义用户模型的所有字段，包括那些在AbstractUser中预定义的字段。为了保留AbstractUser所提供的权限系统功能（如is_staff, is_superuser, groups, user_permissions），还需要同时继承PermissionsMixin。

以下是修改后的自定义User模型示例：

from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
from django.db import models
from django.utils.translation import gettext_lazy as _

class User(AbstractBaseUser, PermissionsMixin):
    # 必须定义一个字段作为 USERNAME_FIELD，例如 email
    email = models.EmailField(_('email address'), db_index=True, blank=True, null=True, unique=True)

    # 必须定义一个字段作为唯一标识符，通常是 email 或 username
    USERNAME_FIELD = 'email'
    # 必须定义在创建超级用户时需要输入的字段列表
    REQUIRED_FIELDS = [] # 如果 email 是唯一标识符且允许为 None，则不需要其他必填字段

    # 添加 AbstractUser 中常见的字段，以保持功能完整性
    first_name = models.CharField(_('first name'), max_length=150, blank=True)
    last_name = models.CharField(_('last name'), max_length=150, blank=True)
    is_staff = models.BooleanField(
        _('staff status'),
        default=False,
        help_text=_('Designates whether the user can log into this admin site.'),
    )
    is_active = models.BooleanField(
        _('active'),
        default=True,
        help_text=_(
            'Designates whether this user should be treated as active. '
            'Unselect this instead of deleting accounts.'
        ),
    )
    date_joined = models.DateTimeField(_('date joined'), auto_now_add=True)

    objects = UserManager() # 需要自定义一个 UserManager 来处理用户创建

    class Meta:
        verbose_name = _('user')
        verbose_name_plural = _('users')

    def clean(self):
        super().clean()
        self.email = self.__class__.objects.normalize_email(self.email)

    def get_full_name(self):
        """
        Returns the first_name plus the last_name, with a space in between.
        """
        full_name = '%s %s' % (self.first_name, self.last_name)
        return full_name.strip()

    def get_short_name(self):
        """Returns the short name for the user."""
        return self.first_name

    def email_user(self, subject, message, from_email=None, **kwargs):
        """Send an email to this user."""
        send_mail(subject, message, from_email, [self.email], **kwargs)

重要注意事项：

1. USERNAME_FIELD: 当使用AbstractBaseUser时，你必须在自定义User模型中指定一个唯一的字段作为USERNAME_FIELD。这通常是email或一个自定义的username字段。

2. REQUIRED_FIELDS: 你还需要定义REQUIRED_FIELDS列表，它包含了在通过createsuperuser命令创建用户时，除了USERNAME_FIELD和密码之外，必须提供的字段。

3. 自定义UserManager: AbstractBaseUser不提供默认的objects管理器来处理用户创建。你需要创建一个自定义的UserManager，它需要实现create_user和create_superuser方法。例如：

   from django.contrib.auth.models import BaseUserManager
   
   class UserManager(BaseUserManager):
       def create_user(self, email, password=None, **extra_fields):
           if not email:
               raise ValueError('The Email field must be set')
           email = self.normalize_email(email)
           user = self.model(email=email, **extra_fields)
           user.set_password(password)
           user.save(using=self._db)
           return user
   
       def create_superuser(self, email, password=None, **extra_fields):
           extra_fields.setdefault('is_staff', True)
           extra_fields.setdefault('is_superuser', True)
           extra_fields.setdefault('is_active', True)
   
           if extra_fields.get('is_staff') is not True:
               raise ValueError('Superuser must have is_staff=True.')
           if extra_fields.get('is_superuser') is not True:
               raise ValueError('Superuser must have is_superuser=True.')
           return self.create_user(email, password, **extra_fields)
   

   登录后复制

   然后将此管理器赋值给User模型的objects属性：objects = UserManager()。

3. 优势与考量

优势：

• 完全的字段控制： 继承AbstractBaseUser提供了对用户模型字段的完全控制，避免了与父类预定义字段的类型冲突，尤其是在使用mypy等严格类型检查工具时。
• 更清晰的职责分离： AbstractBaseUser专注于认证核心逻辑，而PermissionsMixin则处理权限，使模型结构更清晰。
• 解决Mypy错误： 这是解决mypy在重定义AbstractUser字段时报告的Incompatible types错误的最直接和推荐的方法。

考量：

• 更多的样板代码： 相较于AbstractUser，使用AbstractBaseUser意味着你需要手动定义所有常用字段（如first_name, last_name, is_staff, is_active, date_joined等），并实现自定义的UserManager。这增加了初始设置的复杂性。
• 迁移影响： 如果项目已上线且使用了继承AbstractUser的自定义模型，切换到AbstractBaseUser可能需要进行数据迁移，确保现有用户数据能够正确映射到新模型结构。务必在生产环境部署前进行充分测试。

4. 总结

当Django项目与mypy集成时，重定义AbstractUser中预设字段的类型冲突是一个常见问题。通过将自定义User模型从继承AbstractUser改为继承AbstractBaseUser和PermissionsMixin，开发者可以获得对用户模型字段的完全控制，从而彻底解决mypy的类型不兼容错误。尽管这会引入一些额外的样板代码，但从长远来看，它提供了更大的灵活性和更严格的类型安全性，是构建健壮Django应用的重要实践。务必记住，在切换基类时，正确实现USERNAME_FIELD、REQUIRED_FIELDS以及自定义UserManager至关重要。

以上就是Django自定义User模型与Mypy类型检查：解决字段重定义不兼容错误的详细内容，更多请关注php中文网其它相关文章！