Django REST framework 学习笔记

DRF 官网 —— https://www.django-rest-framework.org/
DRF 中文文档 —— https://q1mi.github.io/Django-REST-framework-documentation/
W3C DRF 中文教程 —— https://www.w3cschool.cn/lxraw/

Django REST framework 简介

Django REST 框架是基于 Django 用于构建 Web API 的强大而灵活的工具包。

🔗How to Develop APIs with Django REST Framework

安装 DRF 及 可选包

pip install djangorestframework
# 为 browsable API 提供 Markdown 支持
pip install markdown
# Filtering 支持
pip install django-filter

使用国内源

pip install djangorestframework --index https://pypi.tuna.tsinghua.edu.cn/simple
pip install markdown --index https://pypi.tuna.tsinghua.edu.cn/simple
pip install django-filter --index https://pypi.tuna.tsinghua.edu.cn/simple

编辑 djangoProject/settings.py 启用 DRF 应用

INSTALLED_APPS = [
    # ...
	'app_users',  # 启用  app_users 应用
    'rest_framework',  # 启用 DRF
]

全局设置

编辑 djangoProject/settings.py

INSTALLED_APPS = (
    # ...
    'rest_framework',
)

REST_FRAMEWORK = {
    # 仅限管理员查看和编辑。
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAdminUser', 
    ],
    # 启用分页
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

新建一个用户应用的 API

创建一个简单的允许管理员用户查看和编辑系统中的用户和组的 API

创建应用

python3 manage.py startapp app_user

序列化器

开发 Web API 的第一件事是为 Web API 提供一种将代码片段实例序列化和反序列化为诸如 json 之类的表示形式的方式。DRF 则通过声明与 Django forms 非常相似的序列化器（serializers）来实现。

序列化器允许把像查询集和模型实例这样的复杂数据转换为可以轻松渲染成 JSON，XML 或其他内容类型的原生 Python 类型。序列化器还提供反序列化，在验证传入的数据之后允许解析数据转换回复杂类型。

Serializer 类，它为你提供了强大的通用方法来控制响应的输出。
ModelSerializer类，它为创建用于处理模型实例和查询集的序列化程序提供了有用的快捷实现方式。 HyperlinkedModelSerializer 类，它可以使用超链接来表示关联关系而不是主键。

创建 app_user/serializers.py

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


# ModelSerializer 类能够让你自动创建一个具有模型中相应字段的 Serializer 类。
# 这个 ModelSerializer 类和常规的 Serializer 类一样，不同的是：
#     - 它根据模型自动生成一组字段。
#     - 它自动生成序列化器的验证器，比如 unique_together 验证器。
#     - 它默认简单实现了.create()方法和.update()方法。
class UserSerializer(serializers.ModelSerializer):
    """用户 序列化器"""
    class Meta:
        model = User
        # 可以将 fields 属性设置成'__all__'来表明使用模型中的所有字段
        # fields = '__all__'
        # 可以将 exclude 属性设置成一个从序列化器中排除的字段列表
        # 注意：exclude 和 fields 不能同时使用
        exclude = ('is_superuser', 'password', 'email', 'user_permissions')


# HyperlinkedModelSerializer 类使用超链接来表示关联关系而不是主键。
# 默认情况下序列化器将包含一个 url 字段而不是主键字段。
# url 字段将使用 HyperlinkedIdentityField 字段来表示，
# 模型的任何关联都将使用 HyperlinkedRelatedField 字段来表示。
class GroupSerializer(serializers.HyperlinkedModelSerializer):
    """用户组 序列化器"""
    class Meta:
        model = Group
        # 强烈建议你使用 fields 属性显式的设置要序列化的字段
        fields = ('url', 'id', 'name')

视图集

REST 框架包括一个用于处理 ViewSets 的抽象，它允许开发人员集中精力对 API 的状态和交互进行建模，并根据常规约定自动处理 URL 构造。
ViewSet 只是一种基于类的视图，它不提供任何方法处理程序（如 .get()或.post()），而是提供诸如 .list() 和 .create() 之类的操作。
ViewSet 的方法处理程序仅使用 .as_view() 方法绑定到完成视图的相应操作。
通常不是在 URLconf 中的视图集中显示注册视图，而是要使用路由类注册视图集，该类会自动为你确定 URLconf。

编辑视图 app_user/views.py

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


# ViewSets 定义视图的行为
# ModelViewSet 类继承自 GenericAPIView，并通过混合各种 mixin 类的行为来实现各种操作。
# ModelViewSet 类提供的操作是 .list(), .retrieve(), .create(),
#                            .update(), .partial_update(), .destroy()
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer

# ReadOnlyModelViewSet 类也继承自 GenericAPIView。
# 和 ModelViewSet 一样，它也包括各种操作的实现，
# 但与 ModelViewSet 不同的是，它只提供“只读”操作、.list() 和 .removement()
class GroupViewSet(viewsets.ReadOnlyModelViewSet):
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

# 序列一个非常棒的属性就是可以通过打印序列化器类实例的结构(representation)查看它的所有字段。
serializer = UserSerializer()
print(repr(serializer))

路由器

REST 框架增加了对自动 URL 路由到 Django 的支持，并为您提供了一种简单、快速、一致的方式，将视图逻辑连接到一组 URL。

因为使用 viewsets 类，所以可通过路由器来自动确定 API URL。

SimpleRouter 路由器包括标准集合 list,create,retrieve,update,partial_update,destroy 动作的路由。视图集中还可以使用 @ detail_route 或 @ list_route 装饰器标记要被路由的其他方法。
DefaultRouter 这个路由器类似于上面的 SimpleRouter，但是还包括一个默认返回所有列表视图的超链接的 API 根视图。它还生成可选的 .json 样式格式后缀的路由。
编辑 app_user/urls.py

from django.urls import path
from django.urls import include

from . import views
from rest_framework import routers  # 引入 DRF 路由器

# 创建路由器并注册视图
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)


urlpatterns = [
    # 一个默认返回所有列表视图的超链接的 API 根视图
    path('api/', include(router.urls)),
    # 用于支持浏览器浏览的 API 的默认登录和注销视图
    path('api-auth/', include('rest_framework.urls')),
]

编辑 djangoProject/urls.py

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

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

测试我们的 API

# 启动 Django 开发服务器
python3 manage.py runserver

启动服务器后，浏览器访问：http://127.0.0.1:8000/app_user/api/