Django REST Framework 完整介绍与使用指南 – wiki词典

作者： /

Django REST Framework (DRF) 完整介绍与使用指南

Django REST Framework (DRF) 是一个强大且灵活的工具包，用于使用 Django 构建 Web API。它扩展了 Django 的功能，提供了一套强大的数据建模、URL 路由和视图处理工具，是现代 Web 开发的基石。

为什么使用 Django REST Framework？

DRF 通过提供以下几个关键功能，简化了 RESTful API 的创建：

  • 序列化 (Serialization)：将复杂的 Python 数据类型（例如 Django 模型实例和查询集）转换为可以轻松渲染为 JSON、XML 或其他内容类型的原生 Python 数据类型。它还处理反序列化，验证传入数据。
  • Web 可浏览 API (Web Browsable API)：为您的 API 提供用户友好的交互式 HTML 界面，这对于开发人员来说是一个显著的可用性优势。
  • 认证和权限 (Authentication and Permissions)：提供灵活的认证策略和自定义权限类来保护您的 API 端点。
  • 通用视图和视图集 (Generic Views and ViewSets)：提供预构建的视图和视图集，以最少的代码处理常见的 API 模式（如 CRUD 操作）。
  • 路由器 (Routers)：自动为视图集生成 URL 模式，简化 URL 配置。

安装与设置

要开始使用 Django REST Framework，请按照以下步骤操作：

  1. 先决条件: 确保您已安装 Python 和 Django。建议在虚拟环境中工作。
  2. 安装 DRF: 使用 pip 安装 djangorestframework 包：
    bash
    pip install djangorestframework
  3. 添加到 INSTALLED_APPS: 打开您的 Django 项目的 settings.py 文件，并将 'rest_framework' 添加到您的 INSTALLED_APPS 列表中：
    python
    # settings.py
    INSTALLED_APPS = [
    # ...
    'rest_framework',
    # ... your apps
    ]
    如果您计划使用可浏览 API 的登录/注销功能，您可能还需要添加 Django 的认证应用程序：
    python
    # settings.py
    INSTALLED_APPS = [
    # ...
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'rest_framework',
    # ...
    ]

核心概念与使用

让我们通过一个简单的示例来了解 DRF 的核心组件。

1. 模型 (Models)

首先，定义一个简单的 Django 模型。例如，在名为 library 的应用程序中创建一个 Book 模型：

“`python

library/models.py

from django.db import models

class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=100)
publication_date = models.DateField()
isbn = models.CharField(max_length=13, unique=True)

def __str__(self):
    return self.title

“`

创建模型后，请记住进行数据库迁移：

bash
python manage.py makemigrations library
python manage.py migrate

2. 序列化器 (Serializers)

序列化器对于将复杂数据类型（如 Book 实例）转换为 JSON 等格式以及验证传入数据至关重要。ModelSerializer 提供了一种便捷的方式，可以自动创建具有与模型字段对应的字段的序列化器。

“`python

library/serializers.py

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
class Meta:
model = Book
fields = [‘id’, ‘title’, ‘author’, ‘publication_date’, ‘isbn’]
“`

3. 视图和视图集 (Views and ViewSets)

DRF 提供了多种定义 API 视图的方式。

  • APIView: 一个基本的基于类的视图，它提供对请求和响应处理的更多控制。
  • GenericAPIView: 扩展了 APIView 并为列表和详细视图提供通用行为，通常与 mixins 一起使用。
  • ModelViewSet: 一个强大的类，它将一组相关视图（列表、创建、检索、更新、销毁）的逻辑组合到一个类中，从而简化了模型的 CRUD 操作。

对于大多数 CRUD 操作，强烈推荐使用 ModelViewSet。

“`python

library/views.py

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

class BookViewSet(viewsets.ModelViewSet):
queryset = Book.objects.all()
serializer_class = BookSerializer
“`

BookViewSet 自动为 Book 模型提供了 list、retrieve、create、update 和 destroy 操作。

4. 路由器 (Routers)

路由器自动为视图集生成 URL 模式，无需手动为 CRUD 操作定义每个 URL。DefaultRouter 常用且创建标准的 RESTful 端点。

“`python

project_name/urls.py (your project’s main urls.py)

from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from library.views import BookViewSet

创建一个路由器并注册我们的视图集。

router = DefaultRouter()
router.register(r’books’, BookViewSet)

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(router.urls)), # 包含我们的 API URL
path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’)), # 用于可浏览 API 登录/注销
]
“`

通过将 BookViewSet 注册到路由器，DRF 会自动生成 /api/books/（用于列表和创建）和 /api/books/{id}/（用于检索、更新和删除）等 URL。

高级主题 (简要概述)

认证和权限 (Authentication and Permissions)

DRF 提供了各种认证和权限类来保护您的 API。您可以在 settings.py 中全局配置它们，或针对每个视图/视图集进行配置。

“`python

settings.py

REST_FRAMEWORK = {
‘DEFAULT_AUTHENTICATION_CLASSES’: [
‘rest_framework.authentication.SessionAuthentication’,
‘rest_framework.authentication.TokenAuthentication’,
],
‘DEFAULT_PERMISSION_CLASSES’: [
‘rest_framework.permissions.IsAuthenticatedOrReadOnly’,
]
}
“`

此示例将 SessionAuthentication 和 TokenAuthentication 设置为默认认证方法，并将 IsAuthenticatedOrReadOnly 设置为默认权限，这意味着经过认证的用户拥有完全访问权限，而未经认证的用户只能读取数据。

分页 (Pagination)

为了处理大型数据集，DRF 提供了分页功能。您可以在全局或每个视图中启用它。

“`python

settings.py

REST_FRAMEWORK = {
# … other settings
‘DEFAULT_PAGINATION_CLASS’: ‘rest_framework.pagination.PageNumberPagination’,
‘PAGE_SIZE’: 10
}
“`

此配置将对结果进行分页，默认每页显示 10 个项目。

结论

Django REST Framework 提供了一种强大而高效的方式来使用 Django 构建 Web API。通过利用其序列化器、通用视图、视图集和路由器，您可以快速开发功能强大且易于维护的 API。可浏览 API 进一步增强了开发体验，使其易于与您的端点进行交互和测试。

滚动至顶部