如何利用 Django REST Framework 快速构建现代API？

2025-3-1

利用 Django REST Framework 快速构建现代 API

在当今的 Web 开发领域，API (应用程序编程接口) 扮演着至关重要的角色。它们是不同软件系统之间进行通信和数据交换的桥梁，驱动着各种应用，从移动应用到单页应用 (SPA) 乃至物联网 (IoT) 设备。随着前后端分离架构的兴起，构建高效、可靠且易于维护的 API 变得尤为重要。

Django REST Framework (DRF) 是一个强大而灵活的工具包，用于在 Django 框架之上构建 Web API。它以其简洁性、可扩展性和丰富的功能集而闻名，使开发者能够快速构建出符合 RESTful 原则的现代 API。本文将深入探讨如何利用 DRF 的各项特性，从零开始构建一个功能完备的 API。

1. 为什么选择 Django REST Framework？

在深入探讨具体步骤之前，让我们先了解一下为什么 DRF 如此受欢迎，以及它相对于其他 API 构建方式的优势：

  • 基于 Django: DRF 构建于 Django 之上，这意味着你可以利用 Django 强大的 ORM (对象关系映射)、模板引擎、表单处理等功能。如果你已经熟悉 Django，那么学习 DRF 将会非常容易。
  • RESTful 原则: DRF 鼓励并强制执行 RESTful API 设计原则，这有助于创建结构良好、易于理解和使用的 API。
  • 序列化: DRF 提供了强大的序列化功能，可以将复杂的 Django 模型数据转换为 JSON、XML 或其他格式，反之亦然。
  • 视图集和路由器: DRF 的视图集 (ViewSets) 和路由器 (Routers) 极大地简化了 API 视图的编写和 URL 配置，减少了重复代码。
  • 认证和权限: DRF 内置了多种认证和权限机制，包括基本认证、令牌认证、OAuth2 等，可以轻松实现 API 的安全控制。
  • 可浏览 API: DRF 提供了一个交互式的 Web 界面，可以自动生成 API 文档，并允许开发者直接在浏览器中测试 API 端点。
  • 强大的社区和生态系统: DRF 拥有一个活跃的社区和丰富的第三方扩展，可以满足各种需求。
  • 丰富的文档 官方文档非常详尽，几乎你能遇到的所有问题，都能在官方文档里找到答案

2. 环境搭建与项目初始化

在开始构建 API 之前，我们需要先搭建好开发环境并初始化 Django 项目。

2.1 安装 Python 和 Django

首先，确保你的系统上安装了 Python (建议使用 Python 3.8 或更高版本)。然后，使用 pip 安装 Django 和 DRF：

bash
pip install django djangorestframework

2.2 创建 Django 项目

使用 django-admin 命令创建一个新的 Django 项目：

bash
django-admin startproject myproject
cd myproject

2.3 创建 Django 应用

在 Django 项目中，通常会将不同的功能模块划分为不同的应用。让我们创建一个名为 api 的应用：

bash
python manage.py startapp api

2.4 配置项目

在 myproject/settings.py 文件中，将 rest_framework 和 api 应用添加到 INSTALLED_APPS 列表中：

python
INSTALLED_APPS = [
# ... 其他应用
'rest_framework',
'api',
]

3. 定义数据模型 (Models)

假设我们要构建一个简单的博客 API，需要存储文章 (Article) 和作者 (Author) 的信息。在 api/models.py 文件中定义模型：

```python
from django.db import models

class Author(models.Model):
name = models.CharField(max_length=100)
bio = models.TextField()

def __str__(self):
    return self.name

class Article(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
author = models.ForeignKey(Author, on_delete=models.CASCADE)
publication_date = models.DateField()

def __str__(self):
    return self.title

```

3.1. 数据迁移

模型定义好后，需要执行以下命令来进行数据的迁移：

bash
python manage.py makemigrations
python manage.py migrate

4. 创建序列化器 (Serializers)

序列化器是 DRF 的核心组件之一，负责将 Django 模型实例转换为 JSON 等格式，以及将接收到的数据反序列化为模型实例。在 api/serializers.py 文件中创建序列化器：

```python
from rest_framework import serializers
from .models import Author, Article

class AuthorSerializer(serializers.ModelSerializer):
class Meta:
model = Author
fields = 'all' # 或者指定需要的字段：['id', 'name', 'bio']

class ArticleSerializer(serializers.ModelSerializer):
author = AuthorSerializer(read_only=True) # 嵌套序列化器，只读
author_id = serializers.PrimaryKeyRelatedField(queryset=Author.objects.all(), write_only=True, source='author') #可写

class Meta:
    model = Article
    fields = ['id', 'title', 'content', 'author', 'publication_date', 'author_id']

```
这里有几个关键点：

  • ModelSerializer: 这是一个方便的基类，可以自动根据模型字段创建序列化器字段。
  • fields: 指定要包含在序列化输出中的字段。'__all__' 表示包含所有字段。
  • 嵌套序列化器: author = AuthorSerializer(read_only=True) 表示在文章序列化输出中包含作者的详细信息，但它是只读的。
  • PrimaryKeyRelatedField: author_id 字段允许我们在创建或更新文章时，通过作者 ID 来指定作者，而不是传递整个作者对象。 source='author' 属性将 author_id 字段映射到模型的 author 字段。

5. 构建视图 (Views)

DRF 提供了多种视图类来处理不同的 API 请求。视图集 (ViewSets) 是一个特别强大的功能，它将一组相关的视图逻辑 (如列表、创建、检索、更新、删除) 组合到一个类中。在 api/views.py 文件中创建视图集：

```python
from rest_framework import viewsets
from .models import Author, Article
from .serializers import AuthorSerializer, ArticleSerializer

class AuthorViewSet(viewsets.ModelViewSet):
queryset = Author.objects.all()
serializer_class = AuthorSerializer

class ArticleViewSet(viewsets.ModelViewSet):
queryset = Article.objects.all()
serializer_class = ArticleSerializer
```

ModelViewSet 自动为我们提供了以下 API 操作：

  • list: 获取所有作者/文章列表
  • create: 创建一个新的作者/文章
  • retrieve: 获取单个作者/文章的详细信息
  • update: 更新一个作者/文章
  • partial_update: 部分更新一个作者/文章
  • destroy: 删除一个作者/文章

6. 配置 URL 路由 (Routers)

DRF 的路由器 (Routers) 可以自动为视图集生成 URL 配置。在 api/urls.py 文件中创建路由器并注册视图集：

```python
from rest_framework import routers
from .views import AuthorViewSet, ArticleViewSet

router = routers.DefaultRouter()
router.register(r'authors', AuthorViewSet)
router.register(r'articles', ArticleViewSet)

urlpatterns = router.urls
```

然后，在项目的根 URL 配置 myproject/urls.py 中包含 api 应用的 URL：

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

urlpatterns = [
path('admin/', admin.site.urls),
path('api/', include('api.urls')),
]
```

7. 运行开发服务器并测试 API

现在，我们可以运行 Django 开发服务器来测试 API：

bash
python manage.py runserver

在浏览器中访问以下 URL：

  • http://127.0.0.1:8000/api/authors/: 获取所有作者列表
  • http://127.0.0.1:8000/api/articles/: 获取所有文章列表
  • http://127.0.0.1:8000/api/articles/1/: 获取 ID 为 1 的文章的详细信息

你会看到 DRF 提供的可浏览 API 界面，它允许你查看 API 文档、发送请求并查看响应。你也可以使用 Postman 或 curl 等工具来测试 API。

8. 认证和权限

为了保护 API，我们需要实现认证和权限控制。DRF 提供了多种内置的认证和权限类。

8.1 认证 (Authentication)

在 myproject/settings.py 中配置默认的认证类：

python
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.SessionAuthentication',
'rest_framework.authentication.TokenAuthentication',
],
# ... 其他配置
}

这里我们启用了会话认证 (SessionAuthentication) 和令牌认证 (TokenAuthentication)。会话认证适用于 Web 浏览器访问 API 的情况，而令牌认证适用于其他客户端 (如移动应用)。

要使用令牌认证，需要在 INSTALLED_APPS 中添加 'rest_framework.authtoken'，并运行数据库迁移：

bash
python manage.py migrate

8.2 权限 (Permissions)

在 myproject/settings.py 中配置默认的权限类：

python
REST_FRAMEWORK = {
# ... 其他配置
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticated',
],
}

IsAuthenticated 权限类要求用户必须通过认证才能访问 API。

你也可以在视图集级别设置权限：

```python
from rest_framework.permissions import IsAdminUser

class ArticleViewSet(viewsets.ModelViewSet):
# ... 其他配置
permission_classes = [IsAdminUser] # 只有管理员用户才能访问文章 API
```

DRF 还提供了其他权限类，如 AllowAny (允许任何用户访问)、IsAuthenticatedOrReadOnly (已认证用户可写，未认证用户只读) 等。

9. 分页 (Pagination)

当 API 返回大量数据时，分页是必不可少的。DRF 提供了多种分页样式。

在 myproject/settings.py 中配置默认的分页类：

python
REST_FRAMEWORK = {
# ... 其他配置
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10, # 每页显示 10 条数据
}

现在，当你访问列表 API 时 (如 /api/articles/)，DRF 会自动对结果进行分页，并在响应中包含分页信息 (如总页数、当前页码、上一页和下一页的 URL)。

10. 过滤 (Filtering)

DRF 允许你根据查询参数对 API 结果进行过滤。

首先，安装 django-filter：

bash
pip install django-filter

在 myproject/settings.py 中添加 'django_filters' 到 INSTALLED_APPS，并配置默认的过滤后端：

python
REST_FRAMEWORK = {
# ... 其他配置
'DEFAULT_FILTER_BACKENDS': [
'django_filters.rest_framework.DjangoFilterBackend'
],
}

在视图集中指定 filterset_fields：

```python
from django_filters.rest_framework import DjangoFilterBackend

class ArticleViewSet(viewsets.ModelViewSet):
# ... 其他配置
filter_backends = [DjangoFilterBackend]
filterset_fields = ['author', 'publication_date'] # 允许按作者和发布日期过滤
```

现在，你可以通过查询参数来过滤文章列表，例如：

  • /api/articles/?author=1: 获取作者 ID 为 1 的所有文章
  • /api/articles/?publication_date=2023-10-26: 获取发布日期为 2023-10-26 的所有文章

11. 搜索 (Searching)

DRF 内置了搜索功能，可以让你根据关键词搜索 API 结果。

在视图集中添加 SearchFilter：

```python
from rest_framework.filters import SearchFilter

class ArticleViewSet(viewsets.ModelViewSet):
# ... 其他配置
filter_backends = [DjangoFilterBackend, SearchFilter]
search_fields = ['title', 'content'] # 允许按标题和内容搜索
```

现在，你可以通过 search 查询参数来搜索文章，例如：

  • /api/articles/?search=Django: 搜索标题或内容中包含 "Django" 的文章

12. 限流 (Throttling)

为了防止 API 被滥用，我们可以使用 DRF 的限流功能来限制 API 请求的频率。

在 myproject/settings.py 中配置默认的限流策略：

python
REST_FRAMEWORK = {
# ... 其他配置
'DEFAULT_THROTTLE_CLASSES': [
'rest_framework.throttling.AnonRateThrottle', # 匿名用户限流
'rest_framework.throttling.UserRateThrottle', # 认证用户限流
],
'DEFAULT_THROTTLE_RATES': {
'anon': '100/day', # 匿名用户每天最多 100 次请求
'user': '1000/day', # 认证用户每天最多 1000 次请求
},
}

你也可以在视图集级别设置限流策略：

```python
class ArticleViewSet(viewsets.ModelViewSet):
# ... 其他配置
throttle_classes = [UserRateThrottle]
throttle_scope = 'articles' # 使用名为 "articles" 的限流范围

在 settings.py 中定义 "articles" 范围的限流速率

REST_FRAMEWORK = {
# ... 其他配置
'DEFAULT_THROTTLE_RATES': {
'articles': '500/day', # "articles" 范围每天最多 500 次请求
},
}
```

13. 版本控制 (Versioning)

随着 API 的发展，可能需要引入新的功能或更改现有功能，而又不影响现有的客户端。DRF 提供了多种 API 版本控制方案。

一种常见的做法是在 URL 中包含版本号。在 myproject/urls.py 中配置 URL：

```python
from django.urls import path, include

urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('api.urls')), # v1 版本的 API
# path('api/v2/', include('api_v2.urls')), # v2 版本的 API (如果需要)
]
```

你可以在不同的应用 (api_v1、api_v2 等) 中定义不同版本的 API。

展望未来：超越基础

本文介绍了使用 Django REST Framework 构建现代 API 的基本步骤和常用功能。但是，DRF 的功能远不止于此。以下是一些你可以进一步探索的高级主题：

  • 自定义序列化器字段: 创建自定义的序列化器字段来处理特殊的数据类型或逻辑。
  • 自定义视图: 使用 DRF 的通用视图类 (如 ListAPIView、CreateAPIView 等) 或自定义视图类来处理更复杂的 API 逻辑。
  • 自定义认证和权限: 实现自定义的认证和权限类来满足特定的安全需求。
  • OpenAPI (Swagger) 集成: 使用 drf-yasg 或 drf-spectacular 等库自动生成符合 OpenAPI 规范的 API 文档。
  • GraphQL 集成: 使用 Graphene-Django 等库将 DRF 与 GraphQL 集成。
  • 异步视图: 使用 Django 的异步视图 (ASGI) 来提高 API 的性能和可伸缩性。
  • 测试: 编写单元测试和集成测试来确保 API 的质量和可靠性。
    • 使用pytest和pytest-django能够很方便进行测试
  • 部署: 将 API 部署到生产环境，如使用 Gunicorn 和 Nginx 部署到服务器，或使用 Docker 和 Kubernetes 进行容器化部署。

Django REST Framework 是一个功能强大、灵活且易于使用的工具包，可以帮助你快速构建出高质量的现代 API。通过掌握本文介绍的基础知识，并不断探索 DRF 的高级功能，你将能够构建出满足各种需求的 API，为你的应用程序提供强大的支持。

版权声明：
作者：admin
链接：https://hostlocvps.com/2025/03/01/%e5%a6%82%e4%bd%95%e5%88%a9%e7%94%a8-django-rest-framework-%e5%bf%ab%e9%80%9f%e6%9e%84%e5%bb%ba%e7%8e%b0%e4%bb%a3api%ef%bc%9f/
文章版权归作者所有，未经允许请勿转载。
THE END
全面解析Ruby on Rails框架功能与优势
<<上一篇
深入了解Manjaro：它与其他Linux发行版有何不同？
下一篇>>
相关推荐
Oracle JDK安装指南：从下载到配置完整教程
TypeScript核心概念与开发指南
最强视频播放工具：VLC for Android体验报告
Python实现文件下载的核心代码解析
如何利用GitHub提升Swift编程效率
TikTok视频保存指南：如何快速获取心仪视频
新手友好型教程：如何实现直接输出结果 每一知识点单独成行解析
TensorFlow GitHub开发指南：从零开始构建AI模型
TensorFlow GitHub官方仓库全解读：开发者必看指南
pgvector介绍：PostgreSQL中的向量数据库解决方案