Django REST Framework 入门教程

Django REST Framework (DRF) 是一个强大且灵活的工具包，用于构建 Web API。它基于 Django 构建，可以帮助您快速创建 RESTful 风格的 API。

本教程将引导您完成创建一个简单的 API 的过程，该 API 用于管理用户和组。

1. 环境准备

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

首先，我们来安装 Django 和 Django REST Framework：

bash
pip install django djangorestframework

2. 创建项目

现在，我们来创建一个新的 Django 项目。打开您的终端，进入您希望创建项目的目录，然后运行以下命令：

bash
django-admin startproject tutorial
cd tutorial

接着，我们创建一个新的 app 来存放我们的 API 逻辑：

bash
python manage.py startapp quickstart

3. 配置项目

创建完 app 后，需要将其和 DRF 添加到项目的 INSTALLED_APPS 设置中。

打开 tutorial/settings.py 文件，找到 INSTALLED_APPS 列表，并添加 'rest_framework' 和 'quickstart.apps.QuickstartConfig'：

“`python

tutorial/settings.py

INSTALLED_APPS = [
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,
# 添加 rest_framework
‘rest_framework’,
# 添加我们创建的 app
‘quickstart.apps.QuickstartConfig’,
]
“`

4. 创建模型 (Model)

我们将使用 Django 内置的 User 和 Group 模型。因此，我们不需要在 quickstart/models.py 中创建新的模型。

5. 创建序列化器 (Serializer)

序列化器允许将复杂的數據（如查询集和模型实例）转换为可以轻松呈现为 JSON、XML 或其他内容类型的原生 Python 数据类型。

在 quickstart 目录下创建一个新文件 serializers.py，并添加以下代码：

“`python

quickstart/serializers.py

from django.contrib.auth.models import User, Group
from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = User
fields = [‘url’, ‘username’, ’email’, ‘groups’]

class GroupSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = Group
fields = [‘url’, ‘name’]
“`

在这个例子中，我们使用了 HyperlinkedModelSerializer。它使用超链接来表示关系，这是一种很好的 RESTful 设计实践。

6. 创建视图 (View)

视图定义了 API 的端点（endpoints）以及它们应该如何响应请求。DRF 提供了 ViewSet，它可以将一组相关的视图逻辑组合在一起。

打开 quickstart/views.py 文件，并用以下代码替换其内容：

“`python

quickstart/views.py

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from rest_framework import permissions
from .serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
“””
允许用户查看或编辑的 API 端点。
“””
queryset = User.objects.all().order_by(‘-date_joined’)
serializer_class = UserSerializer
permission_classes = [permissions.IsAuthenticated]

class GroupViewSet(viewsets.ModelViewSet):
“””
允许组查看或编辑的 API 端点。
“””
queryset = Group.objects.all()
serializer_class = GroupSerializer
permission_classes = [permissions.IsAuthenticated]
“`

我们在这里为 User 和 Group 分别创建了一个 ViewSet。ModelViewSet 提供了完整的 CRUD（创建、读取、更新、删除）操作，无需我们手动实现。

permission_classes 用于控制对这些视图的访问权限。在这里，我们使用了 IsAuthenticated，表示只有经过身份验证的用户才能访问这些端点。

7. 配置 URL

现在我们需要将我们创建的视图连接到 URL。DRF 提供了 Router 类，可以自动为我们的 ViewSet 生成 URL 配置。

首先，在 quickstart 目录下创建一个 urls.py 文件：

“`python

quickstart/urls.py

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

router = routers.DefaultRouter()
router.register(r’users’, views.UserViewSet)
router.register(r’groups’, views.GroupViewSet)

使用自动 URL 路由连接我们的 API。

另外，我们还包括了 DRF 提供的登录 URL。

urlpatterns = [
path(”, include(router.urls)),
path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’))
]
“`

接下来，我们需要将这些 URL 包含到项目的主 URL 配置中。打开 tutorial/urls.py 文件，并用以下代码替换其内容：

“`python

tutorial/urls.py

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

urlpatterns = [
path(‘admin/’, admin.site.urls),
# 将 quickstart app 的 URL 包含进来
path(”, include(‘quickstart.urls’)),
]
“`

8. 数据库迁移

我们的项目使用了 Django 的内置模型，但我们仍然需要创建数据库表。

在终端中运行以下命令：

bash
python manage.py migrate

9. 运行和测试

恭喜！您的第一个 API 已经准备就绪。现在让我们来运行它。

bash
python manage.py runserver

服务器启动后，您可以在浏览器中打开 http://127.0.0.1:8000/。您将看到一个由 DRF 提供的可浏览的 API 界面。

您可以通过这个界面：
– 查看所有用户：http://127.0.0.1:8000/users/
– 查看所有组：http://127.0.0.1:8000/groups/

由于我们设置了 IsAuthenticated 权限，您需要先登录才能看到数据。您可以使用右上角的 “Log in” 链接。在此之前，您需要先创建一个超级用户：

bash
python manage.py createsuperuser

按照提示创建您的管理员账户。创建成功后，您就可以登录并与您的 API 进行交互了。

总结

本教程向您展示了如何使用 Django REST Framework 快速搭建一个功能完善的 API。您学习了如何使用序列化器、视图集和路由器来轻松地构建 RESTful 服务。

这仅仅是一个开始。DRF 提供了丰富的功能，包括认证、权限、限流、分页等等。希望本教程能为您打开探索 DRF 的大门。