Django REST framework教程一：序列化

教程索引目录

Django REST framework的系列教程

对于需要通篇了解的同学，可以点击教程索引目录。

入门介绍

本教程将涵盖一个简单的PasteBin1代码高亮的Web API。整个过程，将逐一介绍REST framework的各个组成部件，让你全面理解，组件之间是如何整合的。

本教程有点深度，所以在开始之前，你也许会需要几片曲奇饼，一杯你最爱的饮品来压压惊～。如果你只是想有个快速的鸟瞰，也许你该掉头去看看快速入门文档。

留意： 本教材的代码可以在Github中找到：tomchristie/rest-framework-tutorial。完整的代码部署在线上的沙盒版本（sand version）里，用作测试。

搭建一个新的环境

在一切的开始之前，我们会先使用 virtualenv 创建一个新的虚拟环境。这会使我们的软件支持包配置(package configuration)，完美的独立于其他正在进行中的项目。

virtualenv env
source env/bin/activate

现在我们处于一个虚拟环境中了，让我们开始安装我们需要的软件支持包（package）吧。

pip install django
pip install djangorestframework
pip install pygments  #我们将使用它来实现代码高亮

注意：任何时候需要离开虚拟环境，只需输入命令

deactivate

。更多的信息，请看 virtualenv文档

开始之前

好了，我们准备好敲代码了。开始之前，我们需要创建一个项目（project）。

cd ~
django-admin.py startproject tutorial
cd tutorial

然后我们创建一个app，来构建简单的Web API。

python manage.py startapp snippets

我们需要将这个新建的

snippets

app 和

rest_framework

app 添加到

INSTALLED_APPS

中。编辑

tutorial/settings.py

文件：

INSTALLED_APPS = (
...
'rest_framework',
'snippets.apps.SnippetsConfig',
)

好啦，我们准备好要大干一场了。

创建模型（model）

出于教程的设计考虑，我们将先创建一个简单的

Snippets

模型，用来存储代码片段。那么来编辑

snippets/models.py

文件吧。注意：一个好的编程实践会含有注释。尽管你会在教程的示范代码中找到注释，但为了专注于代码本身，我们在这里将省略注释。

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(models.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 makemigrations snippets
python manage.py migrate

创建序列器（Serializer）类

我们的 Web API 将开始于，为代码片段的实例（instances）提供序列化和反序列化的途径，使之可以转化为，某种表现形式如

json

。我们可以借助声明序列器（serializer）来实现，类似于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 instance

序列器(serializer)类的第一部分，告诉REST框架，哪些字段(field)，需要被序列化/反序列化。

create()

和

update()

方法，定义了如何创建和修改，一个有内容的实例对象。这两个方法会在运行

serializer.save()

时，被调用。

序列器类非常类似Django的

Form

类，在多个字段中，也包含了类似的验证标识(validation flags)，如

required

，

max_length

和

default

。

字段标识（flag）也能，控制序列器，在特定情况下，是如何呈现（displayed）的，比如需要渲染（rendering）成HTML。上面的

{'base_template': 'textarea.html'}

标识，相当于在Django的

Form

类中使用

widget=widgets.Textarea

。这尤其在控制可视化API如何来呈现时，特别有用。我们在后面的教程中，会看到这点。

事实上，一会我们可以看到，如何使用

ModelSerializer

类， 来节省一些时间。但现在，我们会保持序列器中，每个字段的清晰定义。

让序列器运作起来

在此，让我们先停一停，来熟悉一下，如何使用我们新建的序列器。让我们进入Django shell。

python manage.py shell

好了，导入一些包后，为了下步的运作，让我们创建几个代码片段吧

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()

现在我们有几个，可用的代码片段实例了。让我们看看，如何来序列化，其中一个实例。

serializer = SnippetSerializer(snippet)
serializer.data
# {'pk': 2, 'title': u'', 'code': u'print "hello, world"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'}

此刻，我们将模型实例，转化成了Python的原生数据类型（native datatypes）。要完成序列化的流程，我们将data渲染成

json

。

content = JSONRenderer().render(serializer.data)
content
# '{"pk": 2, "title": "", "code": "print \\"hello, world\\"\\n", "linenos": false, "language": "python", "style": "friendly"}'

反序列化也是类似的。首先，我们将一个流（stream）解析（parse）成Python的原生数据类型（native datatypes）…

from django.utils.six import BytesIO

stream = BytesIO(content)
data = JSONParser().parse(stream)

然后，我们将原生数据类型，还原（restore）成一个被填充完毕（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()
# <Snippet: Snippet object>

注意API的工作形式是如此的相似。这种重复性的相似，会在我们的视图（view）中，用到序列器的时候，变得更加的明显。

除了模型实例，我们也可以将queryset序列化。只需在序列器的参数中加入

many=True

。

serializer = SnippetSerializer(Snippet.objects.all(), many=True)
serializer.data
# [OrderedDict([('pk', 1), ('title', u''), ('code', u'foo = "bar"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('pk', 2), ('title', u''), ('code', u'print "hello, world"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('pk', 3), ('title', u''), ('code', u'print "hello, world"'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])]

使用 模型序列器（ModelSerializers）

在

SnippetSerializer

类中，重复了许多，在

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')

序列器有个很好的特性，你可以通过打印序列器的属性，查看序列器对象中所有的字段。在Django shell中（即

python manage.py 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')...

特别需要一提的是， “ 类并没有什么神奇之处，它只是一种创建序列器的捷径：

自动地声明了一套字段

默认的实现了

create()

和

update()

方法

用序列器编写普通Django视图

来看看如何使用新建的序列器（Serializer）类来编写一些API视图。到此为止，我们还没有使用过REST framework其他的特性，我们只是编写一个普通的Django视图。

我们将从，创建一个HttpResponse的子类开始，这个子类会将任何data渲染并返回为

json

。

编辑

snippets/views.py

文件，添加下列内容：

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from rest_framework.renderers import JSONRenderer
from rest_framework.parsers import JSONParser
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer

class JSONResponse(HttpResponse):
"""
An HttpResponse that renders its content into JSON.
"""
def __init__(self, data, **kwargs):
content = JSONRenderer().render(data)
kwargs['content_type'] = 'application/json'
super(JSONResponse, self).__init__(content, **kwargs)

我们API的根url，将会成为一个视图，显示所有现存的代码片段，或创建一个新的代码片段。

@csrf_exempt
def snippet_list(request):
"""
List all code snippets, or create a new 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_exempt

。你平时不会做这种事，实际上，相比起这个，REST framework 的视图有着更加合理的行为，但现在我们会这么操作。

我们也需要一个视图，来响应某个单独的代码片段，并且可以获取，更新和删除这个片段。

@csrf_exempt
def snippet_detail(request, pk):
"""
Retrieve, update or delete a code 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, status=400)

elif request.method == 'DELETE':
snippet.delete()
return HttpResponse(status=204)

最后，我们需要注册这些视图。创建

snippets/urls.py

文件：

from django.conf.urls import url
from snippets import views

urlpatterns = [
url(r'^snippets/$', views.snippet_list),
url(r'^snippets/(?P<pk>[0-9]+)/$', views.snippet_detail),
]

我们也需要，注册到

tutorial/urls.py

文件的根url配置（root urlconf）中，来包含我们的snippets app的URLs。

from django.conf.urls import url, include

urlpatterns = [
url(r'^', include('snippets.urls')),
]

需要注意的是，此刻，有一些边缘事件（edge cases），我们没有相应的处理。如果我们发送杂乱的

json

， 或一个请求使用了一种请求方法，是我们视图没有涵盖的（如modify），那么我们会出现500 “server error”的响应（response）。总之，现在我们暂时这么做。

测试我们第一个访问Web API的尝试

现在让我们启动提供代码片段服务的服务器吧。

退出Django 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 。Httpie是一个使用python编写的，非常友好的http客户端。让我们安装它吧。

你可以使用 pip 安装 httpie：

pip install httpie

终于，我们获得了所有片段的列表了：

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，获取某个特定的片段：

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"
}

同样的，使用浏览器访问这些URLs时，你也会获取相同的json呈现。

我们到哪里了？

目前为止，我们做得还行，我们做的序列化API感觉跟Django的Form API 比较相似，并且我们做了一些普通的Django视图。

我们的API视图，现在还没做啥特别的事情。除了响应了json之外，还有一些没能处理的边缘事件，但至少还是个能用的Web API。

我们会在教程的第二部分(tutorial part 3)，来看看如何改进。

如果你觉得这个翻译非常有帮助，不妨小额赞助我一下，你的认可，是我的动力！

PasteBin是一个国外的代码片段分享平台，与GitHub不一样的是，它不提供代码托管和版本控制等复杂的功能。 ↩