理解Mypy类型冲突的根源
Django的AbstractUser模型是一个功能完备的用户模型，它预定义了许多标准字段，包括email、first_name、last_name等，并为这些字段设置了特定的类型注解。当您在自定义的User模型中继承AbstractUser并尝试重新定义这些字段时，即使字段名相同，但如果其类型参数（例如null=True, blank=True, unique=True等）与基类定义的类型签名不完全匹配，Mypy就会将其视为类型不兼容的赋值。
例如，AbstractUser可能将email定义为非空的EmailField，而您将其重定义为可空 (null=True) 的EmailField。尽管这在Django ORM层面是允许的，但Mypy会认为您正在尝试用一个类型为EmailField[str | int | Combinable | None, str | None]的字段覆盖一个类型为EmailField[str | int | Combinable, str]的字段，从而抛出Incompatible types in assignment错误。
简单地使用# type: ignore来抑制此错误虽然能让Mypy通过，但会导致更深层次的问题。Mypy将无法推断被忽略字段的准确类型，从而在代码库中其他地方引用该字段时产生Cannot determine type of "email"等错误，这违背了使用Mypy进行强类型检查的初衷。
解决方案：转向AbstractBaseUser
解决此Mypy类型冲突的最有效且推荐的方法是，将自定义用户模型的基类从AbstractUser更改为AbstractBaseUser。
AbstractBaseUser是Django用户模型的最底层抽象，它仅提供了核心的认证功能（如密码哈希、会话管理等），但不包含任何预定义的字段（如email、username、first_name等）。这意味着您可以完全自由地定义您的用户模型所需的任何字段，而不会与基类的预定义字段产生类型冲突。
由于AbstractBaseUser不包含权限相关的字段和方法，如果您的自定义用户模型需要使用Django的权限系统（例如is_staff, is_superuser, groups, user_permissions等），您还需要同时继承PermissionsMixin。
实现步骤与示例代码
以下是如何修改您的自定义User模型以使用AbstractBaseUser和PermissionsMixin的示例：
from django.db import models
from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin, UserManager
from django.utils import timezone
from django.utils.translation import gettext_lazy as _
class User(AbstractBaseUser, PermissionsMixin):
"""
自定义用户模型，继承AbstractBaseUser和PermissionsMixin，
提供更灵活的字段定义。
"""
email = models.EmailField(
_("email address"),
db_index=True,
blank=True,
null=True, # 允许为空，与AbstractUser默认行为不同
unique=True,
help_text=_("Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.")
)
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"), default=timezone.now)
# 必须定义USERNAME_FIELD，它是一个唯一标识符，用于认证
USERNAME_FIELD = "email"
# 定义REQUIRED_FIELDS，当通过createsuperuser命令创建用户时会提示输入的字段
REQUIRED_FIELDS = [] # 如果email是USERNAME_FIELD且允许为空，则这里可以为空
# 必须指定一个管理器
objects = UserManager()
class Meta:
verbose_name = _("user")
verbose_name_plural = _("users")
db_table = "custom_user" # 可选，自定义表名
def clean(self):
super().clean()
self.email = self.__class__.objects.normalize_email(self.email)
def get_full_name(self):
"""
返回用户的全名。
"""
full_name = "%s %s" % (self.first_name, self.last_name)
return full_name.strip()
def get_short_name(self):
"""
返回用户的短名。
"""
return self.first_name
def __str__(self):
"""
用户对象的字符串表示。
"""
return self.email if self.email else f"User ID: {self.pk}"
关键点说明：
- 继承基类更改： 从AbstractUser改为AbstractBaseUser, PermissionsMixin。
- email字段重定义： 现在您可以完全控制email字段的定义，包括null=True等参数，Mypy将不再报错。
-
强制性字段和方法： 使用AbstractBaseUser意味着您需要自行定义一些AbstractUser默认提供的字段和方法：
- USERNAME_FIELD: 必须定义，指定用于认证的唯一标识符（例如'email'或'username'）。
- REQUIRED_FIELDS: 列表，当使用createsuperuser命令时会提示用户输入的字段。
- is_active: 布尔字段，表示用户是否活跃。
- is_staff: 布尔字段，表示用户是否可以访问管理站点。
- get_full_name(): 返回用户的全名。
- get_short_name(): 返回用户的短名。
- objects: 必须指定一个管理器，通常是django.contrib.auth.models.UserManager或自定义的管理器。
- __str__(): 返回用户对象的字符串表示。
- date_joined: 建议添加，用于记录用户创建时间。
- clean(): 可选，用于数据清理，如规范化邮箱地址。
优点与注意事项
优点：
- 完全的字段控制： 您可以完全自定义用户模型的所有字段，包括名称、类型和各种参数，而不会受到基类的限制。
- Mypy兼容性： 彻底解决了因重定义字段导致的Mypy类型不兼容问题，保持了代码库的类型安全。
- 清晰的类型推断： Mypy能够准确推断自定义字段的类型，避免了Cannot determine type的错误。
- 灵活性： 为未来的用户模型扩展提供了更大的灵活性。
注意事项：
- 增加的样板代码： 切换到AbstractBaseUser会增加一些必要的样板代码，因为您需要手动实现AbstractUser默认提供的一些字段和方法。确保您已正确定义了USERNAME_FIELD、REQUIRED_FIELDS、is_active、is_staff以及get_full_name()、get_short_name()等方法。
- 迁移： 如果您的项目已经投入生产并使用了基于AbstractUser的自定义模型，切换到AbstractBaseUser将需要进行数据库迁移。请务必在开发环境中充分测试此更改，并备份数据。
- 管理器： 确保为您的自定义用户模型指定了正确的管理器（通常是UserManager），以便Django能够正确地创建和管理用户。
总结
当您在Django自定义用户模型中遇到Mypy因重定义字段而产生的类型冲突时，最健壮的解决方案是采用AbstractBaseUser作为基类，并根据需要结合PermissionsMixin。这种方法虽然会引入一些额外的样板代码，但它赋予了您对用户模型字段的完全控制权，彻底解决了Mypy的类型兼容性问题，并确保了代码库的类型安全性和可维护性。在追求严格类型检查的现代Python开发中，这种策略是构建健壮Django应用的关键一步。
