Django REST Framework：快速构建 Web API

FreeGuideOnline 最新 2026-06-12

Django REST Framework：快速构建 Web API

Django REST Framework（DRF）是 Django 生态中最强大的 Web API 工具包。它让你能够用极少的代码，快速构建出功能完备、安全且易于维护的 RESTful API。本教程面向初学者，将带你从零开始，掌握使用 DRF 构建 API 的核心概念与实战步骤。

1. 什么是 Django REST Framework？

Django REST Framework 是一个建立在 Django 之上的第三方库，专为构建 Web API 设计。它提供了序列化、认证、权限、视图、路由等一系列开箱即用的组件，帮助你专注于业务逻辑，而不是重复造轮子。

核心特性：

强大的序列化引擎：轻松转换复杂数据类型（如 Django 模型实例）为 JSON/XML 等格式，并支持反序列化与数据验证。
基于类的视图（CBV）：可复用的通用视图，极大减少样板代码。
内置可浏览 API：自动生成可用于开发调试的 Web 界面。
灵活的认证与权限系统：支持 Session、Token、JWT 等多种认证方式，以及细粒度的权限控制。
高度可定制：每个组件几乎都可以被替换或扩展。

2. 环境准备与项目搭建

2.1 安装 DRF

确保你已经安装 Python 和 Django。在虚拟环境中执行：

pip install djangorestframework

2.2 创建 Django 项目与应用

django-admin startproject myproject
cd myproject
python manage.py startapp api

2.3 配置 DRF

在 myproject/settings.py 中注册应用：

INSTALLED_APPS = [
    # 默认应用...
    'rest_framework',
    'api',
]

此外，如果你希望禁用可浏览 API（生产环境建议），可以添加：

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
    ]
}

现在一个基本的 DRF 项目骨架就准备好了。

3. 构建你的第一个 API

假设我们要为“图书”创建一个简单的 API。首先在 api/models.py 定义模型：

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=100)
    published_date = models.DateField()
    isbn = models.CharField(max_length=13, unique=True)
    
    def __str__(self):
        return self.title

执行迁移：

python manage.py makemigrations api
python manage.py migrate

4. 序列化器：数据转换与验证

序列化器是 DRF 的核心组件。它负责把模型实例转换为 JSON，也能将请求中的 JSON 解析并验证后保存为模型实例。

在 api/ 目录下创建 serializers.py：

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'   # 序列化全部字段
        # 或者明确列出：fields = ['id', 'title', 'author', 'published_date', 'isbn']

ModelSerializer 会自动根据模型生成一组字段和默认验证器，你只需指定模型和字段即可。它还能自动处理 create() 和 update() 方法，非常方便。

5. 视图：处理请求与响应

DRF 提供了多种编写视图的方式。最常用的是基于类的通用视图（Generic Views），它们组合了常见的 CRUD 行为。

在 api/views.py 中：

from rest_framework import generics
from .models import Book
from .serializers import BookSerializer

# 查询所有图书，并支持创建新图书
class BookListCreateView(generics.ListCreateAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

# 对单个图书进行检索、更新、删除
class BookRetrieveUpdateDestroyView(generics.RetrieveUpdateDestroyAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

只需指定 queryset 和 serializer_class，DRF 就自动为你生成了 GET（列表/详情）、POST、PUT、PATCH、DELETE 等端点逻辑。这就是 DRF 生产力惊人的原因。

6. 路由：串联视图与 URL

在 api/ 目录下创建 urls.py：

from django.urls import path
from . import views

urlpatterns = [
    path('books/', views.BookListCreateView.as_view(), name='book-list-create'),
    path('books/<int:pk>/', views.BookRetrieveUpdateDestroyView.as_view(), name='book-detail'),
]

然后在项目的 myproject/urls.py 中包含这些路由：

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls')),   # 所有 API 路由都以 /api/ 开头
]

现在启动开发服务器：

python manage.py runserver

访问 http://127.0.0.1:8000/api/books/，你会看到可浏览的 API 界面。你可以直接在这里进行 GET、POST 测试，也可以使用 curl 或 Postman。

7. 认证与权限控制

默认情况下，DRF 对所有用户开放所有操作。实际应用中必须添加认证和权限。

在 myproject/settings.py 中添加全局配置：

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.BasicAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
}

SessionAuthentication：适用于 Web 前端与 API 同域的情况，使用 Django 的会话机制。
BasicAuthentication：适用于测试或脚本，需在请求头中携带用户名密码。
IsAuthenticated：只有经过认证的用户才能访问 API。

你也可以在具体的视图里覆盖权限，例如允许任何人查看，但只有管理员可以修改：

from rest_framework.permissions import IsAuthenticated, AllowAny, IsAdminUser

class BookListCreateView(generics.ListCreateAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

    def get_permissions(self):
        if self.request.method == 'GET':
            return [AllowAny()]   # 任何人可读
        return [IsAdminUser()]    # 仅管理员可创建

8. 高级特性概览

当你熟悉基础用法后，DRF 还有大量高级功能可以探索：

视图集（ViewSets）与路由器（Routers）：进一步简化 URL 绑定，适合标准 CRUD 操作。
自定义序列化字段：如 SerializerMethodField 返回动态计算的数据。
关联模型嵌套序列化：使用 depth 或嵌套序列化器处理外键关系。
分页：对列表结果进行分页，防止大数据量一次返回。
过滤、搜索与排序：基于 django-filter 的集成，或 DRF 自带的 SearchFilter、OrderingFilter。
节流（Throttling）：限制请求频率，保护 API 免受滥用。
版本控制：通过 URL 路径或请求头管理不同 API 版本。
单元测试：APITestCase 让接口测试变得简单。

9. 实战：集成 JWT 认证示例

现代 API 多使用 Token 方案，如 JWT（JSON Web Token）。以下简要展示集成方法：

安装依赖：

pip install djangorestframework-simplejwt

在 settings.py 中修改认证类：

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

在 urls.py 中添加获取 Token 和刷新 Token 的视图：

from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns += [
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

现在，用户可以通过 POST 用户名密码到 /api/token/ 获取 access 和 refresh token，后续在请求头中添加 Authorization: Bearer <access_token> 即可访问受保护的 API。

10. 最佳实践与建议

始终使用序列化器进行数据验证，不要信任任何用户输入。
将业务逻辑放在模型、序列化器或服务层，而非视图中，保持视图轻量。
合理使用数据库查询优化：在 queryset 中使用 select_related 和 prefetch_related 避免 N+1 问题。
为 API 编写单元测试，保证接口的稳定性和正确性。
利用 DRF 的可浏览 API 进行早期调试，但生产环境可移除或限制访问。
关注 API 版本管理，避免对现有客户端造成破坏性变更。

通过掌握本教程的内容，你已经能够使用 Django REST Framework 快速、可靠地构建出生产级别的 Web API。继续动手实践，并深入阅读官方文档，你会发现 DRF 的强大远不止于此。