Django REST Framework (DRF) 详解：功能、优势与示例 – wiki基地

作者： /

“`markdown

Django REST Framework (DRF) 详解：功能、优势与示例

Django REST Framework (DRF) 是一款强大而灵活的工具包，专门用于构建 Web API。它基于流行的 Django Web 框架，并提供了诸多强大的功能，使得创建 RESTful API 变得高效且便捷。 本文将深入探讨 DRF 的功能、优势，并通过示例代码展示其应用，帮助你全面了解并掌握这一关键技术。

1. 什么是 RESTful API？

在深入了解 DRF 之前，首先需要理解 RESTful API 的概念。REST (Representational State Transfer) 是一种软件架构风格，用于构建分布式系统，尤其适用于 Web API。RESTful API 基于以下关键原则：

  • 客户端-服务器 (Client-Server)： 客户端和服务器职责分离，客户端负责用户界面和用户体验，服务器负责数据存储和处理。
  • 无状态 (Stateless)： 服务器不保存客户端的状态。每个请求都包含服务器理解和处理所需的全部信息。
  • 可缓存 (Cacheable)： 响应可以被缓存，以提高性能。
  • 分层系统 (Layered System)： 客户端无需知道服务器的具体架构，可以与中间层进行交互。
  • 统一接口 (Uniform Interface)： 这是 REST 的核心原则，要求使用一致的接口来访问资源，包括：
    • 资源识别： 通过 URI (Uniform Resource Identifier) 唯一标识资源。
    • 资源操作： 通过标准的 HTTP 方法（GET、POST、PUT、DELETE 等）来操作资源。
    • 自描述消息 (Self-descriptive messages)： 消息包含足够的信息，让客户端能够理解如何处理响应。
    • 超媒体即应用状态引擎 (HATEOAS)： API 响应包含指向其他相关资源的链接，使客户端能够动态地发现和浏览 API。

RESTful API 强调简单、可扩展和可互操作性，因此成为构建 Web API 的主流选择。

2. Django REST Framework (DRF) 的核心功能

DRF 提供了一系列强大的功能，简化了 RESTful API 的开发过程：

  • 序列化器 (Serializers)： 序列化器是 DRF 的核心组件，用于将 Django 模型实例转换为 JSON 或 XML 等格式的数据，以便在 API 中传输。反序列化器则将 JSON 或 XML 数据转换为 Django 模型实例，方便数据存储和处理。

  • 视图 (Views)： DRF 提供了多种视图类，用于处理 API 请求和生成响应。这些视图类封装了常见的 API 逻辑，例如创建、读取、更新和删除 (CRUD) 操作。DRF 提供了以下几种主要的视图类：

    • APIView: 这是最基础的视图类，提供对请求和响应的基本处理能力。
    • GenericAPIView: 继承自 APIView，增加了通用的行为，例如分页和对象查找。
    • ListAPIView, CreateAPIView, RetrieveAPIView, UpdateAPIView, DestroyAPIView: 这些是基于 GenericAPIView 的具体视图类，分别用于处理列表、创建、检索、更新和删除操作。
    • ListCreateAPIView, RetrieveUpdateAPIView, RetrieveDestroyAPIView, RetrieveUpdateDestroyAPIView: 这些是更高级的视图类，将多个基本视图类组合在一起，提供更全面的 API 功能。
    • ViewSet: ViewSet 提供了一种将相关视图逻辑组织到单个类中的方法，减少了代码重复。 它使用 Router 来确定要执行的操作（例如 list、create、retrieve、update、destroy）。 ViewSet 可以是 ViewSet, ReadOnlyModelViewSet, 或 ModelViewSet。

  • 路由 (Routers)： 路由用于将 URL 模式映射到视图类。 DRF 提供了 SimpleRouter 和 DefaultRouter 两种路由器，可以自动生成 API 的 URL 配置。

  • 认证 (Authentication)： DRF 支持多种认证方式，例如基本认证 (Basic Authentication)、令牌认证 (Token Authentication)、会话认证 (Session Authentication) 和 OAuth 认证。 也可以自定义认证方式。

  • 权限 (Permissions)： DRF 允许你控制对 API 资源的访问权限。 提供了许多内置的权限类，例如 AllowAny (允许所有访问)、IsAuthenticated (只允许认证用户访问) 和 IsAdminUser (只允许管理员访问)。 同样，也可以自定义权限类。

  • 节流 (Throttling)： 节流用于限制 API 的请求频率，以防止滥用和保护服务器资源。DRF 提供了匿名用户和认证用户两种节流方式，也可以自定义节流策略。

  • 解析器 (Parsers)： 解析器用于将请求数据解析为 Python 对象。 DRF 默认支持 JSON 和表单数据解析，也可以自定义解析器。

  • 渲染器 (Renderers)： 渲染器用于将 API 响应转换为不同的格式，例如 JSON、XML 和 HTML。 DRF 默认支持 JSON 和 HTML 渲染，也可以自定义渲染器。

  • 版本控制 (Versioning)： DRF 允许你管理 API 的不同版本。 可以使用 URL、查询参数或自定义请求头等方式来指定 API 版本。

  • 自动 API 文档 (Automatic API documentation)： DRF 与 Schema 生成器集成，可以自动生成 API 文档。 常用的工具包括 coreapi 和 Swagger/OpenAPI。

3. DRF 的优势

使用 DRF 构建 Web API 具有以下显著优势：

  • 快速开发： DRF 提供了许多内置组件和工具，可以显著加快 API 开发速度。
  • 代码重用： DRF 的视图类和序列化器可以被重用，减少了代码重复。
  • 易于维护： DRF 的代码结构清晰，易于理解和维护。
  • 强大的功能： DRF 提供了许多高级功能，例如认证、权限、节流和版本控制。
  • 灵活可扩展： DRF 允许你自定义组件，以满足特定的需求。
  • 良好的社区支持： DRF 拥有庞大的社区，可以提供丰富的文档和支持。
  • 兼容性： DRF 完美兼容 Django，可以与现有的 Django 项目集成。
  • 可测试性： DRF 提供了方便的测试工具，可以编写单元测试和集成测试来验证 API 的功能。

4. DRF 示例：构建一个简单的博客 API

为了更好地理解 DRF 的应用，我们将创建一个简单的博客 API，包括以下功能：

  • 列出所有博客文章
  • 创建新的博客文章
  • 获取指定 ID 的博客文章
  • 更新指定 ID 的博客文章
  • 删除指定 ID 的博客文章

4.1. 安装 DRF

首先，需要安装 DRF：

bash
pip install djangorestframework

4.2. 创建 Django 项目和应用

创建一个 Django 项目和名为 blog 的应用：

bash
django-admin startproject myblog
cd myblog
python manage.py startapp blog

4.3. 配置 settings.py

在 myblog/settings.py 文件中，添加 rest_framework 到 INSTALLED_APPS：

python
INSTALLED_APPS = [
...
'rest_framework',
'blog',
]

4.4. 定义模型

在 blog/models.py 文件中，定义 Post 模型：

“`python
from django.db import models

class Post(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)

def __str__(self):
    return self.title

“`

运行迁移命令：

bash
python manage.py makemigrations
python manage.py migrate

4.5. 创建序列化器

在 blog/serializers.py 文件中，创建 PostSerializer：

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

class PostSerializer(serializers.ModelSerializer):
class Meta:
model = Post
fields = ‘all‘ # 或者明确指定字段: [‘id’, ‘title’, ‘content’, ‘created_at’, ‘updated_at’]
# read_only_fields = [‘created_at’, ‘updated_at’] #可选：设置只读字段
“`

4.6. 创建视图

在 blog/views.py 文件中，创建视图类：

“`python
from rest_framework import generics
from .models import Post
from .serializers import PostSerializer
from rest_framework import permissions

class PostList(generics.ListCreateAPIView):
queryset = Post.objects.all()
serializer_class = PostSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly] # 添加权限控制

class PostDetail(generics.RetrieveUpdateDestroyAPIView):
queryset = Post.objects.all()
serializer_class = PostSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly] # 添加权限控制
“`

或者，使用 ViewSet:

“`python
from rest_framework import viewsets
from .models import Post
from .serializers import PostSerializer
from rest_framework import permissions

class PostViewSet(viewsets.ModelViewSet):
queryset = Post.objects.all()
serializer_class = PostSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly]
“`

4.7. 配置 URL

在 blog/urls.py 文件中，配置 URL 模式：

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

使用ViewSet时

router = DefaultRouter()
router.register(r’posts’, views.PostViewSet, basename=’post’) # basename是可选的，但建议指定，尤其是当queryset未指定时

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

不使用ViewSet时

urlpatterns = [

path(‘posts/’, views.PostList.as_view()),

path(‘posts//’, views.PostDetail.as_view()),

]

“`

在 myblog/urls.py 文件中，包含 blog 应用的 URL：

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

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(‘blog.urls’)), # 将 API 路由放在 /api/ 下
path(‘api-auth/’, include(‘rest_framework.urls’)), # 添加 DRF 的登录/注销路由 (可选)
]
“`

4.8. 测试 API

启动 Django 开发服务器：

bash
python manage.py runserver

现在可以使用 curl 命令或 Postman 等工具测试 API：

  • 列出所有博客文章：

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

  • 创建新的博客文章：

    bash
    curl -X POST -H "Content-Type: application/json" -d '{"title": "My First Post", "content": "This is the content of my first post."}' http://127.0.0.1:8000/api/posts/

  • 获取指定 ID 的博客文章：

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

  • 更新指定 ID 的博客文章：

    bash
    curl -X PUT -H "Content-Type: application/json" -d '{"title": "Updated Post", "content": "This is the updated content."}' http://127.0.0.1:8000/api/posts/1/

  • 删除指定 ID 的博客文章：

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

4.9. 认证与权限

上述示例使用了 IsAuthenticatedOrReadOnly 权限类，这意味着：

  • 未认证的用户可以读取 (GET) 博客文章列表和单个博客文章。
  • 只有认证用户才能创建 (POST)，更新 (PUT, PATCH) 或删除 (DELETE) 博客文章。

要启用认证，需要配置认证方式。 最常见的方式是使用 Token Authentication。

  1. 添加 TokenAuthentication 到 REST_FRAMEWORK 设置:

    在 settings.py 中：

    python
    REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
    'rest_framework.authentication.TokenAuthentication',
    'rest_framework.authentication.SessionAuthentication', # 可选：保留会话认证
    ],
    'DEFAULT_PERMISSION_CLASSES': [
    'rest_framework.permissions.IsAuthenticatedOrReadOnly'
    ]
    }

  2. 生成 Token:

    可以通过以下方式生成 Token：

    • 手动生成: 在 Django Admin 界面 (需要创建超级用户)，为用户手动创建 Token。

    • 信号量: 使用信号量，在用户创建时自动生成 Token。 在 blog/apps.py 添加：

      “`python
      from django.apps import AppConfig

      class BlogConfig(AppConfig):
      default_auto_field = ‘django.db.models.BigAutoField’
      name = ‘blog’

      def ready(self):
    import blog.signals # 导入 signals.py

      “`

      然后创建 blog/signals.py：

      “`python
      from django.conf import settings
      from django.db.models.signals import post_save
      from django.dispatch import receiver
      from rest_framework.authtoken.models import Token

      @receiver(post_save, sender=settings.AUTH_USER_MODEL)
      def create_auth_token(sender, instance=None, created=False, **kwargs):
      if created:
      Token.objects.create(user=instance)
      “`

      运行 python manage.py migrate

    现在，当创建新用户时，会自动生成一个 Token。

  3. 在请求中包含 Token:

    在 HTTP 请求头中，添加 Authorization 头，值为 Token <your_token>。

    例如：

    bash
    curl -X POST -H "Content-Type: application/json" -H "Authorization: Token your_token_here" -d '{"title": "My First Post", "content": "This is the content of my first post."}' http://127.0.0.1:8000/api/posts/

5. 总结

Django REST Framework 是一个功能强大且灵活的工具，可以帮助你轻松构建 RESTful API。 通过学习本文，你应该对 DRF 的核心概念、功能和优势有了全面的了解。 你可以利用 DRF 快速开发出高质量的 API，并提高开发效率。 深入研究 DRF 的文档，探索更多高级功能，可以让你更加熟练地掌握这一重要的 Web 开发技术。
“`

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部