Django REST Framework 入门指南 – wiki词典

作者： /

Django REST Framework 入门指南

Django REST Framework (DRF) 是一个强大而灵活的工具包，用于构建 Web API。它建立在 Django 之上，极大地简化了 RESTful API 的开发。本指南将带你从零开始，快速构建一个简单的 REST API。

1. 前言：为什么选择 Django REST Framework？

在现代 Web 开发中，API 是前后端分离、移动应用、第三方集成等场景的核心。Django 本身提供了强大的 Web 开发能力，但如果需要构建一个与 Web 界面分离的、纯粹的 RESTful API，DRF 提供了以下优势：

  • 易用性强： 提供了丰富的工具和抽象，减少了大量重复性工作。
  • 高度可定制： 从序列化到视图，几乎所有组件都可以根据需求进行定制。
  • 完善的文档和社区： 拥有活跃的社区和详尽的官方文档。
  • 浏览器可浏览 API： 提供了一个美观且功能强大的浏览器可浏览 API，方便测试和调试。
  • 认证与权限： 内置多种认证和权限机制。

2. 前置准备

在开始之前，请确保你的开发环境中已经安装了 Python 和 Django。

推荐的开发环境设置：

  1. 创建并激活虚拟环境：

    “`bash
    python -m venv venv

    Windows

    .\venv\Scripts\activate

    macOS/Linux

    source venv/bin/activate
    “`

  2. 安装 Django 和 Django REST Framework：

    bash
    pip install Django djangorestframework

3. 创建 Django 项目和应用

我们将创建一个名为 myproject 的 Django 项目和一个名为 myapp 的应用。

  1. 创建 Django 项目：

    bash
    django-admin startproject myproject .

  2. 创建 Django 应用：

    bash
    python manage.py startapp myapp

  3. 注册应用和 REST Framework：
    打开 myproject/settings.py，在 INSTALLED_APPS 中添加 rest_framework 和 myapp：

    “`python

    myproject/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. 进行数据库迁移：

    bash
    python manage.py migrate

4. 定义模型 (Model)

在 myapp/models.py 中，我们创建一个简单的 Book 模型。

“`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)

序列化器负责将复杂的模型实例（或查询集）转换为原生 Python 数据类型，以便可以轻松地将其渲染为 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’]
# 或者使用 ‘all‘ 来包含所有字段
# fields = ‘all‘
“`

ModelSerializer 是一种快捷方式，它会自动为你创建与模型对应的字段，并实现 create() 和 update() 方法。

6. 创建视图 (View)

DRF 提供了多种视图类型，最常用的是基于类的视图（Class-Based Views）和视图集（ViewSets）。我们先从视图集开始，因为它结合了常用操作（CRUD）的逻辑。

使用 ViewSets 和 Routers

ViewSets 允许你将相关的逻辑组合到一个类中，通常用于处理一个模型的所有标准操作（列表、详情、创建、更新、删除）。Routers 负责自动为 ViewSets 生成 URL 模式，省去了手动编写 urls.py 的麻烦。

打开 myapp/views.py：

“`python

myapp/views.py

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

class BookViewSet(viewsets.ModelViewSet):
“””
允许用户查看或编辑图书的 API 终结点。
“””
queryset = Book.objects.all().order_by(‘title’)
serializer_class = BookSerializer
“`

ModelViewSet 继承自 GenericViewSet 并混合了 ListModelMixin, RetrieveModelMixin, CreateModelMixin, UpdateModelMixin, DestroyModelMixin。这意味着它自动提供了创建、检索、更新、删除和列出模型实例的 API 接口。

7. 配置 URL 路由 (URL Routing)

现在我们需要将视图集与 URL 关联起来。我们将使用 DRF 的 DefaultRouter。

  1. 在 myapp 中创建 urls.py：

    “`python

    myapp/urls.py

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

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

    urlpatterns = [
    path(”, include(router.urls)),
    ]
    “`

  2. 在项目根 urls.py 中包含 myapp 的 URL：

    “`python

    myproject/urls.py

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

    urlpatterns = [
    path(‘admin/’, admin.site.urls),
    path(‘api/’, include(‘myapp.urls’)), # 添加这一行
    ]
    “`

现在，当你访问 /api/books/ 时，BookViewSet 将被用于处理请求。

8. 运行开发服务器

现在你可以启动 Django 开发服务器并测试你的 API 了：

bash
python manage.py runserver

打开浏览器，访问 http://127.0.0.1:8000/api/books/。

你将看到 DRF 提供的浏览器可浏览 API 界面。由于我们还没有添加任何图书，列表会是空的。

添加一些数据

为了测试，你可以通过 Django Admin 后台添加一些图书。
1. 创建超级用户：

```bash
python manage.py createsuperuser
```

  1. 注册 Book 模型到 Admin：
    打开 myapp/admin.py：

    “`python

    myapp/admin.py

    from django.contrib import admin
    from .models import Book

    admin.site.register(Book)
    “`

  2. 访问 Admin 后台：
    现在访问 http://127.0.0.1:8000/admin/，使用你创建的超级用户登录，然后添加几本图书。

再次访问 http://127.0.0.1:8000/api/books/，你会看到你添加的图书列表。你还可以尝试访问 http://127.0.0.1:8000/api/books/1/（如果 ID 为 1 的图书存在）来查看单个图书的详情。通过浏览器可浏览 API 界面，你还可以尝试发送 POST、PUT、PATCH、DELETE 请求来创建、更新和删除图书。

9. 认证和权限 (Authentication & Permissions)

API 的一个重要方面是控制谁可以访问什么数据。DRF 提供了灵活的认证和权限系统。

认证 (Authentication)

认证是识别请求发起者的过程。DRF 支持多种认证方案。

例如，要启用会话认证（通常用于与 Django 后台结合使用的 Web 应用）和基本认证（常用于客户端应用程序）：

“`python

myproject/settings.py

REST_FRAMEWORK = {
‘DEFAULT_AUTHENTICATION_CLASSES’: [
‘rest_framework.authentication.SessionAuthentication’,
‘rest_framework.authentication.BasicAuthentication’,
]
}
“`

权限 (Permissions)

权限是确定请求的发起者是否有权执行特定操作的过程。DRF 提供了多种权限类。

例如，我们可能希望只有登录用户才能修改图书，而匿名用户只能查看。

“`python

myapp/views.py

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

class BookViewSet(viewsets.ModelViewSet):
queryset = Book.objects.all().order_by(‘title’)
serializer_class = BookSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly] # 添加这一行
“`

IsAuthenticatedOrReadOnly 权限类允许所有经过认证的用户对对象进行完全访问（读取和写入），而未经认证的用户只能进行只读访问。

10. 总结与展望

恭喜你！你已经成功搭建了一个基于 Django REST Framework 的基本 API。这只是 DRF 功能的冰山一角。你可以继续探索：

  • 更复杂的序列化器： 处理嵌套关系、自定义字段验证。
  • 过滤、搜索、排序： 使用 django-filter 进行高级查询。
  • 分页： 处理大量数据，提高 API 响应速度。
  • 自定义视图和 ViewSet： 根据特定需求调整行为。
  • 更多认证方式： Token 认证、OAuth2 等。
  • 测试 API： 编写单元测试和集成测试来确保 API 的健壮性。

DRF 是构建强大、可扩展的 Web API 的绝佳选择。祝你在使用它的旅程中一切顺利！

滚动至顶部