django-rest-framework指南(1):序列化
本文翻译自django rest framework官方文档,版本3.1.3
Tutorial 1: Serialization
Introduction
这个指南会创建一个代码高亮WEB API.通过这个例子一步一步的介绍组成REST framework的多个部件,并全面介绍它们是怎么组合到一起的.
这个指南有点深入,所以建议你开始前,准备好cookie(这个真的是饼干,曲奇),泡上一杯茶.如果你只是想快速的过一遍,建议你看quickstart文档.
注意:本指南的代码托管在github,作为测试用途的沙盒版本的的完整的实现也已上线,点击这里.
Setting up a new environment
在我们做所有事之前,使用virtualenv创建一个新的虚拟环境.这会使我们的配置和其他项目隔离开来.
virtualenv env
source env/bin/active现在我们在一个virtualenv环境里了,我们可以安装依赖包了.
pip install django
pip install djangorestframework
pip install pygments # 我们将使用它来做代码高亮注意:如果要退出虚拟环境,输入deactiave即可.详情请看virtualenv文档
Getting started
ok,我们准备要写代码了.开始前,先创建一个新项目.
cd ~
django-admin.py startproject tutorial
cd tutorial上面的完成后我们创建一个app,这样我们就能创建一个简单的WEB API.
python manage.py startapp sinppets我们需要添加新的 sinppets app 和 rest_framework app到INSTALLED_PPS.编辑tutorial/settings.py文件:
INSTALL_APPS = (
...
'rest_framework',
'snippets',
)
我们还要在tutorial/urls.py文件里修改root urlconf,来include snippets app的URL.
urlpatterns = {
url(r'^', include('snippets.urls')),
}好的,准备就绪.
Creating a model to work with
创建一个简单的Snippet**model来存储代码片段.然后编辑**snippets/models文件.
注意:在代码中写注释是个好习惯.在github里的代码有注释,这里为了集中注意力到代码上省略了注释.
from django.db import models
from pygments.lexers import get_all_lexers
from pygments.styles import get_all_styles
LEXERS = [item for item in get_all_lexers() if item[1]]
LANGUAGE_CHOICES = sorted([(item[1][0], item[0] for item in LEXERS)])
STYLE_CHOICES = sorted((item, item) for item in get_all_styles())
class Snippet(model.Model):
created = models.DateTimeField(auto_now_add=True)
title = models.CharField(max_length=100, blank=True, default='')
code = models.TextField()
linenos = models.BooleanField(default=False)
language = models.CharField(choices=LANGUAGE_CHOICES, default='python', max_length=100)
style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100)
class Meta:
ordering = ('created',)然后要为snippet模型做初始化migration,并首次同步数据库.
python manage.py makemigration snippets
python manage.py migrateCreating a Serializer class
写WEB API的第一件事就是提供一个方法来用特定格式(例如json)序列化和反序列化snippet实例.我们可以用django form相似的方式来声明序列化器.在snippets目录里创建文件serializers.py并添加如下代码.
from rest_framework import serializers
from snippets.models import Snippet, LANGUAGE_CHOICES, STYLE_CHOICES
class SnippetSerializer(serializers.Serializer):
pk = serializers.IntegerField(read_only=True)
title = serializers.CharField(required=False, allow_blank=True, max_length=100)
code = serializers.CharField(style={'base_template': 'textarea.html'})
linenos = serializers.BooleanField(required=False)
language = serializers.ChoiceField(choices=LANGUAGE_CHOICES, default='python')
style = serializers.ChoiceField(choices=STYLE_CHOICES, default='friendly')
def create(self, validated_data):
"""
参数是验证过的数据,创建并返回一个新的Snippet实例
"""
return Snippet.objects.create(**validated_data)
def update(self, instance, validated_data):
"""
参数是验证过的数据,更新并返回一个已存在的Snippet实例
"""
instance.title = validated_data.get('title', instance.title)
instance.code = validated_data.get('code', instance.code)
instance.linenos = validated_data.get('linenos', instance.linenos)
instance.language = validated_data.get('language', instance.language)
instance.style = validated_data.get('style', instance.style)
instance.save()
return instanceserializer类的第一部分定义了要序列化/反序列化的字段.
create()和update()方法定义了当调用serializer.save()方法时实例怎样被创建和修改.
serializer类和django Form类很像,包括各种字段的相似的验证标识,例如required, max_length和default.
字段标识还能控制特定条件下,例如渲染到html时序列化器的显示.上面的{‘base_template’: ‘textarea_html’}标识等同于使用django Form类中使用widget=widgets.Textarea.这在控制可浏览的API如何显示时非常有用,指南后面会看到的.
其实有时候我们可以使用ModelSerializer类来节省一些时间,后面会用到,但现在我们还是显式的声明序列化器.
Working with Serializers
进行下一步之前,先熟悉一下序列化类.进入django shell
python manage.py shellok,在导入了必要的模块后,创建一些代码片段实例来使用
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer
from rest_framework.renderers import JSONRenderer
from rest_framework.parsers import JSONParser
snippet = Snippet(code='foo = "bar"\n')
snippet.save()
snippet = Snippet(code='print "hello, world"\n')
snippet.save()
现在我们有了一些snippet实例.接着序列化其中一个实例.
serializer = SnippetSerializer(snippet)
serializer.data
# {'pk': 2, 'title': u'', 'code': u'print "hello, world"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'}此时我们把模型实例转换成了python原生数据类型.为了完成序列化过程,我们把数据渲染成json.
content = JSONRender().render(serializer.data)
content
# '{"pk": 2, "title": "", "code": "print \\"hello, world\\"\\n", "linenos": false, "language": "python", "style": "friendly"}'反序列化相似.首先将数据流转换成Python原生数据类型…
from django.utils.six import BytesIO
stream = BytesIO(content)
data = JSONParser().parse(stream)…然后我们将这些数据存储到一个完全填充(fully populated)的对象实例.
serializer = SnippetSerializer(data=data)
serializer.is_valid()
# True
serializer.validated_data
# OrderedDict([('title', ''), ('code', 'print "hello, world"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])
serializer.save()
#注意,这些API和django forms十分相似.当我们开始在视图里写序列化器时就会发现更加相似了.
除了模型实例,我们也能序列化queryset.前提是,在serializer参数里简单的添加many=True.
serializer = SnippetSerializer(Snippet.objects.all(), many=True)
serializer.data
# [{'pk': 1, 'title': u'', 'code': u'foo = "bar"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'}, {'pk': 2, 'title': u'', 'code': u'print "hello, world"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'}] Using ModelSerializers
我们的SnippetSerializer class有很多信息都是Snippet模型有的.保持代码的简洁是很好的.
与django提供Form类和ModelForm类相似,REST framework包含了Serializer类和ModelSerializer类.
让我们来使用ModelSerializer类来重构我们的序列化器.打开文件snippets/serializers.py,用下面的代码替换SnippetSerializer类.
class SnippetSerializer(serializers.ModelSerializer):
class Meta:
model = Snippet
fields = ('id', 'title', 'code', 'linenos', 'language', 'style')这种序列化器有一个很棒的特性,你可以通过打印它的representation来检查序列化器实例的所有字段.使用python manage.py shell打开django shell,然后运行下面的代码:
>>> from snippets.serializers import SnippetSerializer
>>> serializer = SnippetSerializer()
>>> print(repr(serializer))
SnippetSerializer():
id = IntegerField(label='ID', read_only=True)
title = CharField(allow_blank=True, max_length=100, required=False)
code = CharField(style={'base_template': 'textarea.html'})
linenos = BooleanField(required=False)
language = ChoiceField(choices=[('Clipper', 'FoxPro'), ('Cucumber', 'Gherkin'), ('RobotFramework', 'RobotFramework'), ('abap', 'ABAP'), ('ada', 'Ada')...
style = ChoiceField(choices=[('autumn', 'autumn'), ('borland', 'borland'), ('bw', 'bw'), ('colorful', 'colorful')...记住这点很重要,ModelSerializer类没有做任何神奇的事情,他们只是创建序列化器类的简单的快捷方式:
- 自动生成的字段集合
- create()和update()方法的简单的默认实现
Writing regular Django views using our Serializer(使用Serializer编写常规的djang视图)
让我们来看看怎样使用新的Serializer类来编写一些API视图.我们暂时不使用任何REST framework的其他特性,只是写常规的django视图.
首先创建一个HttpResponse的子类,我们能用它来渲染json数据.
编辑snippets/views.py,添加:
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from rest_framework.renders import JSONRender
from rest_framework.parsers import JSONParser
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer
class JSONResponse(HttpResponse):
'''
一个HttpResponse,将content渲染为JSON
'''
def __init__(self, data, **kwargs):
content = JSONRender().render(data)
kwarg['content-type'] = 'application/json'
super(JSONResponse, self).__init__(content, **kwargs)API的根URL是一个视图,返回所有存在的snippet的列表,或者创建一个新的snippets.
@csrf_exempt
def snippet_list(request):
'''
所有代码片段的列表,或者创建一个新的snippet.
'''
if request.method == 'GET':
snippets = Snippet.objects.all()
serializer = SnippetSerializer(snippets, many=True)
return JSONResponse(serializer.data)
elif request.method == 'POST':
data = JSONParser().parse(request)
serializer = SnippetSerializer(data=data)
if serializer.is_valid():
serializer.save()
return JSONResponse(serializer.data, status=201)
return JSONResponse(serializer.errors, status=400)注意:因为我们想要从客户端POST数据到这个视图,客户端没有CSRF token,我们我们要标记这个视图为csrf_token.正常情况下不这么做,REST framework视图实际上使用了比这更好的方法,但是现在暂时这么用吧.
我们还需要一个视图来处理单个snippet,用于查找,更新或删除snippet.
@csrf_token
def snippet_detail(request, pk):
'''
查找,更新或删除一个snippet.
'''
try:
snippet = Snippet.objects.get(pk=pk)
except Snippet.DoesNotExist:
return HttpResponse(status=404)
if request.method == 'GET':
serializer = SnippetSerializer(snippet)
return JSONResponse(serializer.data)
elif request.method == 'PUT':
data = JSONParser().parse(request)
serializer = SnippetSerializer(snippet, data=data)
if serializer.is_valid()
serializer.save()
return JSONResponse(serializer.data)
return JSONResponse(serializer.errors, stats=400)
elif request.method == 'DELETE':
snippet.delete()
return HttpResponse(status=204)最后我们需要为这些视图配置URL.创建snippets/urls.py文件:
from django.conf.urls import url
from snippets import views
urlpatterns = [
url(r'snippets/$', views.snippet_list),
url(r'snippets/(?P[0-9]+)/$' , views.snippet_detail),
]值得注意的是,有几种边缘情况我们暂时不处理.如果我们发送的JSON数据格式不正确,或者某个请求的方法,视图没有处理,我们会抛出500”server error”.
Testing our first attempt at a Web API
现在我们可以启动示例服务器,提供snippet.
从shell退出…
quit()…然后开启django的开发服务器.
python manage.py runserver
Validating models...0 errors found
Django version 1.8.3, using settings 'tutorial.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C. 在另一个终端窗口,我们可以测试.
我们可以使用curl或httpie来测试我们的API.Httpie是一个对用户友好的http客户端,用python编写.让我们来安装它.
你可以使用pip安装
pip install httpie最后,我们能获得所有的snippet列表:
http http://127.0.0.1:8000/snippets/
HTTP/1.1 200 OK
...
[
{
"id": 1,
"title": "",
"code": "foo = \"bar\"\n",
"linenos": false,
"language": "python",
"style": "friendly"
},
{
"id": 2,
"title": "",
"code": "print \"hello, world\"\n",
"linenos": false,
"language": "python",
"style": "friendly"
}
]
或者我们可以引用id来获得单个的snippet
http http://127.0.0.1:8000/snippets/2/
HTTP/1.1 200 OK
...
{
"id": 2,
"title": "",
"code": "print \"hello, world\"\n",
"linenos": false,
"language": "python",
"style": "friendly"
}
同样,你也可以在浏览器里访问这些URL,会显示相同的JSON.
Where are we now
到现在为止我们都做的很好,我们已经有了很像Django form API的序列化API,和一些常规django视图.
我们的API视图暂时没有做什么很特别的事情,除了响应json数据,还有一些处理异常的边缘事件我们没做,但是至少这个WEB API能用了.
在指南的第二部分我们开始做一些改进.