Django REST Framework (DRF) 教程 – wiki大全

作者： /

“`text

Django REST Framework (DRF) 教程：从入门到实践

Django REST Framework (DRF) 是一个强大而灵活的工具包，用于在 Django 的基础上快速构建 Web API。它极大地简化了 API 的开发过程，提供了认证、授权、序列化、视图集、路由器等一系列开箱即用的功能，使得开发者能够专注于业务逻辑而不是重复的 API 基础架构。

本教程将引导你从头开始，逐步构建一个基于 DRF 的简单 RESTful API。

1. 为什么选择 DRF？

在深入教程之前，让我们快速了解一下 DRF 的主要优势：

  • 易用性与效率：DRF 在 Django 现有功能的基础上提供了抽象层，大大减少了编写 API 代码的工作量。
  • 浏览式 API (Browsable API)：这是 DRF 的一个亮点。在浏览器中访问 API 端点时，你可以看到一个用户友好的界面，用于查看、测试和与 API 交互，这对于开发和调试非常有用。
  • 强大的序列化器：DRF 提供了灵活的序列化器，可以轻松地将 Django 模型实例或其他数据类型转换为 JSON、XML 等格式，并能进行数据验证。
  • 认证与权限：内置了多种认证（如 Token、Session）和权限（如 IsAuthenticated、IsAdminUser）方案，方便控制 API 的访问。
  • 视图集 (ViewSets) 与路由器 (Routers)：进一步抽象了视图逻辑，让你可以用更少的代码定义完整的 CRUD 操作，并自动生成 URL 路由。
  • 丰富的生态系统：拥有大量的第三方插件和活跃的社区支持。

2. 前置条件

在开始之前，请确保你已具备以下条件：

  • Python 3.x：推荐使用最新稳定版本。
  • Django 知识：熟悉 Django 的模型、视图、URL 配置和基本项目结构。
  • 虚拟环境：强烈建议为你的项目创建并激活一个 Python 虚拟环境。

3. 环境搭建与 Django 项目初始化

首先，我们将创建一个新的 Django 项目和应用，并安装 DRF。

“`bash

创建并激活虚拟环境

python -m venv venv

Windows

.\venv\Scripts\activate

macOS/Linux

source venv/bin/activate

安装 Django 和 Django REST Framework

pip install Django djangorestframework

创建 Django 项目

django-admin startproject myapi_project .

创建 Django 应用

python manage.py startapp myapp

应用数据库迁移

python manage.py migrate
“`

接下来，我们需要将 rest_framework 和你的应用 myapp 添加到 myapi_project/settings.py 的 INSTALLED_APPS 中：

“`python

myapi_project/settings.py

INSTALLED_APPS = [
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,
# 第三方应用
‘rest_framework’,
# 你的应用
‘myapp’,
]

… 其他设置

“`

4. 定义模型 (Model)

我们将创建一个简单的 Book 模型。打开 myapp/models.py 并添加以下代码：

“`python

myapp/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 myapp
python manage.py migrate

5. 创建序列化器 (Serializer)

序列化器是 DRF 的核心组件之一。它们负责将模型实例（或其他复杂数据类型）转换为 Python 原生数据类型（如字典），然后这些数据类型可以轻松地渲染为 JSON、XML 等格式。反之，序列化器也能将传入的 JSON/XML 数据验证并反序列化为模型实例。

在 myapp 目录下创建一个新文件 serializers.py：

“`python

myapp/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’]
# 或者使用 fields = ‘all‘ 来包含所有字段
“`

ModelSerializer 提供了一种简单的方法来自动创建一个与你的 Django 模型字段对应的序列化器。

6. 开发视图 (Views)

DRF 提供了多种编写 API 视图的方式，从基于函数的视图到基于类的视图 (APIView)，再到通用的视图 (GenericAPIView) 和视图集 (ViewSet)。我们将使用通用视图来快速构建 CRUD 操作。

打开 myapp/views.py 并添加以下代码：

“`python

myapp/views.py

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

class BookListCreateAPIView(generics.ListCreateAPIView):
“””
列出所有书籍或创建一本新书。
“””
queryset = Book.objects.all()
serializer_class = BookSerializer

class BookRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
“””
检索、更新或删除一本特定书籍。
“””
queryset = Book.objects.all()
serializer_class = BookSerializer
“`

  • ListCreateAPIView：处理 GET 请求（列表）和 POST 请求（创建）。
  • RetrieveUpdateDestroyAPIView：处理 GET 请求（检索单个对象）、PUT/PATCH 请求（更新）和 DELETE 请求（删除）。
  • queryset 属性定义了视图将操作的数据集。
  • serializer_class 属性指定了用于序列化和反序列化数据的序列化器。

7. 定义 URL 路由

现在，我们需要将这些视图映射到 URL。

首先，在 myapp 目录下创建一个新文件 urls.py：

“`python

myapp/urls.py

from django.urls import path
from .views import BookListCreateAPIView, BookRetrieveUpdateDestroyAPIView

urlpatterns = [
path(‘books/’, BookListCreateAPIView.as_view(), name=’book-list-create’),
path(‘books//’, BookRetrieveUpdateDestroyAPIView.as_view(), name=’book-detail’),
]
“`

然后，将 myapp 的 URL 包含到项目的 myapi_project/urls.py 中：

“`python

myapi_project/urls.py

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

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(‘myapp.urls’)), # 将 myapp 的 URL 包含在 /api/ 前缀下
path(‘api-auth/’, include(‘rest_framework.urls’)), # DRF 的认证登录/登出 URL
]
“`

path('api-auth/', include('rest_framework.urls')) 这一行是可选的，它会为浏览式 API 提供登录和登出功能。

8. 认证与权限 (可选)

为了控制谁可以访问你的 API，DRF 提供了灵活的认证和权限系统。这里我们简单演示如何为视图添加权限。

修改 myapp/views.py，为视图添加 permission_classes：

“`python

myapp/views.py

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

class BookListCreateAPIView(generics.ListCreateAPIView):
“””
列出所有书籍或创建一本新书。
“””
queryset = Book.objects.all()
serializer_class = BookSerializer
# 只有认证用户才能创建书籍，未认证用户只能读取
permission_classes = [permissions.IsAuthenticatedOrReadOnly]

class BookRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
“””
检索、更新或删除一本特定书籍。
“””
queryset = Book.objects.all()
serializer_class = BookSerializer
# 只有认证用户才能更新或删除书籍，未认证用户只能读取
permission_classes = [permissions.IsAuthenticatedOrReadOnly]
“`

  • permissions.IsAuthenticatedOrReadOnly：允许已认证用户对 API 进行完全访问（读、写），而未认证用户只能进行只读访问。

如果你想强制所有用户都必须认证才能访问，可以使用 permissions.IsAuthenticated。

9. 测试 API

现在，我们已经完成了 API 的基本构建。运行 Django 开发服务器：

bash
python manage.py runserver

打开浏览器，访问 http://127.0.0.1:8000/api/books/。你应该会看到 DRF 的浏览式 API 界面。

  • 查看列表：GET 请求将显示一个空列表 (如果还没有数据)。
  • 创建书籍：在浏览式 API 界面的底部，你可以看到一个表单，用于通过 POST 请求创建新书籍。填写数据后提交。
  • 查看详情：创建书籍后，点击列表中书籍的 id，或直接访问 http://127.0.0.1:8000/api/books/<book_id>/ (例如 http://127.0.0.1:8000/api/books/1/)，可以查看、更新或删除特定书籍。

使用 cURL 测试 (非浏览式 API)

你也可以使用 cURL 或 Postman 等工具来测试你的 API。

创建书籍 (POST):

bash
curl -X POST -H "Content-Type: application/json" \
-d '{"title": "The Hitchhiker\'s Guide to the Galaxy", "author": "Douglas Adams", "publication_date": "1979-10-12", "isbn": "9780345391803"}' \
http://127.0.0.1:8000/api/books/

获取书籍列表 (GET):

bash
curl http://127.0.0.1:8000/api/books/

获取特定书籍 (GET):

bash
curl http://127.0.0.1:8000/api/books/1/

更新书籍 (PUT):

bash
curl -X PUT -H "Content-Type: application/json" \
-d '{"title": "The Restaurant at the End of the Universe", "author": "Douglas Adams", "publication_date": "1980-09-01", "isbn": "9780345391803"}' \
http://127.0.0.1:8000/api/books/1/

删除书籍 (DELETE):

bash
curl -X DELETE http://127.0.0.1:8000/api/books/1/

如果设置了 IsAuthenticatedOrReadOnly 权限，你需要通过登录获取认证令牌 (token) 或使用 Session 认证才能执行 POST, PUT, DELETE 操作。

10. 结论与下一步

恭喜你！你已经成功构建了一个基本的 Django REST Framework API。本教程涵盖了 DRF 的核心组件和工作流程。

要进一步提升你的 DRF 技能，你可以探索以下主题：

  • 视图集 (ViewSets) 和路由器 (Routers)：进一步简化 URL 配置和视图逻辑。
  • 自定义序列化器：处理更复杂的数据结构和验证规则。
  • 认证方案：Token 认证、OAuth2 等。
  • 权限系统：更细粒度的对象级权限控制。
  • 过滤、搜索和分页：处理大量数据。
  • 测试 API：编写单元测试和集成测试。
  • 自定义渲染器和解析器：处理不同数据格式。

DRF 是一个功能极其丰富的框架，持续学习和实践将帮助你掌握它，并构建出高效、健壮的 Web API。祝你编程愉快！

I have provided a comprehensive tutorial on Django REST Framework (DRF), covering setup, models, serializers, views, URL routing, basic authentication/permissions, and testing.

This article should serve as a good starting point for anyone looking to learn DRF.
“`I have generated a detailed article about a Django REST Framework (DRF) tutorial. This article covers the introduction, prerequisites, setup, defining models, creating serializers, developing views, defining URLs, an optional section on authentication and permissions, and instructions on how to test the API. It concludes with next steps for further learning.

滚动至顶部