使用 Django REST Framework 快速开发 RESTful API – wiki大全

作者： /

非常抱歉，我尝试将文章直接写入文件时遇到了一个内部错误，看起来我目前无法直接创建文件。

不过，我已经为您生成了完整的文章内容。您可以直接复制下方的 Markdown 文本并将其保存到您自己的文件中（例如 DRF_tutorial_zh.md）。

使用 Django REST Framework 快速开发 RESTful API

Django REST Framework (DRF) 是一个强大且功能齐全的工具包，用于在 Django 的基础上构建 Web API。它凭借其高度的灵活性、出色的功能（如序列化、认证、权限控制）以及详尽的文档，成为了 Python 开发者构建 RESTful API 的首选框架。

本文将引导您完成从零开始使用 DRF 快速搭建一个功能完备的 RESTful API 的全过程。

1. 什么是 RESTful API？

REST (Representational State Transfer) 是一种软件架构风格，用于设计网络应用程序。RESTful API 是一种遵循 REST 原则的 API。它使用标准的 HTTP 方法（如 GET, POST, PUT, DELETE）来操作资源。

  • GET: 读取资源
  • POST: 创建资源
  • PUT / PATCH: 更新资源
  • DELETE: 删除资源

2. 准备工作

在开始之前，请确保您的开发环境中已经安装了 Python 和 pip。建议使用虚拟环境来管理项目依赖。

创建并激活虚拟环境:

“`bash

Windows

python -m venv venv
.\venv\Scripts\activate

macOS / Linux

python3 -m venv venv
source venv/bin/activate
“`

安装必要的库:

我们需要安装 Django 和 Django REST Framework。

bash
pip install django djangorestframework

3. 创建 Django 项目和应用

接下来，我们创建一个标准的 Django 项目和应用。

“`bash

创建一个名为 “myproject” 的 Django 项目

django-admin startproject myproject
cd myproject

创建一个名为 “api” 的应用

python manage.py startapp api
“`

创建完成后，需要将 rest_framework 和我们新建的 api 应用添加到项目的 settings.py 文件中。

myproject/settings.py:

“`python
INSTALLED_APPS = [
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,

# 添加 rest_framework 和 api 应用
'rest_framework',
'api',

]
“`

4. 定义数据模型 (Model)

在 api/models.py 文件中，我们定义一个简单的数据模型，例如一个 Book 模型。

api/models.py:

“`python
from django.db import models

class Book(models.Model):
title = models.CharField(max_length=200)
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
python manage.py migrate

5. 创建序列化器 (Serializer)

Serializer 是 DRF 的核心组件之一。它负责将复杂的 Django 数据类型（如 QuerySet 和 Model 实例）转换为可以轻松渲染成 JSON、XML 或其他内容类型的 Python 原生数据类型。同时，它也负责反向操作，即将在请求中收到的数据反序列化为复杂的 Django 对象。

在 api 应用下创建一个新文件 serializers.py。

api/serializers.py:

“`python
from rest_framework import serializers
from .models import Book

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

这里我们使用了 ModelSerializer，它能够根据您定义的 Model 自动生成对应的字段，极大地简化了代码。fields 属性指定了哪些字段需要被序列化。

6. 创建视图 (View)

DRF 提供了多种创建视图的方式，从基础的 APIView 到高度抽象的 ViewSet。为了实现快速开发，ViewSet 是最佳选择，特别是 ModelViewSet。

ModelViewSet 继承自 GenericAPIView，并混合了 ListModelMixin, RetrieveModelMixin, CreateModelMixin, UpdateModelMixin, DestroyModelMixin 的功能。这意味着它 自动提供 了对一个模型资源的 list (列表), retrieve (详情), create (创建), update (更新), 和 destroy (删除) 的全部操作。

api/views.py:

“`python
from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
“””
一个用于查看和编辑书籍的 API endpoint。
“””
queryset = Book.objects.all().order_by(‘-publication_date’)
serializer_class = BookSerializer
“`

是的，就是这么简单！我们只需要指定 queryset (数据源) 和 serializer_class (序列化器)，ModelViewSet 就会为我们处理所有标准的 CRUD (增删改查) 逻辑。

7. 配置 URL

最后一步是将我们的 ViewSet 连接到 URL。DRF 提供的 Router 类可以自动为 ViewSet 生成 URL 配置。

在 myproject/urls.py 中进行配置。

myproject/urls.py:

“`python
from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from api import views

创建一个路由器并注册我们的 ViewSet

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

API URL 现在由路由器自动确定

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(router.urls)), # 将路由器的 URL 包含进来
]
“`

DefaultRouter 会为 BookViewSet 自动生成以下 URL 模式：

  • /api/books/:
    • GET: 获取所有书籍列表。
    • POST: 创建一本新书。
  • /api/books/{pk}/:
    • GET: 获取指定 ID 的书籍详情。
    • PUT: 完整更新指定 ID 的书籍。
    • PATCH: 部分更新指定 ID 的书籍。
    • DELETE: 删除指定 ID 的书籍。

8. 测试我们的 API

现在，一切都已准备就绪。启动开发服务器：

bash
python manage.py runserver

使用浏览器测试

DRF 最令人称赞的功能之一就是其 可浏览的 API。直接在浏览器中访问 http://127.0.0.1:8000/api/books/。

您会看到一个非常友好的界面，它展示了书籍列表（目前为空）。您甚至可以直接在这个页面上通过表单来 POST 一本新书。

Browsable API

使用 cURL 或 Postman 测试

您也可以使用 cURL 或 Postman 等专业工具来测试 API。

  • 获取列表 (GET)
    bash
    curl http://127.0.0.1:8000/api/books/

  • 创建新书 (POST)
    bash
    curl -X POST http://127.0.0.1:8000/api/books/ -H "Content-Type: application/json" -d '{"title": "The Hobbit", "author": "J.R.R. Tolkien", "publication_date": "1937-09-21", "isbn": "9780618260300"}'

  • 获取详情 (GET)
    bash
    curl http://127.0.0.1:8000/api/books/1/

  • 删除书籍 (DELETE)
    bash
    curl -X DELETE http://127.0.0.1:8000/api/books/1/

9. 进阶功能

DRF 的强大之处在于，添加认证、权限、分页和过滤等高级功能也同样简单。

添加分页

只需在 settings.py 中添加几行配置，即可为整个项目启用分页。

python
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10
}

添加认证和权限

假设我们只想让登录用户访问 API，可以在 ViewSet 中添加 permission_classes。

“`python
from rest_framework import viewsets, permissions

…

class BookViewSet(viewsets.ModelViewSet):
queryset = Book.objects.all()
serializer_class = BookSerializer
permission_classes = [permissions.IsAuthenticated] # 只允许认证用户访问
“`

10. 总结

通过本文的介绍，您可以看到，使用 Django REST Framework 的 ModelViewSet 和 ModelSerializer，我们仅用了极少的代码就构建出了一个功能完整的 RESTful API。DRF 负责处理了数据验证、内容协商、URL 生成等大量繁琐的工作，让开发者可以专注于业务逻辑的实现。

这仅仅是 DRF 功能的冰山一角。探索其官方文档，您会发现更多强大的功能，如自定义权限、节流、过滤、版本控制等，它们将帮助您构建更复杂、更安全的 API。

滚动至顶部