Django REST Framework实战：打造高效、可扩展的Web API – wiki基地

作者： /

Django REST Framework实战：打造高效、可扩展的Web API

Django REST Framework (DRF) 是一个建立在 Django 基础之上的、强大且功能齐全的工具包，用于构建 Web API。它极大地简化了 API 的开发过程，让开发者能够专注于业务逻辑，而不是重复编写样板代码。本文将从零开始，带您深入了解 DRF，并逐步构建一个真实世界中的 API。

为什么选择 Django REST Framework？

在选择技术栈时，我们总是会问“为什么是它？”。以下是选择 DRF 的几个关键理由：

  • 高效率开发: DRF 提供了序列化器（Serializers）、视图集（ViewSets）和路由器（Routers）等高级抽象，能够自动处理数据验证、URL 构建等繁琐工作，从而显著提升开发速度。
  • 强大的功能: 内置了认证、权限、限流、分页和过滤等一系列开箱即用的功能，满足了绝大多数 API 开发场景的需求。
  • 高度可扩展: DRF 的设计遵循了 Django 的“松耦合”原则，所有组件都是可插拔、可定制的。您可以根据项目需求轻松替换或扩展默认实现。
  • 完善的文档与社区: DRF 拥有堪称典范的官方文档和活跃的开发者社区，无论您遇到什么问题，几乎都能找到答案。
  • 自带可浏览 API: DRF 会自动为您的 API 生成一个人类可读的 Web 界面，极大地简化了 API 的调试和测试过程。

环境搭建

在开始之前，请确保您已经安装了 Python 和 Django。

  1. 安装 Django 和 DRF:
    bash
    pip install django djangorestframework

  2. 创建 Django 项目和应用:
    bash
    django-admin startproject myproject
    cd myproject
    python manage.py startapp myapi

  3. 配置项目:
    打开 myproject/settings.py 文件，将 rest_framework 和 myapi 添加到 INSTALLED_APPS 列表中：

    python
    INSTALLED_APPS = [
    # ...
    'rest_framework',
    'myapi',
    ]

创建一个简单的 API

我们将以一个常见的“文章（Article）”模型为例，来创建一个简单的 CRUD (增删改查) API。

1. 定义模型 (Model)

在 myapi/models.py 文件中，定义 Article 模型：

“`python
from django.db import models

class Article(models.Model):
title = models.CharField(max_length=100)
content = models.TextField()
author = models.CharField(max_length=50)
created_at = models.DateTimeField(auto_now_add=True)

def __str__(self):
    return self.title

“`

然后，执行数据库迁移：

bash
python manage.py makemigrations
python manage.py migrate

2. 创建序列化器 (Serializer)

序列化器负责将复杂的模型实例（QuerySets）转换为 Python 原生数据类型，然后再渲染成 JSON、XML 或其他内容类型。在 myapi/ 目录下创建一个新文件 serializers.py：

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

class ArticleSerializer(serializers.ModelSerializer):
class Meta:
model = Article
fields = [‘id’, ‘title’, ‘content’, ‘author’, ‘created_at’]
“`

ModelSerializer 是一个非常神奇的类，它能根据您提供的 model 自动生成序列化器字段和验证器。

3. 编写视图 (Views)

视图负责处理 HTTP 请求并返回响应。DRF 提供了多种编写视图的方式，从最底层的 APIView 到高度抽象的 generics 和 ViewSets。我们先使用基于类的通用视图 generics。

打开 myapi/views.py 文件：

“`python
from rest_framework import generics
from .models import Article
from .serializers import ArticleSerializer

class ArticleListCreateAPIView(generics.ListCreateAPIView):
“””
列出所有文章或创建一个新文章。
“””
queryset = Article.objects.all()
serializer_class = ArticleSerializer

class ArticleRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
“””
检索、更新或删除一篇文章实例。
“””
queryset = Article.objects.all()
serializer_class = ArticleSerializer
“`

  • ListCreateAPIView: 用于处理 GET (列表) 和 POST (创建) 请求。
  • RetrieveUpdateDestroyAPIView: 用于处理 GET (单个对象)、PUT/PATCH (更新) 和 DELETE (删除) 请求。

4. 配置 URL

最后一步是将我们的视图连接到 URL。在 myapi/ 目录下创建 urls.py 文件：

“`python
from django.urls import path
from .views import ArticleListCreateAPIView, ArticleRetrieveUpdateDestroyAPIView

urlpatterns = [
path(‘articles/’, ArticleListCreateAPIView.as_view(), name=’article-list-create’),
path(‘articles//’, ArticleRetrieveUpdateDestroyAPIView.as_view(), name=’article-retrieve-update-destroy’),
]
“`

然后，在主项目 myproject/urls.py 中包含 myapi 的 URL 配置：

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

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(‘myapi.urls’)), # 包含 API 的 URL
]
“`

现在，启动开发服务器 (python manage.py runserver)，访问 http://127.0.0.1:8000/api/articles/，您将看到 DRF 提供的可浏览 API 界面！您可以通过这个界面直观地进行 GET、POST 等操作。

探索高级功能

DRF 的魅力远不止于此。

认证与权限

API 的安全性至关重要。DRF 提供了多种认证方案，如 SessionAuthentication、TokenAuthentication 和 JWT 等。

您可以在 settings.py 中设置全局默认的认证和权限策略：

python
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.TokenAuthentication',
],
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticated', # 默认需要登录才能访问
]
}

也可以在单个视图上指定：

“`python
from rest_framework.permissions import IsAuthenticatedOrReadOnly

class ArticleListCreateAPIView(generics.ListCreateAPIView):
queryset = Article.objects.all()
serializer_class = ArticleSerializer
permission_classes = [IsAuthenticatedOrReadOnly] # 未登录用户只读
“`

视图集 (ViewSets) 与路由器 (Routers)

当您为同一个资源编写多个视图（列表、详情、创建等）时，会发现有很多重复代码。ViewSets 可以将一组相关的视图逻辑组合到一个类中。

重构 myapi/views.py：

“`python
from rest_framework import viewsets

class ArticleViewSet(viewsets.ModelViewSet):
“””
一个用于查看和编辑文章实例的 ViewSet。
“””
queryset = Article.objects.all()
serializer_class = ArticleSerializer
permission_classes = [IsAuthenticatedOrReadOnly]
“`

ModelViewSet 继承自 GenericViewSet 并混合了所有 CRUD 操作的 mixin 类，一个类就完成了之前两个类的所有功能。

接着，使用 Routers 自动生成 URL。修改 myapi/urls.py：

“`python
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ArticleViewSet

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

router = DefaultRouter()
router.register(r’articles’, ArticleViewSet, basename=’article’)

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

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

DRF 的路由器会自动为您生成 articles/ (列表/创建) 和 articles/<pk>/ (详情/更新/删除) 等 URL 模式，代码更加简洁、一致。

分页、过滤和搜索

  • 分页 (Pagination): 当数据量很大时，一次性返回所有数据是不明智的。DRF 提供了灵活的分页支持。在 settings.py 中配置全局分页样式：
    python
    REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10 # 每页 10 条
    }

  • 过滤 (Filtering): 允许客户端根据字段值筛选结果。安装 django-filter (pip install django-filter) 后，您可以轻松地为 ViewSet 添加过滤功能。

  • 搜索 (Searching): DRF 也内置了搜索功能，允许基于关键字进行查询。

构建可扩展 API 的最佳实践

  1. 版本化你的 API: 在 URL 中加入版本号（如 /api/v1/articles/），这使得未来的 API 升级不会影响到现有客户端。
  2. 保持序列化器的“瘦”: 序列化器应专注于数据的表示和基本验证。复杂的业务逻辑应放在视图或服务层中。
  3. 使用环境变量管理敏感信息: 永远不要将数据库密码、SECRET_KEY 等硬编码在代码中。使用 .env 文件和 python-decouple 等工具来管理它们。
  4. 编写清晰的文档: 尽管 DRF 提供了可浏览 API，但为您的 API 编写专门的文档（例如使用 drf-yasg 或 drf-spectacular 生成 OpenAPI/Swagger 文档）对于协作者和前端开发者来说至关重要。
  5. 编写单元测试和集成测试: 确保您的 API 在代码变更后依然能够按预期工作。

结语

Django REST Framework 是一个设计精良、功能强大的框架，它遵循“约定优于配置”的原则，让 API 开发变成一种享受。通过本文的学习，您已经掌握了 DRF 的核心概念和基本用法。但这仅仅是开始，DRF 的世界还有更多宝藏等待您去挖掘。现在，就开始您的下一个项目，用 DRF 打造出高效、健壮且可扩展的 Web API 吧！

滚动至顶部