序列化serialization
1. 设置一个新的环境
在我们开始之前， 我们首先使用virtualenv要创建一个新的虚拟环境，以使我们的配置和我们的其他项目配置彻底分开。
$mkdir ~/env$virtualenv ~/env/tutorial$source ~/env/tutorial/bin/avtivate
现在我们处在一个虚拟的环境中，开始安装我们的依赖包
$pip install django$pip install djangorestframework$pip install pygments ////使用这个包，做代码高亮显示
需要退出虚拟环境时，运行deactivate。更多信息，irtualenv document
2. 开始
环境准备好只好，我们开始创建我们的项目
$ cd ~$ django-admin.py startproject tutorial$ cd tutorial
项目创建好后，我们再创建一个简单的app
$python manage.py startapp snippets
我们使用sqlite3来运行我们的项目tutorial，编辑tutorial/settings.py, 将数据库的默认引擎engine改为sqlite3, 数据库的名字name改为tmp.db
databases = { 'default': { 'engine': 'django.db.backends.sqlite3', 'name': 'tmp.db', 'user': '', 'password': '', 'host': '', 'port': '', }}
同时更改settings.py文件中的installd_apps,添加我们的app snippets和rest_framework
installed_apps = ( ... 'rest_framework', 'snippets',)
在tutorial/urls.py中，将snippets app的url包含进来
urlpatterns = patterns('', url(r'^', include('snippets.urls')),)
3. 创建model
这里我们创建一个简单的nippets model，目的是用来存储代码片段。
from django.db import modelsfrom pygments.lexers import get_all_lexersfrom pygments.styles import get_all_styleslexers = [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, 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',)
完成model时，记得sync下数据库
python manage.py syncdb
4. 创建序列化类
我们要使用我们的web api，要做的第一件事就是序列化和反序列化， 以便snippets实例能转换为可表述的内容，例如json. 我们声明一个可有效工作的串行器serializer。在snippets目录下面，该串行器与django 的表单形式很类似。创建一个serializers.py ，并将下面内容拷贝到文件中。
from django.forms import widgetsfrom rest_framework import serializersfrom snippets.models import snippetclass snippetserializer(serializers.serializer): pk = serializers.field() # note: `field` is an untyped read-only field. title = serializers.charfield(required=false, max_length=100) code = serializers.charfield(widget=widgets.textarea, max_length=100000) linenos = serializers.booleanfield(required=false) language = serializers.choicefield(choices=models.language_choices, default='python') style = serializers.choicefield(choices=models.style_choices, default='friendly') def restore_object(self, attrs, instance=none): create or update a new snippet instance. if instance: # update existing instance instance.title = attrs['title'] instance.code = attrs['code'] instance.linenos = attrs['linenos'] instance.language = attrs['language'] instance.style = attrs['style'] return instance # create new instance return snippet(**attrs)
该序列化类的前面部分，定义了要序列化和反序列化的类型，restore_object 方法定义了如何通过反序列化数据，生成正确的对象实例。
我们也可以使用modelserializer来快速生成，后面我们将节省如何使用它。
5. 使用 serializers
在我们使用我们定义的snippetsserializers之前，我们先熟悉下snippets.
$python manage.py shell
进入shell终端后，输入以下代码：
from snippets.models import snippetfrom snippets.serializers import snippetserializerfrom rest_framework.renderers import jsonrendererfrom rest_framework.parsers import jsonparsersnippet = snippet(code='print hello, world\n')snippet.save()
我们现在获得了一个snippets的实例，现在我们对他进行以下序列化
serializer = snippetserializer(snippet)serializer.data# {'pk': 1, 'title': u'', 'code': u'print hello, world\n', 'linenos': false, 'language': u'python', 'style': u'friendly'}
这时，我们将该实例转成了python原生的数据类型。下面我们将该数据转换成json格式，以完成序列化：
content = jsonrenderer().render(serializer.data)content# '{pk: 1, title: , code: print \\hello, world\\\\n, linenos: false, language: python, style: friendly}'
反序列化也很简单，首先我们要将一个输入流（content），转换成python的原生数据类型
import stringiostream = stringio.stringio(content)data = jsonparser().parse(stream)
然后我们将该原生数据类型，转换成对象实例
serializer = snippetserializer(data=data)serializer.is_valid()# trueserializer.object#
注意这些api和django表单的相似处。这些相似点， 在我们讲述在view中使用serializers时将更加明显。
6. 使用 modelserializers
snippetserializer使用了许多和snippet中相同的代码。如果我们能把这部分代码去掉，看上去将更佳简洁。
类似与django提供form类和modelform类，rest framework也包含了serializer 类和 modelserializer类。
打开snippets/serializers.py ,修改snippetserializer类：
class snippetserializer(serializers.modelserializer): class meta: model = snippet fields = ('id', 'title', 'code', 'linenos', 'language', 'style')
7. 通过serializer编写django view
让我们来看一下，如何通过我们创建的serializer类编写django view。这里我们不使用rest framework的其他特性，仅编写正常的django view。
我们创建一个httpresponse 子类，这样我们可以将我们返回的任何数据转换成json。
在snippet/views.py中添加以下内容：
from django.http import httpresponsefrom django.views.decorators.csrf import csrf_exemptfrom rest_framework.renderers import jsonrendererfrom rest_framework.parsers import jsonparserfrom snippets.models import snippetfrom snippets.serializers import snippetserializerclass jsonresponse(httpresponse): an httpresponse that renders it's content into json. def __init__(self, data, **kwargs): content = jsonrenderer().render(data) kwargs['content_type'] = 'application/json' super(jsonresponse, self).__init__(content, **kwargs)
我们api的目的是，可以通过view来列举全部的snippet的内容，或者创建一个新的snippet
@csrf_exemptdef snippet_list(request): list all code snippets, or create a new snippet. if request.method == 'get': snippets = snippet.objects.all() serializer = snippetserializer(snippets) 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) else: return jsonresponse(serializer.errors, status=400)
注意，因为我们要通过client向该view post一个请求，所以我们要将该view 标注为csrf_exempt, 以说明不是一个csrf事件。
note that because we want to be able to post to this view from clients that won't have a csrf token we need to mark the view as csrf_exempt. this isn't something that you'd normally want to do, and rest framework views actually use more sensible behavior than this, but it'll do for our purposes right now.
我们也需要一个view来操作一个单独的snippet，以便能更新／删除该对象。
@csrf_exemptdef 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) else: return jsonresponse(serializer.errors, status=400) elif request.method == 'delete': snippet.delete() return httpresponse(status=204)
将views.py保存，在snippets目录下面创建urls.py,添加以下内容：
urlpatterns = patterns('snippets.views', url(r'^snippets/$', 'snippet_list'), url(r'^snippets/(?p[0-9]+)/$', 'snippet_detail'),)
注意我们有些边缘事件没有处理，服务器可能会抛出500异常。
8. 测试
现在我们启动server来测试我们的snippet。
在python mange.py shell终端下执行（如果前面进入还没有退出）
>>quit()
执行下面的命令， 运行我们的server：
python manage.py runservervalidating models...0 errors founddjango version 1.4.3, using settings 'tutorial.settings'development server is running at http://127.0.0.1:8000/quit the server with control-c.
新开一个terminal来测试我们的server
序列化：
url http://127.0.0.1:8000/snippets/[{id: 1, title: , code: print \hello, world\\n, linenos: false, language: python, style: friendly}] url http://127.0.0.1:8000/snippets/1/{id: 1, title: , code: print \hello, world\\n, linenos: false, language: python, style: friendly}
request and response
1. request object ——request对象
rest framework 引入了一个继承自httprequest的request对象，该对象提供了对请求的更灵活解析。request对象的核心部分是request.data属性，类似于request.post, 但在使用web api时，request.data更有效。
（1）request.post # only handles form data. only works for 'post' method.
（2）request.data # handles arbitrary data. works any http request with content.
2. response object ——response对象
rest framework引入了一个response 对象，它继承自templateresponse对象。它获得未渲染的内容并通过内容协商content negotiation 来决定正确的content type返回给client。
return response(data) # renders to content type as requested by the client.
3. status codes
在views当中使用数字化的http状态码，会使你的代码不宜阅读，且不容易发现代码中的错误。rest framework为每个状态码提供了更明确的标识。例如http_400_bad_request。相比于使用数字，在整个views中使用这类标识符将更好。
4. 封装api views
在编写api views时，rest framework提供了两种wrappers：
1). @api_viwe 装饰器 ——函数级别
2). apiview 类——类级别
这两种封装器提供了许多功能，例如，确保在view当中能够接收到request实例；往response中增加内容以便内容协商content negotiation 机制能够执行。
封装器也提供一些行为，例如在适当的时候返回405 methord not allowed响应；在访问多类型的输入request.data时，处理任何的parseerror异常。
5. 汇总
我们开始用这些新的组件来写一些views。
我们不在需要jesonresponse 类（在前一篇中创建），将它删除。删除后我们开始稍微重构下我们的view
from rest_framework import statusfrom rest_framework.decorators import api_viewfrom rest_framework.response import responsefrom snippets.models import snippetfrom snippets.serializers import snippetserializer@api_view(['get', 'post'])def snippet_list(request): list all snippets, or create a new snippet. if request.method == 'get': snippets = snippet.objects.all() serializer = snippetserializer(snippets) return response(serializer.data) elif request.method == 'post': serializer = snippetserializer(data=request.data) if serializer.is_valid(): serializer.save() return response(serializer.data, status=status.http_201_created) else: return response(serializer.errors, status=status.http_400_bad_request)
上面的代码是对我们之前代码的改进。看上去更简洁，也更类似于django的forms api形式。我们也采用了状态码，使返回值更加明确。
下面是对单个snippet操作的view更新：
@api_view(['get', 'put', 'delete'])def snippet_detail(request, pk): retrieve, update or delete a snippet instance. try: snippet = snippet.objects.get(pk=pk) except snippet.doesnotexist: return response(status=status.http_404_not_found) if request.method == 'get': serializer = snippetserializer(snippet) return response(serializer.data) elif request.method == 'put': serializer = snippetserializer(snippet, data=request.data) if serializer.is_valid(): serializer.save() return response(serializer.data) else: return response(serializer.errors, status=status.http_400_bad_request) elif request.method == 'delete': snippet.delete() return response(status=status.http_204_no_content)
注意，我们并没有明确的要求requests或者responses给出content type。request.data可以处理输入的json请求，也可以输入yaml和其他格式。类似的在response返回数据时，rest framework返回正确的content type给client。
6. 给urls增加可选的格式后缀
利用在response时不需要指定content type这一事实，我们在api端增加格式的后缀。使用格式后缀，可以明确的指出使用某种格式，意味着我们的api可以处理类似http://example.com/api/items/4.json.的url。
增加format参数在views中，如：
def snippet_list(request, format=none):anddef snippet_detail(request, pk, format=none):
现在稍微改动urls.py文件，在现有的urls中添加一个格式后缀pattterns (format_suffix_patterns):
from django.conf.urls import patterns, urlfrom rest_framework.urlpatterns import format_suffix_patternsurlpatterns = patterns('snippets.views', url(r'^snippets/$', 'snippet_list'), url(r'^snippets/(?p[0-9]+)$', 'snippet_detail'),)urlpatterns = format_suffix_patterns(urlpatterns)
这些额外的url patterns并不是必须的。