Python的Django REST架構中的序列化及請求和返回

序列化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並不是必須的。

