在上一章里,创建了一个学生注册系统和选课系统。然后创建了展示课程内容的视图,以及学习了如何使用Django缓存框架。在这一章里有如下内容:
你可能会想建立一个接口(API),让其他应用程序和我们的网站进行交互。通过建立一个API,就可以让第三方应用程序自动化的操作和消费我们网站生产的数据。
译者注:使用API而不是模板渲染与前端进行交互,这就是前后端分离的思路。仅使用Django来进行Web开发的话前后端分离并不明显。读者在未来的Web开发中接触到前端框架就会对此有更深的了解。
有很多种方式可以建立这样一个API,推荐根据REST原则来建立这样一个API。REST是Representational State Transfer的简称。RESTful API是基于资源的,即URL用于表示网站所有的资源,HTTP的请求种类比如GET
,POST
,PUT
或DELETE
表示对应的行为,即获取,创建,更新和删除数据。不同的HTTP响应码表示这次动作的完成结果,例如2XX
表示该操作成功,4XX
表示错误等。
RESTful API常用的数据交换格式是JSON或者XML,我们准备建立一个使用JSON进行数据交换的API。我们的API会提供以下功能:
我们可以从0开始写视图来建立该API,也可以通过第三方应用简单的为项目建立API,在这方面最出名的第三方应用就是Django REST framework。
Django REST framework可以让你简单地创建符合REST风格的API,其官方网站是https://www.django-rest-framework.org/。
打开系统命令行输入如下命令:
pip install djangorestframework==3.8.2
然后编辑settings.py
激活rest_framework
应用:
INSTALLED_APPS = [ # ... 'rest_framework', ]
再在settings.py
中加入如下设置:
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly',
]
}
原书代码这里少了一个左方括号。
REST_FRAMEWORK
用于具体设置该模块。REST
framework提供了很多设置:DEFAULT_PERMISSION_CLASSES
提供了对于增删改查行为的默认权限。我们设置了DjangoModelPermissionsOrAnonReadOnly
作为唯一默认的权限类。
这个权限类依赖于Django的权限系统,让用户可以增删改查数据对象,同时让未登录用户只能进行只读操作。在下边的向视图增加权限一节中还会详细学习这部分功能。
Django REST 框架的全部设置可以在https://www.django-rest-framework.org/api-guide/settings/找到。
在设置好框架后,还需要确定使用的序列化器。网站对外提供的数据应当是经过序列化的标准数据,同时还需要对外界输入的数据进行反序列化。REST框架提供了下列类用于对一个单独对象设置序列化器:
Serializer
:为普通的Python类实例提供序列化ModelSerializer
:为数据模型的实例提供序列化HyperlinkedModelSerializer
:与ModelSerializer
的功能相同,但可以通过超链接来表示对象之间的关系,而不是通过主键关联。让我们来实际建立一个序列化器。在courses
应用中建立如下文件结构:
api/ __init__.py serializers.py
我们创建了一个叫做api
的包,然后打算在这个包里建立序列化器。编辑serializers.py
文件,添加下列代码:
from rest_framework import serializers from ..models import Subject class SubjectSerializer(serializers.ModelSerializer): class Meta: model = Subject fields = ['id', 'title', 'slug']
这是继承了ModelSerializer
类的,专门用于Subject
模型的序列化器。定义序列化器的类使用起来和Form
以及ModelForm
类很类似:Meta
内的属性允许指定要序列化的类及字段。如果不设置具体的fields
属性,则默认会包含该模型的全部字段。
来实验一下这个序列化器,进入带有Django环境的Python命令行模式:
python manage.py shell
输入以下命令:
>>> from courses.models import Subject >>> from courses.api.serializers import SubjectSerializer >>> subject = Subject.objects.latest('id') >>> serializer = SubjectSerializer(subject) >>> serializer.data {'id': 4, 'title': 'Programming', 'slug': 'programming'}
在这个例子里,先获取了一个Subject
实例,然后创建了一个序列化器的实例SubjectSerializer
并访问序列化之后的数据,可以看到模型的数据被序列化成了Python原生的字典类型数据。
序列化的结果在通过HTTP响应返回之前,必须被渲染成为一个特殊的格式。同样,在从HTTP请求中获取数据的时候,也必须解析数据然后反序列化。REST框架包含了渲染器和解析器用于处理这些过程。
先来看看如何解析数据,在Python命令行模式中输入下列命令:
>>> from io import BytesIO >>> from rest_framework.parsers import JSONParser >>> data = b'{"id":4,"title":"Programming","slug":"programming"}' >>> JSONParser().parse(BytesIO(data)) {'id': 4, 'title': 'Programming', 'slug': 'programming'}
可以看到,给定一个二进制字节流形式的JSON字符串,使用JSONParser
可以将其反序列化为Python的数据对象。
REST框架还包含渲染器Renderer
类用于格式化API的响应。框架通过上下文内容协商机制来确定使用哪种渲染器,即渲染器会通过HTTP请求的Accept
头部字段来确定这个请求所需要的内容类型来进行判断。还可以通过URL的格式化的前缀来判断,例如,一个请求返回JSON格式响应的访问可能会触发JSONRenderer
渲染器。
再回到Python命令行模式中,在刚才的代码的基础上继续执行下列代码:
>>> from rest_framework.renderers import JSONRenderer >>> JSONRenderer().render(serializer.data) b'{"id":4,"title":"Programming","slug":"programming"}'
使用JSONRenderer
可以将Python数据对象渲染成JSON字符串。REST框架提供了两个不同的渲染器:JSONRenderer
和BrowsableAPIRenderer
。后者提供了一个浏览API返回数据的web界面。可以在settings.py
的REST_FRAMEWORK
设置中的DEFAULT_RENDERER_CLASSES
选项中设置默认的渲染器。
关于渲染器和解析器的更多说明可以看https://www.django-rest-framework.org/api-guide/renderers/和https://www.django-rest-framework.org/api-guide/parsers/。
REST框架包含一系列内置的通用视图和mixins用于建立API视图,提供了增删改查数据模型对象的功能。关于所有的通用视图和mixin可以看https://www.django-rest-framework.org/api-guide/generic-views/。
现在来建立一个获取Subject
对象的视图,在courses/api/
目录内新建views.py
文件,在其中增加下列代码:
from rest_framework import generics from ..models import Subject from .serializers import SubjectSerializer class SubjectListView(generics.ListAPIView): queryset = Subject.objects.all() serializer_class = SubjectSerializer class SubjectDetailView(generics.RetrieveAPIView): queryset = Subject.objects.all() serializer_class = SubjectSerializer
在这段代码中,使用了REST框架提供的ListAPIView
和RetrieveAPIView
两个内置视图,在URL中包含一个主键参数,用于获取具体的数据对象。两个视图都有下列属性:
queryset
:基础的QuerySet,用于返回数据serializer_class
:序列化器对象,指定要使用的序列化器接下来为新的视图配置URL,在courses/api/
下新建urls.py
文件,然后编辑其中的内容:
from django.urls import path from . import views app_name = 'courses' urlpatterns = [ path('subjects/', views.SubjectListView.as_view(), name='subject_list'), path('subjects/<pk>/', views.SubjectDetailView.as_view(), name='subject_detail'), ]
然后编辑educa
项目的根urls.py
,加上一行:
urlpatterns = [ # ...... path('api/', include('courses.api.urls', namespace='api')), ]
我们为API视图使用了api
路由命名空间。启动站点,使用curl
命令访问http://127.0.0.1:8000/api/subjects/:
curl http://127.0.0.1:8000/api/subjects/
会得到和下边很相似的响应:
[ {"id":1,"title":"Mathematics","slug":"mathematics"}, {"id":2,"title":"Music","slug":"music"}, {"id":3,"title":"Physics","slug":"physics"}, {"id":4,"title":"Programming","slug":"programming"} ]
这个HTTP响应包含一系列JSON格式的字符串,其内容是序列化后的所有Subject
模型中的数据,包含指定的三个字段。如果系统中没有安装curl
,可以通过 https://curl.haxx.se/dlwiz/ 进行安装。也可以通过其他浏览器扩展比如Postman,在https://www.getpostman.com/进行安装。
现在不使用curl,而是直接在浏览器中打开http://127.0.0.1:8000/api/subjects/,会看到如下页面:
这个界面就是由之前提到的BrowsableAPIRenderer
渲染器提供的。页面内显示了结果的头部信息及API的返回信息。还可以通过在URL中包含具体的ID来获取一个Subject
对象,访问http://127.0.0.1:8000/api/subjects/1/,可以发现页面只展示了一个单独的JSON格式的对象数据。
我们再为Course
模型创建一个序列化器,打开courses/api/serializers.py
继续编辑:
from ..models import Course class CourseSerializer(serializers.ModelSerializer): class Meta: model = Course fields = ['id', 'subject', 'title', 'slug', 'overview', 'created', 'owner', 'modules']
之后看一下Course
序列化器是如何工作的,进入Python命令行模式输入下列命令:
>>> from rest_framework.renderers import JSONRenderer >>> from courses.models import Course >>> from courses.api.serializers import CourseSerializer >>> course = Course.objects.latest('id') >>> serializer = CourseSerializer(course) >>> JSONRenderer().render(serializer.data)
这个时候可以看到查询结果里,该课程包含的模块是一个主键列表的形式,类似这样:
"modules": [6, 7, 9, 10]
这样的数据意义不大,我们想在结果里包含每个Module
的更多信息,所以还必须给Module
模型也制作一个序列化器,编辑serializers.py
,修改成如下:
from rest_framework import serializers from ..models import Module class ModuleSerializer(serializers.ModelSerializer): class Meta: model = Module fields = ['order','title','description'] class CourseSerializer(serializers.ModelSerializer): modules = ModuleSerializer(many=True, read_only=True) class Meta: model = Course fields = ['id', 'subject', 'title', 'slug', 'overview', 'created', 'owner', 'modules']
首先为Module
模型制作了一个序列化器,然后给CourseSerializer
增加了一个modules
属性,设置为Module
类的序列化器,many=True
表示需要序列化多个对象,read_only
参数表示这个字段是只读的,不应该被包含在任何需要进行增删改的字段中。
重新启动Python命令行模式,再执行一遍上边Python命令行代码,使用JSONRenderer
渲染序列化器实例的data
属性,可以看到结果中关于modules
的部分被嵌套的ModuleSerializer
序列化成下面这样:
"modules": [ { "order": 0, "title": "Introduction to overview", "description": "A brief overview about the Web Framework." }, { "order": 1, "title": "Configuring Django", "description": "How to install Django." }, ... ]
这样就完成了嵌套序列化的工作,关于序列化器的更多信息可以看https://www.django-rest-framework.org/api-guide/serializers/。
REST框架提供了一个APIView
视图,基于Django内置的View
视图基础上增加了RESTful API的功能,但与View
不同的是,APIView
采用了REST框架自定义的处理Request
和Response
对象的方法,并且在返回HTTP响应的时候处理APIException
错误,而且还包含内建的认证系统来管理对视图的访问。
下边通过APIView
来创建一个视图供用户选课,编辑courses
应用的api/views.py
文件,增加如下代码:
from django.shortcuts import get_object_or_404 from rest_framework.views import APIView from rest_framework.response import Response from ..models import Course class CourseEnrollView(APIView): def post(self, request, pk, format=None): course = get_object_or_404(Course, pk=pk) course.students.add(request.user) return Response({'enrolled': True})
这个CourseEnrollView
视图管理用户选课的功能。代码解释如下:
APIView
post()
方法用于处理POST请求,这个类不需要处理其他类型的HTTP请求。pk
参数,为课程的主键id,用于取得该课程对象。如果找不到就返回404
错误。Course
对象的多对多关系,即选课。编辑api/urls.py
文件,为新的视图配置URL:
path('courses/<pk>/enroll/', views.CourseEnrollView.as_view(), name='course_enroll'),
现在理论上我们就可以发送一个POST请求来选课,而无需在页面中点击按钮。然而这么做需要区分用户身份,避免未认证的用户也来发送POST请求。下一节来看看API认证与权限管理是如何工作的。
REST框架提供了一个认证类,用于鉴别提交HTTP请求的用户身份。如果认证通过,REST框架会在request.user
中设置认证后的User
对象,如果没有用户通过认证,则request
被设置一个Django内置的AnonymousUser
对象。
REST框架提供如下的认证后端:
BasicAuthentication
:这是基础的HTTP认证(BA认证),用户和密码存放在HTTP请求头的Authorization
头部数据中,以Base64格式发送。关于BA认证的具体内容看这里。TokenAuthentication
:这是基于token的认证,一个Token
模型用于存放用户的token,HTTP请求头中的Authorization
信息中存储token数据用于验证。SessionAuthentication
:使用Django的session后端进行验证,对于前端发来的AJAX请求一般使用该方式验证。RemoteUserAuthentication
:允许使用web服务器代理认证,会设置一个REMOTE_USER
变量。除此之外,还可以继承REST框架提供的BaseAuthentication
类并且重写authenticate()方法来创建自定义的验证后端。
通过DEFAULT_AUTHENTICATION_CLASSES
还可以设置认证是基于每个视图的,还是全局认证。
认证(Authentication)只解决用户身份的问题,即识别发请求的用户身份,但不会允许或阻止用户访问视图,必须通过设置用户权限来限制访问视图。
在https://www.django-rest-framework.org/api-guide/authentication/可以找到所有认证相关的文档。
在视图中增加BasicAuthentication
类,编辑api/views.py
文件,为CourseEnrollView
添加一行:
from rest_framework.authentication import BasicAuthentication class CourseEnrollView(APIView): authentication_classes = (BasicAuthentication,) # ......
现在视图就可以通过HTTP请求头的Authorization
头部信息进行用户身份认证了。
REST框架提供了一个权限系统用于控制对视图的访问。REST框架内建的部分权限有:
AllowAny
:完全开放权限,不管用户认证与否,都不做任何限制IsAuthenticated
:仅允许通过认证的用户IsAuthenticatedOrReadOnly
:认证用户具有完整权限,匿名用户只读(只能使用GET
,HEAD
,OPTIONS
三种HTTP请求种类)。DjangoModelPermissions
:使用django.contrib.auth
的权限管理系统。视图需要一个queryset属性,只有认证的用户加上具备访问某个数据类的权限才能够进行操作DjangoObjectPermissions
:也使用Django权限,是基于每个对象的单独权限设置。如果用户因为权限问题操作失败,则通常会得到下列HTTP响应码和错误信息:
HTTP 401
: UnauthorizedHTTP 403
:Permission denied可以在https://www.django-rest-framework.org/api-guide/permissions/中找到更多关于权限的信息。
继续编辑api/views.py
文件,为CourseEnrollView
添加一个属性permission_classes
:
from rest_framework.authentication import BasicAuthentication from rest_framework.permissions import IsAuthenticated class CourseEnrollView(APIView): authentication_classes = (BasicAuthentication,) permission_classes = (IsAuthenticated,) # ......
我们为视图加上了IsAuthenticated
权限,意味着只有认证用户可以访问该视图。现在可以尝试给这个视图发一个POST请求。
启动站点,然后在系统命令行里输入下列命令:
curl -i -X POST http://127.0.0.1:8000/api/courses/1/enroll/
应该会得到下列响应:
HTTP/1.1 401 Unauthorized ...... {"detail":"Authentication credentials were not provided."}
结果得到了401
响应,因为我们没有认证过。现在我们为请求头增加一个已经注册的用户的认证信息,将下列代码中的student:password
替换成你网站中的实际用户名和密码,然后执行命令:
curl -i -X POST -u student:password http://127.0.0.1:8000/api/courses/1/enroll/
会得到如下响应:
HTTP/1.1 200 OK ...... {"enrolled":true}
现在可以到管理后台查看数据库是否已经更新了该用户选课的数据。
视图集Viewsets
允许对API定义一系列的交互动作,并允许REST框架使用一个Router
对象动态的建立URL。通过使用视图集,可以避免重复编写视图逻辑。REST框架中的视图集涵盖的经典的增删改查动作,包括list()
, create()
,
retrieve()
, update()
, partial_update()
, 和 destroy()
。
为Course
模型创建一个视图集,编辑api/views.py
文件,增加如下代码:
from rest_framework import viewsets from .serializers import CourseSerializer class CourseViewSet(viewsets.ReadOnlyModelViewSet): queryset = Course.objects.all() serializer_class = CourseSerializer
创建了一个视图集并继承了ReadOnlyModelViewSet
,ReadOnlyModelViewSet
提供了只读的list()
和retrieve()
方法,可以返回一个对象集合或者单个对象。编辑api/urls.py
,为视图集配置URL:
from django.urls import path, include from rest_framework import routers from . import views router = routers.DefaultRouter() router.register('courses', views.CourseViewSet) urlpatterns = [ # ...... path('', include(router.urls)), ]
建立了一个默认的路由对象DefaultRouter()
,然后将CourseViewSet
视图注册到路由中,使用了前缀courses
,现在这个router
对象就可以为视图集动态的生成URL。
打开http://127.0.0.1:8000/api/,可以看到如下页面:
这个时候可以访问http://127.0.0.1:8000/api/courses/,就可以得到JSON格式的课程列表。这个路径中的/courses/
就是注册路由的时候使用的前缀courses
。
视图集的详细使用可以看 https://www.django-rest-framework.org/api-guide/viewsets/,路由的使用方法可以参考https://www.django-rest-framework.org/api-guide/routers/。
可以为视图集添加额外功能。让我们来把CourseEnrollView
变成一个自定义的视图集。编辑api/views.py
文件,修改CourseViewSet
为下面这样:
from rest_framework.decorators import detail_route class CourseViewSet(viewsets.ReadOnlyModelViewSet): queryset = Course.objects.all() serializer_class = CourseSerializer @detail_route(methods=['post'], authentication_classes=[BasicAuthentication], permission_classes=[IsAuthenticated]) def enroll(self, request, *args, **kwargs): course = self.get_object() course.students.add(request.user) return Response({'enrolled': True})
为视图集增加了一个自定义的方法enroll()
,代表为视图集增加的新功能,解释如下:
detail_router
装饰器(该装饰器已经被Pycharm提醒要被删除,未来改用@action
装饰器),定义了这是一个在单个对象上执行的功能。methods
设置为['post']
表示该视图只接受POST请求,然后还设置了验证和权限。self.get_object()
获取当前的Course
对象。然后编辑api/urls.py
文件,去掉下边这一行,因为通过@detail_route
动态配置了新的路由,这一行无需再用:
path('courses/<pk>/enroll/', views.CourseEnrollView.as_view(), name='course_enroll'),
然后编辑api/views.py
,删除CourseEnrollView
,因为这个类的功能现在成为视图集的一部分。
现在选课功能的URL由router
自动生成,实际的URL与刚才相同,因为使用了我们自定义的函数名称enroll
。
我们希望只有选了某课程的学生用户才可以访问该课程的全部内容。最好的方式就是自定义一个权限,REST框架(原书为Django,应该为REST)提供了一个BasePermission
类允许重写下列方法:
has_permission()
:视图级别的权限检查has_object_permission()
:对象级别的权限检查这两个方法必须返回True
表示具有权限或False
表示不具有权限。在courses/api/
目录下新建permissions.py
文件,添加下列代码:
from rest_framework.permissions import BasePermission class IsEnrolled(BasePermission): def has_object_permission(self, request, view, obj): return obj.students.filter(id=request.user.id).exists()
这个IsEnrolled
权限继承了BasePermission
类然后重写了has_object_permission
方法。由于这个方法是基于对象的,所以obj
就是当前的课程。检查当前用户是否在已经选该课的所有用户里。之后就可以使用该权限类了。
现在已经把主题,课程和章节都序列化了。还必须序列化内容。Content
模型有一个通用外键关系,可以用于检索所有内容模型。而且我们还为所有内容模型添加了render()
方法。可以使用这些关系和方法,来实现序列化。
编辑api/serializers.py
文件,添加下列代码:
from ..models import Content class ItemRelatedField(serializers.RelatedField): def to_representation(self, value): return value.render() class ContentSerializer(serializers.ModelSerializer): item = ItemRelatedField(read_only=True) class Meta: model = Content fields = ['order', 'item']
在这段代码里,通过继承RelatedField
定义了一个特别的字段ItemRelatedField
,然后重写了to_representation()
方法。然后定义了内容序列化器ContentSerializer
并且指定与原来通用外键同名的item
属性为刚定义的ItemRelatedField
字段。
我们还需要另外一个用于Module
模型的序列化器,其中嵌套这个Content
序列化器;还需要改造Course
序列化器以让其也包含内容输出,编辑api/serializers.py
文件添加下列代码:
class ModuleWithContentsSerializer(serializers.ModelSerializer): contents = ContentSerializer(many=True) class Meta: model = Module fields = ['order', 'title', 'description', 'contents'] class CourseWithContentsSerializer(serializers.ModelSerializer): modules = ModuleWithContentsSerializer(many=True) class Meta: model = Course fields = ['id', 'subject', 'title', 'slug', 'overview', 'created', 'owner', 'modules']
这其实就是一层一层从内到外嵌套序列化器,由于已经定义了Content
的序列化器,就建立一个外层的ModuleWithContent
序列化器,其中设置contents
字段为Content
序列化器,再往上一层的CourseWithContent
序列化器也是类似来嵌套ModuleWithContent
。
再建立一个视图,模仿刚才的retrieve()
行为,但是采用新的序列化器,编辑api/views.py
文件,给CourseViewSet
视图集添加下列代码:
from .permissions import IsEnrolled from .serializers import CourseWithContentsSerializer class CourseViewSet(viewsets.ReadOnlyModelViewSet): # ... @detail_route(methods=['get'], serializer_class=CourseWithContentsSerializer, authentication_classes=[BasicAuthentication], permission_classes=[IsAuthenticated, IsEnrolled]) def contents(self, request, *args, **kwargs): return self.retrieve(request, *args, **kwargs)
这段代码解释如下:
@detail_route
装饰器来定义该方法是针对一个单独数据对象的CourseWithContentsSerializer
这个新的序列器,用于返回包含具体内容数据的序列化后输出。IsAuthenticated
和自定义权限IsEnrolled
ReadOnlyModelViewSet
提供的retrieve()
方法来返回Course
对象然后打开http://127.0.0.1:8000/api/courses/1/contents/ 。如果你的当前用户选了对应的课程,就可以看到课程,章节和内容嵌套渲染后的字符串以JSON的形式显示出来,类似下边这样:
{ "order": 0, "title": "Introduction to Django", "description": "Brief introduction to the Django Web Framework.", "contents": [ { "order": 0, "item": "<p>Meet Django. Django is a high-level Python Web framework...</p>" }, { "order": 1, "item": "\n<iframe width=\"480\" height=\"360\" src=\"http://www.youtube.com/embed/bgV39DlmZ2U?wmode=opaque frameborder=\"0\" allowfullscreen></iframe>\n" } ] }
现在我们就建立了一个简单的符合RESTful风格的API,让网站自动化向外部提供数据。REST框架还可以使用ModelViewSet
来创建和编辑数据对象。关于REST框架中的主要内容在本章都涉及到了,如果对于框架特性还需要详细了解,可以参考REST框架的官方文档:https://www.django-rest-framework.org/。
在本章,为其他程序自动化使用本网站的程序,建立了一套API,方便与其他应用程序进行互动。
下一章将讨论如何通过uWSGI和NGINX配置生产环境。你还会学到如何实现一个自定义的中间件以及建立自定义的管理命令。