Django REST Framework 构建 Web API 入门指南

直接回答：Django REST Framework（DRF）把 Django 变成专业的 API 工厂：Serializer 负责数据校验与序列化，ViewSet + Router 自动生成 RESTful 端点，认证权限体系开箱即用，还自带可交互的 API 浏览页面。

DRF 的四件法宝

• Serializer：模型 ↔ JSON 的转换层，校验规则集中声明；
• ViewSet：一组资源操作的集合（list/create/retrieve/update/destroy）；
• Router：一行注册，自动生成全部 URL；
• Browsable API：浏览器直接调试接口，联调神器。

搭建项目

pip install djangorestframework
django-admin startproject tasks_api && cd tasks_api
python manage.py startapp tasks

# settings.py
INSTALLED_APPS = [..., "rest_framework", "tasks"]

定义模型

# tasks/models.py
from django.db import models

class Task(models.Model):
    title = models.CharField(max_length=200)
    done = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

makemigrations && migrate。

Serializer：数据的翻译官

# tasks/serializers.py
from rest_framework import serializers
from .models import Task

class TaskSerializer(serializers.ModelSerializer):
    class Meta:
        model = Task
        fields = ["id", "title", "done", "created_at"]
        read_only_fields = ["created_at"]

ModelSerializer 自动映射模型字段；自定义校验加 validate_title 方法，非法数据返回 400 与字段级错误。

视图与路由

# tasks/views.py
from rest_framework import viewsets, permissions
from .models import Task
from .serializers import TaskSerializer

class TaskViewSet(viewsets.ModelViewSet):
    queryset = Task.objects.order_by("-created_at")
    serializer_class = TaskSerializer
    permission_classes = [permissions.IsAuthenticated]

# urls.py
from rest_framework.routers import DefaultRouter
from django.urls import path, include
from tasks.views import TaskViewSet

router = DefaultRouter()
router.register("tasks", TaskViewSet)
urlpatterns = [path("api/", include(router.urls))]

一个类换来完整 REST：

配置认证并登录后可使用可浏览 API。IsAuthenticated 只检查登录；多租户应按 request.user 过滤 queryset，并在创建及对象操作中检查所属权。

下一步

• 认证权限：DEFAULT_PERMISSION_CLASSES 配 IsAuthenticated，令牌用 authtoken 或 JWT（djangorestframework-simplejwt）；
• 分页过滤：同时配置 DEFAULT_PAGINATION_CLASS 与 PAGE_SIZE；过滤需配置 filter_backends 和 django-filter；
• 限流：DEFAULT_THROTTLE_CLASSES 用于业务限流，不是暴力破解或 DDoS 防御边界。

常见问题（FAQ）

Q：DRF 和 FastAPI 怎么选？
A：已在用 Django（尤其需要 Admin/ORM 联动）选 DRF；纯 API 新项目、要异步与自动 OpenAPI 选 FastAPI。两者都优秀，看项目地基。

Q：ViewSet 和 APIView 怎么分工？
A：标准 CRUD 用 ViewSet+Router 最省；不符合 REST 形态的端点（登录、聚合报表）用 APIView 自由发挥。

Q：嵌套序列化性能差怎么办？
A：嵌套 Serializer 是 N+1 重灾区：queryset 里 select_related/prefetch_related 配好；列表接口考虑用扁平字段替代深嵌套。

官方参考

本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。

• 官方资料 1

延伸阅读

• HTTPX 入门：Python 的现代 HTTP 客户端
• FastAPI 构建 Web API 入门指南