django-rest-framework指南(1):序列化
2015-08-15 16:02
681 查看
本文翻译自django rest framework官方文档,版本3.1.3
这个指南有点深入,所以建议你开始前,准备好cookie(这个真的是饼干,曲奇),泡上一杯茶.如果你只是想快速的过一遍,建议你看quickstart文档.
注意:本指南的代码托管在github,作为测试用途的沙盒版本的的完整的实现也已上线,点击这里.
现在我们在一个virtualenv环境里了,我们可以安装依赖包了.
注意:如果要退出虚拟环境,输入deactiave即可.详情请看virtualenv文档
上面的完成后我们创建一个app,这样我们就能创建一个简单的WEB API.
我们需要添加新的 sinppets app 和 rest_framework app到INSTALLED_PPS.编辑tutorial/settings.py文件:
我们还要在tutorial/urls.py文件里修改root urlconf,来include snippets app的URL.
好的,准备就绪.
注意:在代码中写注释是个好习惯.在github里的代码有注释,这里为了集中注意力到代码上省略了注释.
然后要为snippet模型做初始化migration,并首次同步数据库.
serializer类的第一部分定义了要序列化/反序列化的字段.
create()和update()方法定义了当调用serializer.save()方法时实例怎样被创建和修改.
serializer类和django Form类很像,包括各种字段的相似的验证标识,例如required, max_length和default.
字段标识还能控制特定条件下,例如渲染到html时序列化器的显示.上面的{‘base_template’: ‘textarea_html’}标识等同于使用django Form类中使用widget=widgets.Textarea.这在控制可浏览的API如何显示时非常有用,指南后面会看到的.
其实有时候我们可以使用ModelSerializer类来节省一些时间,后面会用到,但现在我们还是显式的声明序列化器.
ok,在导入了必要的模块后,创建一些代码片段实例来使用
现在我们有了一些snippet实例.接着序列化其中一个实例.
此时我们把模型实例转换成了python原生数据类型.为了完成序列化过程,我们把数据渲染成json.
反序列化相似.首先将数据流转换成Python原生数据类型…
…然后我们将这些数据存储到一个完全填充(fully populated)的对象实例.
注意,这些API和django forms十分相似.当我们开始在视图里写序列化器时就会发现更加相似了.
除了模型实例,我们也能序列化queryset.前提是,在serializer参数里简单的添加many=True.
与django提供Form类和ModelForm类相似,REST framework包含了Serializer类和ModelSerializer类.
让我们来使用ModelSerializer类来重构我们的序列化器.打开文件snippets/serializers.py,用下面的代码替换SnippetSerializer类.
这种序列化器有一个很棒的特性,你可以通过打印它的representation来检查序列化器实例的所有字段.使用python manage.py shell打开django shell,然后运行下面的代码:
记住这点很重要,ModelSerializer类没有做任何神奇的事情,他们只是创建序列化器类的简单的快捷方式:
- 自动生成的字段集合
- create()和update()方法的简单的默认实现
首先创建一个HttpResponse的子类,我们能用它来渲染json数据.
编辑snippets/views.py,添加:
API的根URL是一个视图,返回所有存在的snippet的列表,或者创建一个新的snippets.
注意:因为我们想要从客户端POST数据到这个视图,客户端没有CSRF token,我们我们要标记这个视图为csrf_token.正常情况下不这么做,REST framework视图实际上使用了比这更好的方法,但是现在暂时这么用吧.
我们还需要一个视图来处理单个snippet,用于查找,更新或删除snippet.
最后我们需要为这些视图配置URL.创建snippets/urls.py文件:
值得注意的是,有几种边缘情况我们暂时不处理.如果我们发送的JSON数据格式不正确,或者某个请求的方法,视图没有处理,我们会抛出500”server error”.
从shell退出…
…然后开启django的开发服务器.
在另一个终端窗口,我们可以测试.
我们可以使用curl或httpie来测试我们的API.Httpie是一个对用户友好的http客户端,用python编写.让我们来安装它.
你可以使用pip安装
最后,我们能获得所有的snippet列表:
或者我们可以引用id来获得单个的snippet
同样,你也可以在浏览器里访问这些URL,会显示相同的JSON.
我们的API视图暂时没有做什么很特别的事情,除了响应json数据,还有一些处理异常的边缘事件我们没做,但是至少这个WEB API能用了.
在指南的第二部分我们开始做一些改进.
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 = [ite 4000 m 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 shellpython 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. bf3d 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能用了.
在指南的第二部分我们开始做一些改进.
相关文章推荐
- 解析Silverlight调用WCF/Rest异常的解决方法
- python实现rest请求api示例
- windows+apache+mod_python配置django运行环境
- python Django连接MySQL数据库做增删改查
- django自定义Field实现一个字段存储以逗号分隔的字符串
- 深入学习JavaScript中的Rest参数和参数默认值
- 在Python的Django框架中加载模版的方法
- 在Django中使用Sitemap的方法讲解
- 详解Django中的form库的使用
- Django中的CACHE_BACKEND参数和站点级Cache设置
- 剖析Django中模版标签的解析与参数传递
- Python中DJANGO简单测试实例
- Python的Django框架中的数据库配置指南
- 在Django的上下文中设置变量的方法
- 在Python的Django框架中编写编译函数
- 在Django的URLconf中进行函数导入的方法
- 在Python的Django框架中生成CSV文件的方法
- 在主机商的共享服务器上部署Django站点的方法
- 使用Python的Django框架中的压缩组件Django Compressor
- 对于Python的Django框架部署的一些建议