Django REST Framework 入门：使用 DRF 创建 RESTful API – wiki基地

作者： /

Django REST Framework 入门：使用 DRF 创建 RESTful API

Django REST Framework (DRF) 是一个强大而灵活的工具包，用于构建 Web API。它基于 Django，提供了一系列特性和工具，使得创建 RESTful API 变得更加简单和高效。本文将深入探讨如何使用 Django REST Framework 创建一个完整的 RESTful API，从环境搭建到最终的 API 测试，涵盖了关键概念和常见用例。

1. 为什么选择 Django REST Framework?

在构建 Web API 时，有很多选择。那么，为什么选择 Django REST Framework 呢？以下是一些关键优势：

  • 序列化器（Serializers）： DRF 提供了强大的序列化器，可以将复杂的数据类型（如 Django 模型实例）转换为 JSON 或 XML 等格式，方便 API 的数据传输。反之，序列化器也能将传入的请求数据进行校验和转换为 Python 数据类型，以便存储到数据库中。
  • 视图（Views）： DRF 扩展了 Django 的视图系统，提供了许多方便的视图类，如 APIView, ListAPIView, CreateAPIView, RetrieveAPIView, UpdateAPIView, DestroyAPIView 等。这些视图类大大简化了常见 API 操作的处理流程。
  • 认证和权限： DRF 内置了多种认证机制，如 Token 认证、Session 认证、JWT 认证等。同时，它也提供了灵活的权限控制机制，允许你基于用户身份或权限来控制 API 的访问。
  • 路由（Routers）： DRF 提供了 Router 类，可以自动生成 API 的 URL 模式，减少了手动编写 URL 路由的繁琐工作。
  • 可浏览的 API： DRF 自动生成可浏览的 API 页面，方便开发者查看 API 的接口和数据格式，并进行在线测试。
  • 定制性强： DRF 提供了丰富的选项和钩子，允许你定制 API 的各个方面，以满足不同的需求。
  • 良好的社区支持： DRF 拥有庞大的社区，提供了丰富的文档和示例，方便开发者学习和使用。

2. 环境搭建

在开始之前，需要确保已经安装了 Python 和 pip。然后，可以按照以下步骤搭建环境：

  • 创建虚拟环境 (可选但强烈推荐):

bash
python3 -m venv myenv
source myenv/bin/activate # Linux/macOS
myenv\Scripts\activate # Windows

  • 安装 Django 和 Django REST Framework:

bash
pip install django
pip install djangorestframework

  • 创建一个 Django 项目:

bash
django-admin startproject myproject
cd myproject

  • 创建一个 Django 应用:

bash
python manage.py startapp myapp

3. 配置 Django 项目

接下来，需要在 Django 项目的 settings.py 文件中进行一些配置：

  • 将 REST Framework 添加到 INSTALLED_APPS 中:

python
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'rest_framework', # 添加 REST Framework
'myapp', # 添加你的应用
]

  • 配置 REST Framework (可选):

可以在 settings.py 中配置 REST Framework 的一些全局设置。例如，可以设置默认的认证类、权限类和渲染器。

python
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticatedOrReadOnly'
],
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.SessionAuthentication',
'rest_framework.authentication.TokenAuthentication'
]
}

  • DEFAULT_PERMISSION_CLASSES: 指定默认的权限类。IsAuthenticatedOrReadOnly 表示只有认证用户才能进行写操作，未认证用户只能进行读操作。
  • DEFAULT_AUTHENTICATION_CLASSES: 指定默认的认证类。SessionAuthentication 使用 Django 的 Session 机制进行认证，TokenAuthentication 使用 Token 进行认证。

4. 定义模型 (Models)

假设我们要创建一个简单的博客 API，需要定义一个 Post 模型。在 myapp/models.py 文件中定义模型：

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

“`

  • title: 博客文章的标题，是一个字符串字段，最大长度为 200。
  • content: 博客文章的内容，是一个文本字段。
  • created_at: 创建时间，是一个日期时间字段，auto_now_add=True 表示在创建时自动设置当前时间。
  • updated_at: 更新时间，是一个日期时间字段，auto_now=True 表示在每次更新时自动设置当前时间。
  • __str__: 定义了模型的字符串表示形式，方便在管理后台和其他地方显示。

5. 创建序列化器 (Serializers)

序列化器用于将模型实例转换为 JSON 格式，并将 JSON 格式转换为模型实例。在 myapp/serializers.py 文件中创建序列化器：

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

class PostSerializer(serializers.ModelSerializer):
class Meta:
model = Post
fields = ‘all‘ # 使用模型的所有字段
# 或者指定需要的字段：
# fields = (‘id’, ‘title’, ‘content’, ‘created_at’, ‘updated_at’)
“`

  • ModelSerializer: DRF 提供的一个方便的序列化器，可以根据模型自动生成字段。
  • Meta: 一个内部类，用于指定序列化器的元数据。
    • model: 指定序列化器对应的模型。
    • fields: 指定要序列化的字段。'__all__' 表示序列化所有字段，也可以指定一个字段列表。

6. 创建视图 (Views)

视图用于处理 API 请求，并返回响应。在 myapp/views.py 文件中创建视图：

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

class PostList(generics.ListCreateAPIView):
queryset = Post.objects.all()
serializer_class = PostSerializer

class PostDetail(generics.RetrieveUpdateDestroyAPIView):
queryset = Post.objects.all()
serializer_class = PostSerializer
“`

  • ListCreateAPIView: 一个通用的视图，用于列出所有博客文章 (GET) 和创建新的博客文章 (POST)。
  • RetrieveUpdateDestroyAPIView: 一个通用的视图，用于检索单个博客文章 (GET), 更新单个博客文章 (PUT/PATCH), 和删除单个博客文章 (DELETE)。
  • queryset: 指定要查询的模型实例集合。
  • serializer_class: 指定要使用的序列化器。

7. 配置 URL 路由 (URLs)

需要在 Django 项目的 urls.py 文件中配置 URL 路由，将 API 视图映射到 URL。首先，在 myapp 应用中创建一个 urls.py 文件：

“`python

myapp/urls.py

from django.urls import path
from . import views

urlpatterns = [
path(‘posts/’, views.PostList.as_view()),
path(‘posts//’, views.PostDetail.as_view()),
]
“`

  • path: Django 的 URL 路由函数，用于将 URL 模式映射到视图。
  • views.PostList.as_view(): 将 PostList 视图转换为一个可调用的视图函数。
  • views.PostDetail.as_view(): 将 PostDetail 视图转换为一个可调用的视图函数。
  • <int:pk>: 一个 URL 参数，用于捕获博客文章的 ID (主键)。

然后，在项目级别的 urls.py 文件 (例如 myproject/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’)), # 包含 myapp 的 URL 路由
]
“`

  • include: 用于包含其他 URL 路由文件。

8. 数据库迁移

现在，需要创建数据库并进行迁移：

bash
python manage.py makemigrations myapp
python manage.py migrate

  • makemigrations: 创建一个新的迁移文件，用于更新数据库模式。
  • migrate: 将迁移文件应用到数据库。

9. 创建超级用户

为了访问 Django 的管理后台，需要创建一个超级用户：

bash
python manage.py createsuperuser

按照提示输入用户名、电子邮件地址和密码。

10. 测试 API

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

bash
python manage.py runserver

打开浏览器，访问以下 URL：

  • http://127.0.0.1:8000/api/posts/: 获取所有博客文章的列表。
  • http://127.0.0.1:8000/api/posts/{id}/: 获取 ID 为 {id} 的博客文章的详细信息。

DRF 会自动生成可浏览的 API 页面，方便你查看 API 的接口和数据格式，并进行在线测试。你也可以使用 Postman 或 curl 等工具来测试 API。

11. 添加认证和权限

为了保护 API，可以添加认证和权限控制。在 myapp/views.py 文件中，可以为视图添加权限类：

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

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] # 添加权限类
“`

  • permission_classes: 指定视图需要使用的权限类。IsAuthenticatedOrReadOnly 表示只有认证用户才能进行写操作，未认证用户只能进行读操作。

为了使用 Token 认证，需要在 settings.py 文件中将 rest_framework.authtoken 添加到 INSTALLED_APPS 中：

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

然后，运行迁移：

bash
python manage.py migrate

现在，可以在 Django 的管理后台中为用户创建 Token。创建 Token 后，可以在 API 请求的 Authorization 头中包含 Token {token}，进行身份验证。

12. 使用 ViewSets 和 Routers (可选)

ViewSet 是一种将相关视图组合在一起的方式，可以减少代码的重复。Router 可以自动生成 API 的 URL 模式，减少了手动编写 URL 路由的繁琐工作。

在 myapp/views.py 文件中创建一个 ViewSet：

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

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

  • ModelViewSet: 一个通用的 ViewSet，提供了对模型的 CRUD (创建、读取、更新、删除) 操作。

然后，在 myapp/urls.py 文件中使用 Router 自动生成 URL 路由：

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

router = routers.DefaultRouter()
router.register(r’posts’, views.PostViewSet) # 注册 PostViewSet

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

  • DefaultRouter: DRF 提供的一个默认 Router 类，可以自动生成 URL 模式。
  • router.register: 将 ViewSet 注册到 Router 中。r'posts' 是 URL 前缀。

现在，可以访问以下 URL：

  • http://127.0.0.1:8000/api/posts/: 获取所有博客文章的列表 (GET) 或创建新的博客文章 (POST)。
  • http://127.0.0.1:8000/api/posts/{id}/: 获取 ID 为 {id} 的博客文章的详细信息 (GET), 更新单个博客文章 (PUT/PATCH), 和删除单个博客文章 (DELETE)。

13. 总结

本文详细介绍了使用 Django REST Framework 创建 RESTful API 的过程，涵盖了环境搭建、模型定义、序列化器创建、视图编写、URL 路由配置、数据库迁移、认证和权限控制，以及 ViewSets 和 Routers 的使用。通过学习本文，你应该能够掌握 DRF 的基本概念和用法，并能够使用 DRF 构建自己的 RESTful API。

这只是一个入门示例，Django REST Framework 提供了许多高级特性和定制选项，可以满足各种复杂的 API 需求。建议查阅官方文档，深入学习 DRF 的各个方面，以便更好地利用 DRF 构建高质量的 Web API。

后续学习建议:

  • Pagination: 如何对 API 结果进行分页。
  • Filtering: 如何对 API 结果进行过滤和搜索。
  • Custom Serializer Fields: 如何创建自定义的序列化器字段。
  • Custom Permissions: 如何创建自定义的权限类。
  • Testing: 如何编写 API 的测试用例。
  • Versioning: 如何对 API 进行版本控制。
  • Documentation: 如何自动生成 API 文档 (例如使用 Swagger 或 OpenAPI)。

希望这篇文章能够帮助你入门 Django REST Framework! 祝你构建 API 之旅顺利!

发表评论

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

滚动至顶部