DjangoREST框架快速入门教程

本文是一份直击痛点的Django REST framework快速入门指南，聚焦新手最常踩的五大“秒级崩溃”场景：从安装后模块未注册导致的ModuleNotFoundError，到序列化时误用data/instance参数引发的类型错误；从router注册遗漏basename或URL路径不匹配造成的404，到前后端分离下CSRF校验与认证方式错配导致的403拦截；最后点明DRF的核心陷阱不在语法本身，而在于关键配置项（如INSTALLED_APPS、settings中REST_FRAMEWORK选项）和参数语义（instance=模型对象、data=原始数据）的精准理解——每一步都附带可立即验证的修正方案，帮你绕过文档迷雾，真正实现开箱即用。

pip install djangorestframework 装完就报错 ModuleNotFoundError

装完 djangorestframework，运行 python manage.py runserver 却提示找不到 rest_framework —— 这不是没装好，是 Django 没认到它。DRF 不是装完就自动生效的库，必须手动注册。

• 打开项目根目录下的 settings.py
• 在 INSTALLED_APPS 列表里追加 'rest_framework'（注意带引号，且是字符串）
• 别漏掉逗号，尤其加在列表末尾时：错误写法是 'django.contrib.staticfiles', 'rest_framework'（缺逗号），正确是 'django.contrib.staticfiles', 'rest_framework',
• 如果用到了认证或分页等模块，后续可能还要加 'rest_framework.authtoken'，但起步阶段只加主包就够了

serializers.py 里写 ModelSerializer 报错 'Model' object is not iterable

常见于把模型实例直接传给序列化器的 data= 参数，比如 serializer = UserSerializer(data=user_obj)。ModelSerializer 默认处理的是字典数据（即前端 POST 上来的 JSON），不是模型对象。

• 要序列化模型对象（比如查数据库后返回给前端），用 instance= 参数：UserSerializer(instance=user_obj)
• 要反序列化前端数据（比如 POST 的 JSON 创建新用户），才用 data= 参数：UserSerializer(data=request.data)
• 记得调用 .is_valid() 再取 .save() 或 .data，否则 .data 会报错或为空
• 如果模型字段有 blank=True 或 null=True，对应序列化器字段默认也会允许空，但前端没传时仍可能触发验证失败——需要显式设 required=False 控制

urls.py 配置 router.register() 后访问 /api/users/ 404

用 DefaultRouter 注册视图集后，路径 404 多半是 URL 拼接错了，或者视图集没正确继承、没实现必要方法。

• 确认视图集类继承自 viewsets.ModelViewSet（或其他具体 viewset），不是普通 APIView
• 注册时别漏掉 basename：router.register(r'users', UserViewSet, basename='user')；Django 3.1+ 如果视图集没 queryset 属性，basename 是必须的
• 检查主 urls.py 是否把 router 的 URL 包含进来了：urlpatterns += router.urls，而不是只写了 path('api/', include(router.urls)) 却忘了导入 router
• 浏览器访问路径必须严格匹配注册的 prefix，比如注册 r'users'，就该访问 /api/users/（结尾斜杠不能少，DRF 默认启用 APPEND_SLASH=True）

用 curl 测试 POST 接口返回 403 CSRF Failed

DRF 默认启用 CSRF 校验，但前后端分离场景下（比如 Vue/React 调 API），通常不走 session 认证，而是用 Token 或 JWT，这时 CSRF 反而会拦截请求。

• 开发阶段最直接的解法：在视图类或视图函数上加装饰器 @csrf_exempt（仅限调试，别上线）
• 更合理的做法是切换认证方式，在 settings.py 中配置：REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ['rest_framework.authentication.TokenAuthentication']}
• 然后在视图中声明 authentication_classes = [TokenAuthentication]，这样 DRF 就自动跳过 CSRF 检查
• 注意：使用 Token 认证时，请求头必须带 Authorization: Token xxx，否则会返回 401，不是 403

DRF 的坑不在安装，而在“哪里该配什么”和“参数传错地方”。尤其是 instance 和 data、basename 和 queryset、CSRF 和认证方式这几组，错一个字就卡住半天。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~