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 migrate

Creating 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 instance

serializer类的第一部分定义了要序列化/反序列化的字段.
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 shell

ok,在导入了必要的模块后,创建一些代码片段实例来使用

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()
#<Snippet:Snippet object>

注意,这些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<pk>[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能用了.
在指南的第二部分我们开始做一些改进.