Python Web开发：Django REST framework 简介 – wiki基地

作者： /

Python Web 开发：Django REST framework 简介

在当今互联互通的世界中，API（Application Programming Interface，应用程序接口）已经成为构建现代 Web 应用的核心。无论是前后端分离的单页应用 (SPA)，移动 App，还是与其他服务进行数据交换，API 都扮演着至关重要的角色。Python 作为一种流行且功能强大的编程语言，在 Web 开发领域占据一席之地，其成熟的 Web 框架 Django 更是企业级应用的首选之一。然而，纯粹使用 Django 构建一套符合 RESTful 规范的 API 可能会涉及大量重复性的工作，例如数据序列化、请求解析、视图逻辑、权限控制等。

正是在这样的背景下，Django REST framework (DRF) 应运而生。它是一个强大且灵活的工具包，专为在 Django 的基础上构建 Web API 而设计。DRF 极大地简化了 API 的开发过程，提供了丰富的功能和组件，让开发者能够快速、高效地创建健壮、可维护的 RESTful API。

本文将详细探讨 Django REST framework，从其核心概念、主要组件到如何开始使用，帮助读者全面了解这个优秀的框架。

1. 为什么选择 Django REST framework？

在深入了解 DRF 之前，我们先来思考一下构建 Web API 通常需要处理哪些问题：

  • 数据序列化 (Serialization): 如何将复杂的数据类型（如 Django 模型实例或查询集）转换为易于传输的格式（如 JSON 或 XML），反之亦然（反序列化）。
  • 请求解析 (Request Parsing): 如何方便地接收和解析客户端发送的不同格式的数据（如 JSON、表单数据）。
  • 视图逻辑 (View Logic): 如何组织处理 HTTP 请求的逻辑，例如 GET, POST, PUT, DELETE 等。
  • 权限与认证 (Authentication & Permissions): 如何确认请求的身份，并控制其是否有权执行特定操作。
  • 限流 (Throttling): 如何限制用户或特定 IP 地址的请求频率，防止滥用。
  • 分页 (Pagination): 如何处理大量数据，只返回部分结果。
  • 过滤与搜索 (Filtering & Searching): 如何让客户端能够根据条件检索数据。
  • 版本控制 (Versioning): 如何在 API 迭代更新时保持向后兼容。
  • 文档 (Documentation): 如何清晰地描述 API 的使用方法。

虽然 Django 本身提供了处理 HTTP 请求和数据库交互的能力，但它并没有内置针对 API 开发的特定工具。直接使用 Django 的 View 创建 API，你需要手动处理序列化、反序列化和许多上述问题，这会非常繁琐且容易出错。

DRF 的出现正是为了解决这些问题。它在 Django 的强大功能之上，提供了一套专用的工具和抽象层，使得 API 开发变得更加高效和愉快。选择 DRF 的理由包括：

  • 强大的序列化器 (Serializers): 轻松处理模型和非模型数据的序列化与反序列化，并提供数据验证功能。
  • 灵活的视图层 (Views): 提供不同层次的视图类（APIView, Generic Views, ViewSets），简化请求处理逻辑。
  • 内置认证与权限系统: 提供了多种认证方式和精细的权限控制，确保 API 安全。
  • 可浏览的 API (Browsable API): 一个令人惊叹的特性，允许开发者和用户通过浏览器与 API 进行交互，极大地提高了开发、测试和文档生成的效率。
  • 丰富的附加功能: 内置了分页、过滤、限流、版本控制等常用功能。
  • 高度可定制: DRF 的各个组件都可以轻松扩展和定制，以满足特定需求。
  • 良好的文档和社区支持: DRF 拥有详尽的官方文档和庞大的活跃社区。

总而言之，如果你正在使用或打算使用 Django 构建 Web 应用，并且需要提供 API 接口，那么 Django REST framework 几乎是你的不二之选。

2. Django REST framework 的核心概念与组件

DRF 的强大之处在于其模块化的设计和对 RESTful 原则的良好支持。理解其核心组件是掌握 DRF 的关键。

2.1 Serializers (序列化器)

序列化器是 DRF 中最核心也可能是最重要的概念之一。它们扮演着两个主要角色：

  1. 序列化: 将复杂的数据类型（如 Django 模型实例、查询集、任意 Python 对象）转换为可以轻松渲染成标准格式（如 JSON、XML）的本地 Python 数据类型（如字典、列表）。
  2. 反序列化: 将接收到的本地 Python 数据类型（通常来自解析请求体，如 JSON）转换为复杂类型，并进行数据验证。

想象一下，你需要将一个用户模型的数据发送给前端。用户模型可能包含 username, email, date_joined 等字段。直接发送模型实例是不行的。你需要创建一个字典，将模型实例的字段值填充进去，然后再将这个字典序列化成 JSON 字符串。反过来，当前端发送用户更新数据时，你需要接收 JSON 数据，将其解析成字典，然后验证数据的格式和内容是否正确，最后用验证后的数据更新模型实例。序列化器自动化了这些繁琐的转换和验证过程。

DRF 提供了两种主要的序列化器：

  • Serializer: 通用的序列化器基类，用于处理任意数据，或者需要完全手动控制字段的情况。你需要明确定义每一个字段。
  • ModelSerializer: 强大的抽象类，可以直接从 Django 模型类自动生成一组字段，极大地简化了基于模型的数据序列化。它是日常开发中最常用的序列化器。

示例 (ModelSerializer):

假设你有一个简单的 Django 模型 myapp.models.Product:

“`python

myapp/models.py

from django.db import models

class Product(models.Model):
name = models.CharField(max_length=100)
price = models.DecimalField(max_digits=10, decimal_places=2)
description = models.TextField(blank=True)
is_available = models.BooleanField(default=True)

def __str__(self):
    return self.name

“`

你可以为其创建一个 ModelSerializer:

“`python

myapp/serializers.py

from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
class Meta:
model = Product
fields = ‘all‘ # 或者指定 [‘id’, ‘name’, ‘price’] 等需要序列化的字段
“`

使用这个序列化器：

  • 序列化单个对象:
    python
    product = Product.objects.get(id=1)
    serializer = ProductSerializer(product)
    print(serializer.data) # 返回一个字典 {'id': 1, 'name': ..., 'price': ..., ...}
  • 序列化查询集:
    python
    products = Product.objects.all()
    serializer = ProductSerializer(products, many=True) # many=True 参数表示序列化一个列表
    print(serializer.data) # 返回一个列表 [{}, {}, ...]
  • 反序列化和验证:
    python
    data = {'name': 'New Gadget', 'price': '99.99'}
    serializer = ProductSerializer(data=data)
    serializer.is_valid(raise_exception=True) # 验证数据，如果验证失败会抛出异常
    product = serializer.save() # 创建或更新模型实例（如果传入了instance参数）
    print(product)

序列化器不仅负责转换数据格式，还负责验证输入数据的有效性。你可以在序列化器中定义各种验证规则（字段类型、最大长度、唯一性等）。is_valid() 方法会执行这些验证。

2.2 Views (视图)

在 DRF 中，视图负责接收 HTTP 请求，调用序列化器处理数据，并返回 HTTP 响应。DRF 提供了多种视图基类，它们在抽象级别上有所不同：

  1. APIView: 这是 DRF 提供的最基础的视图类。它继承自 Django 的 View 类，但做了增强，例如：

    • 处理 Request 对象（DRF 的 Request 对象提供了更灵活的请求数据解析）。
    • 处理 Response 对象（DRF 的 Response 对象处理内容协商和渲染）。
    • 处理认证、权限、限流等功能。
    • 方法名对应 HTTP 方法（get, post, put, delete 等）。

    使用 APIView 时，你需要手动编写大部分逻辑，例如获取对象、序列化、保存等。这提供了最大的灵活性，适用于自定义程度高的场景。

    示例 (APIView):

    “`python

    myapp/views.py

    from rest_framework.views import APIView
    from rest_framework.response import Response
    from rest_framework import status
    from .models import Product
    from .serializers import ProductSerializer

    class ProductListAPIView(APIView):
    def get(self, request, format=None):
    products = Product.objects.all()
    serializer = ProductSerializer(products, many=True)
    return Response(serializer.data)

    def post(self, request, format=None):
    serializer = ProductSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

    “`

  2. Generic Views (通用视图): DRF 提供了一系列混合类 (Mixins) 和通用视图类，它们封装了常用的操作，如列出对象 (ListModelMixin, ListAPIView)、创建对象 (CreateModelMixin, CreateAPIView)、检索单个对象 (RetrieveModelMixin, RetrieveAPIView)、更新对象 (UpdateModelMixin, UpdateAPIView)、删除对象 (DestroyModelMixin, DestroyAPIView)。

    通过组合这些混合类，你可以快速构建符合 RESTful 风格的视图，而无需编写重复的代码。例如，ListCreateAPIView 结合了 ListModelMixin 和 CreateModelMixin，用于处理集合资源的 GET (列表) 和 POST (创建) 请求。

    示例 (Generic View):

    “`python

    myapp/views.py

    from rest_framework import generics
    from .models import Product
    from .serializers import ProductSerializer

    class ProductListCreateAPIView(generics.ListCreateAPIView):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    class ProductRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    lookup_field = ‘pk’ # 默认就是pk，这里只是为了说明
    ``
    可以看到，使用通用视图极大地减少了代码量。你只需要指定    queryset和serializer_class`。

  3. ViewSets (视图集): 视图集进一步抽象了视图的概念。它将一组相关的逻辑操作（如列表、创建、检索、更新、删除）组织到一个类中，而不是像传统视图那样每个操作对应一个独立的视图类。视图集通常与路由器 (Routers) 配合使用，由路由器自动生成对应的 URL 模式。

    最常用的视图集是 ModelViewSet，它提供了完整的 CRUD (Create, Retrieve, Update, Destroy) 操作，并且可以通过设置 queryset 和 serializer_class 快速生成一套完整的模型资源 API。ReadOnlyModelViewSet 只提供列表和检索操作。

    示例 (ViewSet):

    “`python

    myapp/views.py

    from rest_framework import viewsets
    from .models import Product
    from .serializers import ProductSerializer

    class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    ``
    使用 ViewSet 后，你不需要手动为列表、创建、检索、更新、删除等操作分别编写不同的 View 类或方法，所有这些逻辑都包含在    ProductViewSet` 中。

2.3 Requests & Responses (请求与响应)

DRF 提供了增强的 Request 和 Response 对象：

  • Request 对象: 继承自 Django 的 HttpRequest，但提供了更灵活的请求体解析。你可以通过 request.data 属性访问解析后的请求体数据，无论它是 JSON、XML 还是表单数据。DRF 会根据请求头的 Content-Type 自动选择合适的解析器 (Parsers)。
  • Response 对象: 继承自 Django 的 HttpResponse。你可以将序列化后的 Python 数据（如字典或列表）直接传递给 Response 对象，DRF 会根据请求头的 Accept 或 URL 后缀自动选择合适的渲染器 (Renderers) 将数据转换为对应的格式（如 JSON、HTML 用于可浏览 API），并设置正确的 Content-Type 响应头。这使得内容协商变得非常简单。

2.4 Authentication & Permissions (认证与权限)

安全是 API 开发的重要环节。DRF 提供了灵活的认证和权限系统来控制对 API 的访问：

  • 认证 (Authentication): 认证是确定请求发起者身份的过程。DRF 提供了多种认证类，如 SessionAuthentication (适用于基于 Session 的传统 Django 用户认证)、TokenAuthentication (基于 Token 的无状态认证，常用于移动 App 和单页应用)、BasicAuthentication 等。你也可以编写自定义认证类。
  • 权限 (Permissions): 权限是在认证之后，确定已认证用户是否有权执行特定操作的过程。DRF 提供了多种权限类，如 AllowAny (允许任何用户)、IsAuthenticated (只允许认证用户)、IsAdminUser (只允许管理员用户)、IsAuthenticatedOrReadOnly (认证用户可读写，未认证用户只读) 等。你也可以编写自定义权限类，例如检查用户是否拥有特定对象的权限。

你可以在全局设置中配置默认的认证和权限类，也可以在单个视图或视图集上通过设置 authentication_classes 和 permission_classes 属性来覆盖默认设置。

示例 (设置权限):

“`python

myapp/views.py

from rest_framework import viewsets, permissions
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
queryset = Product.objects.all()
serializer_class = ProductSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly] # 认证用户可读写，未认证用户只读

或对特定方法设置不同权限 (在ViewSet中可以这样做):

from rest_framework.decorators import action

from rest_framework.response import Response

class ProductViewSet(…):

queryset = Product.objects.all()

serializer_class = ProductSerializer

permission_classes = [permissions.IsAuthenticated] # 默认所有操作都需要认证

@action(detail=True, methods=[‘get’], permission_classes=[permissions.AllowAny])

def public_detail(self, request, pk=None):

# 这个action允许任何用户访问

product = self.get_object()

serializer = self.get_serializer(product)

return Response(serializer.data)

“`

2.5 Routers (路由器)

当使用 ViewSet 时，DRF 的路由器可以自动生成一系列 URL 模式，将 HTTP 方法映射到 ViewSet 中的相应操作（如 list, create, retrieve, update, partial_update, destroy）。这进一步减少了手动配置 URL 的工作量。

DRF 提供了两种主要的路由器：

  • DefaultRouter: 包含一个根视图，返回所有注册的视图集的超链接。
  • SimpleRouter: 不包含根视图。

通常使用 DefaultRouter 更方便，因为它提供了可浏览的根 API 页面。

示例 (使用 Router):

“`python

myproject/urls.py (假设是你的项目主 urls.py)

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from myapp import views # 假设你的ViewSets在 myapp/views.py 中

router = DefaultRouter()
router.register(r’products’, views.ProductViewSet) # 注册 ProductViewSet，对应的URL前缀是 ‘products’

urlpatterns = [
# … 其他项目的URL
path(‘api/’, include(router.urls)), # 将路由器的URL包含在 ‘api/’ 路径下
# 也可能需要登录/注销URL，特别是使用SessionAuthentication时
# path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’)),
]
“`

通过上面的配置，ProductViewSet 将会自动映射到以下 URL (假设根路径是 /api/)：

  • GET /api/products/: 对应 ViewSet 的 list 方法 (获取产品列表)
  • POST /api/products/: 对应 ViewSet 的 create 方法 (创建新产品)
  • GET /api/products/{pk}/: 对应 ViewSet 的 retrieve 方法 (获取单个产品)
  • PUT /api/products/{pk}/: 对应 ViewSet 的 update 方法 (更新单个产品，完全更新)
  • PATCH /api/products/{pk}/: 对应 ViewSet 的 partial_update 方法 (更新单个产品，部分更新)
  • DELETE /api/products/{pk}/: 对应 ViewSet 的 destroy 方法 (删除单个产品)

2.6 Parsers & Renderers (解析器与渲染器)

这是 DRF 处理内容协商的幕后功臣：

  • Parsers (解析器): 负责解析请求体中的数据。当客户端发送请求时，DRF 会检查 Content-Type 请求头，并使用对应的解析器来处理请求体数据。例如，JSONParser 用于处理 application/json，FormParser 和 MultiPartParser 用于处理表单数据。解析后的数据可以在 request.data 中访问。
  • Renderers (渲染器): 负责将视图返回的响应数据转换为发送给客户端的特定格式。当视图返回一个 Response 对象时，DRF 会检查客户端的 Accept 请求头或 URL 后缀（如 .json, .xml），并使用对应的渲染器将 Response 对象中的 Python 数据转换为相应的格式。JSONRenderer 用于生成 JSON 响应，BrowsableAPIRenderer 用于生成可浏览的 HTML 界面。

DRF 默认配置了常用的解析器和渲染器，通常你不需要直接与它们打交道，除非需要处理非标准的数据格式。

2.7 Browsable API (可浏览的 API)

这是 DRF 最受欢迎的特性之一。当你在浏览器中访问使用 DRF 构建的 API 端点时，如果使用了 BrowsableAPIRenderer（这是默认配置之一），你将看到一个美观的 HTML 界面，而不是原始的 JSON 或 XML 数据。

这个界面展示了 API 的端点、可用的 HTTP 方法、请求参数表单、响应数据等信息，甚至可以直接在界面中填写表单并发送请求进行测试。这对于开发、调试和非正式的 API 文档来说非常方便。

![Browsable API Example (Conceptual – Replace with actual screenshot if possible in a real article)]

（此处想象一个截图：展示一个 DRF 的 browsable API 页面，上面有请求方法按钮（GET, POST等）、URL输入框、请求体输入区域、以及下方显示响应头和响应体的区域）

可浏览 API 的存在大大降低了测试 API 的门槛，尤其是对于刚接触 API 或不熟悉命令行工具（如 curl）的开发者。

3. 开始使用 Django REST framework

要开始使用 DRF，你需要遵循以下基本步骤：

  1. 安装 DRF:
    使用 pip 安装 DRF：
    bash
    pip install djangorestframework

  2. 添加到 INSTALLED_APPS:
    在你的 Django 项目的 settings.py 文件中，将 rest_framework 添加到 INSTALLED_APPS 列表中：
    python
    # settings.py
    INSTALLED_APPS = [
    # ... 其他应用
    'rest_framework',
    # ... 你的应用，例如 'myapp',
    ]

  3. 配置全局设置 (可选):
    你可以在 settings.py 中配置 DRF 的全局设置，例如默认的认证类、权限类、分页样式等。
    python
    # settings.py
    REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
    'rest_framework.authentication.SessionAuthentication',
    'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
    'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10, # 每页显示10条数据
    'DEFAULT_RENDERER_CLASSES': [
    'rest_framework.renderers.JSONRenderer',
    'rest_framework.renderers.BrowsableAPIRenderer',
    ],
    'DEFAULT_PARSER_CLASSES': [
    'rest_framework.parsers.JSONParser',
    'rest_framework.parsers.FormParser',
    'rest_framework.parsers.MultiPartParser',
    ],
    }
    这些设置提供了合理的默认值，如果你有特定需求，可以根据 DRF 文档进行修改。

  4. 创建 Serializers:
    为你的模型或其他需要通过 API 暴露的数据创建序列化器，通常放在应用的 serializers.py 文件中。

  5. 创建 Views 或 ViewSets:
    根据需求选择 APIView、Generic Views 或 ViewSets 来处理 API 请求，通常放在应用的 views.py 文件中。使用 ViewSets 和 Routers 通常是最快捷的方式来构建标准的 RESTful API。

  6. 配置 URLs:
    在你的项目或应用的 urls.py 文件中配置 URL 模式，将 URL 路径映射到你的视图或 ViewSet。如果使用 ViewSet，推荐使用 DRF 的 Router。

  7. 可选：添加认证 URL (如果使用 Session 或 Token 认证):
    如果你使用了 SessionAuthentication 或 TokenAuthentication，并且希望在可浏览 API 中看到登录/注销选项，可以在项目主 urls.py 中包含 DRF 提供的认证 URL：
    “`python
    # myproject/urls.py
    from django.urls import path, include

    urlpatterns = [
    # … 其他URL
    path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’)),
    # … 你的API URL，例如 path(‘api/’, include(router.urls)),
    ]
    “`

完成这些步骤后，你的 Django 应用就具备了提供 RESTful API 的能力。

4. DRF 的高级功能 (简述)

除了核心组件，DRF 还提供了许多高级功能来处理复杂的 API 场景：

  • 分页 (Pagination): 内置多种分页样式（如页码分页 PageNumberPagination、偏移量分页 LimitOffsetPagination、游标分页 CursorPagination），可以轻松地将大的数据集分页返回。
  • 过滤与搜索 (Filtering & Searching): 可以集成 Django 过滤后端（如 django-filter）和 DRF 的搜索后端，允许客户端通过 URL 参数进行数据过滤和全文搜索。
  • 版本控制 (Versioning): 提供了多种 API 版本控制方案（如 URL 参数版本、Namespace 版本、Host 版本、Header 版本），帮助你在不破坏现有客户端的情况下迭代更新 API。
  • 限流 (Throttling): 基于用户或 IP 地址限制请求频率，保护 API 免受过载。
  • 自定义字段、序列化器、视图和解析器/渲染器: DRF 的设计高度灵活，你可以轻松地扩展或完全替换其默认组件，以满足独特的业务需求。
  • 测试工具: DRF 提供了一些辅助工具，如 APITestCase 和 APIClient，用于编写 API 单元测试和集成测试。

5. 总结

Django REST framework 是构建基于 Django 的 Web API 的首选框架。它通过提供强大的序列化器、灵活的视图系统、内置的认证与权限、便捷的路由器以及令人印象深刻的可浏览 API 等核心组件，极大地简化了 API 的开发过程。

DRF 遵循 RESTful 设计原则，鼓励开发者编写结构清晰、易于理解和维护的 API 代码。其丰富的内置功能（如分页、过滤、限流）和高度可定制性使其能够应对各种复杂的 API 场景。

无论是从零开始构建一个新的 API 服务，还是为现有的 Django 项目添加 API 功能，DRF 都能显著提高开发效率和 API 的质量。对于任何 Django 开发者来说，掌握 Django REST framework 都是一项极具价值的技能。

通过本文的介绍，希望读者对 DRF 的核心概念和优势有了清晰的认识。下一步是查阅官方文档，通过实践来深入学习和掌握这个强大的工具。开始尝试使用 ModelSerializer 和 ModelViewSet 快速构建第一个 API 端点吧，你会发现 DRF 的魅力所在！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部