如何让mypy正确校验Django项目的外键、反向关联等类型？

问题背景 #

已为Django REST项目配置类型提示，安装了django-stubs和djangorestframework-stubs，mypy.ini配置如下：

[mypy]
plugins =
    mypy_django_plugin.main
    mypy_drf_plugin.main

[mypy.plugins.django-stubs]
django_settings_module = "core.settings.base"

普通模型字段的类型提示正常，但访问Django特定特性时存在两个问题：

• 访问反向关联（如示例中的u.badges）时触发类型校验错误
• 外键关联对象（如示例中的u.role）被识别为Any类型，无字段提示

示例模型代码：

class User(models.Model):
    name = models.TextField()
    role = models.ForeignKey(Role) # Role模型定义无关

class Badge(models.Model):
    user = models.ForeignKey(User, related_name="badges")

问题代码示例：

u: User = get_user()
print(u.name) # 正常提示与校验
print(u.badges.all()) # 类型错误
print(u.role.pk) # role为Any类型，无pk字段提示

解决步骤 #

1. 确保依赖版本兼容 #

检查mypy、django-stubs和djangorestframework-stubs的版本兼容性，建议升级到最新稳定版，避免版本冲突导致插件功能异常：

pip install --upgrade mypy django-stubs djangorestframework-stubs

2. 为关联字段添加显式类型注解 #

由于Django的关联字段是动态生成的，需要手动为模型添加类型注解，帮助mypy识别正确类型：

from typing import TYPE_CHECKING
from django.db import models
from django.db.models.manager import RelatedManager

# 用TYPE_CHECKING避免循环导入
if TYPE_CHECKING:
    from .models import Role, Badge

class User(models.Model):
    name = models.TextField()
    # 标注外键关联的模型类型
    role: "Role" = models.ForeignKey("Role", on_delete=models.CASCADE)
    # 标注反向关联的管理器类型
    badges: RelatedManager["Badge"]

class Badge(models.Model):
    user = models.ForeignKey(User, related_name="badges", on_delete=models.CASCADE)

3. 优化mypy配置 #

在mypy.ini中添加额外配置，确保插件能正确解析Django模型的动态属性：

[mypy]
plugins =
    mypy_django_plugin.main
    mypy_drf_plugin.main
ignore_missing_imports = true
# 若启用strict模式需调整规则，建议先关闭排查问题
strict = false

[mypy.plugins.django-stubs]
django_settings_module = "core.settings.base"
# 开启对Django不完整特性的支持，处理动态生成的模型属性
enable_incomplete_feature = true

4. 使用官方提供的类型工具 #

对于查询集等Django内置类型，直接使用django-stubs提供的类型别名，确保类型校验准确：

from django.db.models.query import QuerySet

def get_user_badges(user: User) -> QuerySet[Badge]:
    return user.badges.all()

内容的提问来源于stack exchange，提问作者Samuele B.