运行./manage.py makemigrations时drf_spectacular生成schema抛出异常如何解决

错误根因 #

运行./manage.py makemigrations时触发的drf_spectacular.E001错误，是因为drf_spectacular的schema自动生成逻辑在Django系统检查阶段执行时，调用了对global_preferences表的数据库查询，而此时该表尚未通过migrations创建，因此触发关系不存在的报错。

临时解决方案 #

执行命令时跳过Django系统检查，直接生成迁移文件：

./manage.py makemigrations --skip-checks

迁移文件生成后执行表创建：

./manage.py migrate

待global_preferences表创建完成后，后续执行Django相关命令将不会再触发该报错。

永久修复方案 #

该问题本质是项目代码中存在模块加载阶段就执行数据库查询的逻辑，常见于django-preferences等全局偏好配置包的调用，需要调整代码写法：

1. 排查所有视图、序列化器、全局配置文件中的顶层查询代码，例如以下错误写法会在模块导入时直接触发数据库查询：

# 错误示例：顶层代码直接执行ORM查询
from preferences.models import GlobalPreferences
default_config = GlobalPreferences.objects.values_list("preferences", flat=True).first()

2. 将所有顶层的数据库查询逻辑移到方法/函数内部，实现延迟调用：

# 修正示例：查询逻辑放在方法内部，仅在实际调用时执行
def get_default_config():
    from preferences.models import GlobalPreferences
    return GlobalPreferences.objects.values_list("preferences", flat=True).first()

3. 也可以在settings.py中添加drf_spectacular配置，关闭迁移场景下的schema检查：

SPECTACULAR_SETTINGS = {
    # 其他配置保持不变
    'DISABLE_ERRORS_AND_WARNINGS': True,
}

版本适配说明 #

你当前使用的Django 3.2.4 + DRF 3.12的环境，建议搭配0.24.0及以上版本的drf_spectacular，避免出现版本兼容类的schema生成错误。

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