在 django 开发中，为满足特定业务需求，我们常常需要创建自定义用户模型。一种常见做法是继承 django 内置的 abstractuser 类。然而，当尝试重定义 abstractuser 中已有的字段，例如 email，并同时启用 mypy 进行类型检查时，可能会遇到 mypy 报错“incompatible types in assignment”的问题。本文将深入分析这一问题的原因，并提供一个推荐的解决方案，以确保类型安全和代码的灵活性。
问题背景与Mypy类型冲突
AbstractUser 是 Django 提供的一个功能完整的用户模型基类，它预定义了包括 username、email、first_name、last_name、is_staff、is_active、date_joined 等一系列常用字段及其默认行为。当我们在自定义的 User 模型中，再次声明并重定义了 AbstractUser 中已有的字段，例如将 email 字段的 null 或 unique 属性进行修改：
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（结合 django-stubs）进行类型检查时，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]
这个错误表明，尽管我们重定义的 email 字段在语义上与 AbstractUser 中的 email 字段相似，但其具体的类型签名（例如是否允许 None 值）与基类中预定义的类型不完全匹配，导致 mypy 认为这是一个不兼容的类型赋值。简单地使用 # type: ignore 注释来抑制错误并非长久之计，因为它会导致其他地方的 Cannot determine type 错误，从而削弱了 mypy 的类型保护作用。
根本原因分析
AbstractUser 的设计理念是提供一个开箱即用的用户模型，其内部字段已经有了明确的定义和类型提示。当子类尝试以不同的类型签名（即使只是 null=True 或 unique=True 的差异，这些会影响 django-stubs 生成的类型提示）来覆盖这些字段时，mypy 会将其视为类型不兼容。django-stubs 致力于为 Django 模型提供准确的类型信息，因此它会严格检查这种继承链上的类型一致性。
解决方案：拥抱AbstractBaseUser
解决此问题的最有效且推荐的方法是，将自定义用户模型的基类从 AbstractUser 更改为更底层的 AbstractBaseUser。
AbstractBaseUser 是 Django 用户模型体系中最基础的抽象类。它仅提供了用户认证所需的核心功能，例如密码管理、最近登录时间以及 is_active 状态。与 AbstractUser 不同，AbstractBaseUser 不包含 email、first_name、last_name、is_staff 等字段。这意味着，当您继承 AbstractBaseUser 时，您可以完全自由地定义这些字段，而不会与基类的预定义类型发生冲突。
为了在继承 AbstractBaseUser 的同时，仍然拥有 Django 默认的用户权限系统（如 is_superuser、groups、user_permissions），您还需要同时继承 PermissionsMixin。
以下是使用 AbstractBaseUser 和 PermissionsMixin 构建自定义用户模型的示例：
from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin, BaseUserManager
from django.db import models
from django.utils import timezone
# 推荐定义一个自定义的用户管理器
class CustomUserManager(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)
class User(AbstractBaseUser, PermissionsMixin):
email = models.EmailField(db_index=True, blank=True, null=True, unique=True)
first_name = models.CharField(max_length=150, blank=True)
last_name = models.CharField(max_length=150, blank=True)
is_staff = models.BooleanField(default=False)
is_active = models.BooleanField(default=True)
date_joined = models.DateTimeField(default=timezone.now)
# 必须定义 USERNAME_FIELD，用于指定用户认证的唯一标识符
USERNAME_FIELD = 'email'
# 必须定义 REQUIRED_FIELDS，用于通过 createsuperuser 命令创建用户时需要输入的字段
# 注意：USERNAME_FIELD 和 password 字段不应包含在此列表中
REQUIRED_FIELDS = []
# 关联自定义管理器
objects = CustomUserManager()
class Meta:
verbose_name = 'user'
verbose_name_plural = 'users'
def __str__(self):
return 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注意事项与权衡
- 增加的样板代码： 切换到 AbstractBaseUser 意味着您需要手动定义 AbstractUser 中默认提供的所有字段（如 first_name, last_name, is_staff, date_joined 等），以及实现一些辅助方法（如 get_full_name, get_short_name）。此外，您还需要定义一个自定义的用户管理器 (BaseUserManager 的子类)，用于处理用户和超级用户的创建逻辑。
- 灵活性： 尽管增加了样板代码，但这种方法提供了极致的灵活性。您可以完全控制用户模型的结构，定义任何您需要的字段，并确保它们与 mypy 的类型检查兼容。这对于需要高度定制用户模型的项目尤其有利。
- 迁移考量： 如果您是在一个现有项目中从 AbstractUser 切换到 AbstractBaseUser，您需要谨慎处理数据库迁移。这可能涉及到删除旧字段、添加新字段，并可能需要数据迁移脚本来将现有数据映射到新的模型结构。在进行此类更改前，务必进行充分的测试和备份。
总结
当 Django 自定义用户模型在继承 AbstractUser 并重定义内置字段时遇到 mypy 的类型不兼容错误，最佳实践是转向继承 AbstractBaseUser 并结合 PermissionsMixin。这种方法虽然要求更多的手动配置和样板代码，但它提供了对用户模型字段的完全控制，彻底解决了 mypy 的类型冲突问题，并为构建高度定制化且类型安全的用户模型奠定了坚实基础。在追求代码质量和类型安全性的现代 Python 开发中，理解并采纳这种策略至关重要。
