Django - REST framework - 001 - 序列化

時間 2019-12-08

標籤 django rest framework 序列欄目 Python 简体版

原文原文鏈接

參考資料：官方文檔html

介紹

該教程將爲你演示如何構建一個相似於pastebin的代碼高亮的web API。
在這個過程當中，咱們將會向你介紹構成REST framework的各類組件，並幫助你更深入的理解它是怎樣工做的。python

構造一個新的環境

首先，咱們使用virtualenv構建一個新的虛擬環境。它可使咱們的包配置與其餘正在使用的項目很好的隔離。web

virtualenv env
source env/bin/activate
複製代碼

如今咱們在virtualenv環境中，能夠安裝咱們的包需求了。shell

pip install django
pip install djangorestframework
pip install pygments  # We'll be using this for the code highlighting
複製代碼

開始

Okay，如今咱們能夠開始了首先，新建一個項目。數據庫

cd ~
django-admin startproject tutorial
cd tutorial
複製代碼

而後新建一個app。咱們將基於這個app構建Web api。django

python manage.py startapp snippets
複製代碼

將新的app snippets 和 rest_framework app 添加到 INSTALLED_APPS中。編輯tutorial/settings.py 文件，添加如下內容:json

INSTALLED_APPS = (
    ...
    'rest_framework',
    'snippets.apps.SnippetsConfig',
)
複製代碼

建立一個model

接下來，咱們將建立一個簡單的 Snippet 模型，用來存儲code片斷。編輯 snippets/models.py 文件。api

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 model建立一個初始化的migration，而後與數據庫關聯並同步。瀏覽器

python manage.py makemigrations snippets
python manage.py migrate
複製代碼

新建一個Serializer class

構造Web API，第一件事情就是提供一個爲snippet 實例序列化和反序列化的方法，好比將它序列化爲json。
咱們能夠經過聲明一個serializers來達成目的，這種方式和Django's forms很相似。
在snippets 路徑下，建立文件 serializers.py ，並添加下面的內容。安全

from rest_framework import serializers
from snippets.models import Snippet, LANGUAGE_CHOICES, STYLE_CHOICES


class SnippetSerializer(serializers.Serializer):
    id = 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):
        """ Create and return a new `Snippet` instance, given the validated data. """
        return Snippet.objects.create(**validated_data)

    def update(self, instance, validated_data):
        """ Update and return an existing `Snippet` instance, given the validated data. """
        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
複製代碼

SnippetSerializer class中的第一部分定義了有哪些字段須要被序列化/反序列化。
方法 create() 和 update() 定義了當調用**serializer.save()**方法時，serializer應該怎樣構造實例。
一個serializer class 和Django 的Form class是很類似的。這其中包括一些校驗標誌也是很類似的，好比：required, max_length 和 default等。
這些字段標誌能夠控制特定情形下serializer的表現，好比應該在何時渲染HTML。
配置 {'base_template': 'textarea.html'} 字段和在Django Form class上使用 widget=widgets.Textarea 是等價的。
這對於控制 browsable API 應該怎樣表現是很是有用的，這一點在後面的教程中也能夠看到。
咱們也能夠直接使用 Model Serializer class來節省咱們的時間，它的具體用法，在教程後面的部分將會有介紹。如今咱們先使用定製化的serializer。

使用 serializer

在更近一步以前，咱們先來熟悉一下Serializer class。鍵入命令，進入Django shell環境：

python manage.py shell
複製代碼

導入一些必要的依賴，而後構建兩個snippet實例。

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
# {'id': 2, 'title': '', 'code': 'print("hello, world")\n', 'linenos': False, 'language': 'python', 'style': 'friendly'}
複製代碼

以看到，咱們已經將snippet實例轉化成了Python原生數據類型。進一步將數據轉化成 json。

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

反序列化的過程和序列化過程是類似的。首先咱們將一個流解析成Python原始數據類型...

import io
stream = io.BytesIO(content)
data = JSONParser().parse(stream)
複製代碼

而後將數據存儲成一個對象實例。

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是很是類似的。當咱們開始編寫視圖代碼的時候，會更加體會到這種類似性。
咱們也能夠將一個查詢集合進行序列化。只須要添加many=True 字段做爲serializer的參數。

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

使用 ModelSerializer

SnippetSerializer class 複製了大量的信息，這些信息一樣存在於Snippet模型中。若是可讓咱們的代碼再簡潔一點，就更好了。
與Django 提供了Form classes 和 ModelForm classes同樣， REST framework 也提供了Serializer classes, 和 ModelSerializer classes。
讓咱們使用ModelSerializer class 重構序列化的過程。編輯文件snippets/serializers.py，使用如下內容代替原來的SnippetSerializer class：

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')...
複製代碼

其實，ModelSerializer classes 並無作什麼特殊的事情，它只是提供了建立一個序列化類的替代和簡寫方式：

自動肯定的字段集。
簡單的默認的create() and update() 方法實現。

使用Serializer編寫常規的 Django視圖

下面，咱們將使用新的Serializer class來編寫一些API。咱們暫時不會使用REST framework 的任何其餘特性，只是編寫一個常規的Django 視圖。
編輯文件 snippets/views.py ，並添加下列內容：

from django.http import HttpResponse, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from rest_framework.parsers import JSONParser
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer
複製代碼

API的目的是構造一個視圖，能夠支持列舉和新建snippet對象。

@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, safe=False)

    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)
複製代碼

注意到若是在用戶端沒有CSRF token的狀況下，使用POST方法，須要將咱們的視圖添加一個裝飾器 csrf_exempt。
這並非正確和常規的作法，這裏只是爲了提供演示。事實上，REST framework 視圖提供了靈敏的安全校驗功能供使用。
咱們還須要建立一個視圖用戶對單個snippet對象的檢索、更新和刪除操做。

@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.urls import path
from snippets import views

urlpatterns = [
    path('snippets/', views.snippet_list),
    path('snippets/<int:pk>/', views.snippet_detail),
]
複製代碼

同時，咱們須要在項目根域目錄下配置文件tutorial/urls.py，引入snippet app的URL配置。

from django.urls import path, include

urlpatterns = [
    path('', include('snippets.urls')),
]
複製代碼

上面的示例中，有許多邊界狀況並無處理，這並不影響咱們將基本面展現給你。
若是咱們發送一個非預期的json字符串，或者接收到了一個並不支持的請求，將會返回一個500 "server error" 的響應。

測試 Web API

如今咱們將啓動一個簡單的server，
首先退出shell...

quit()
複製代碼

而後啓動一個 Django server

python manage.py runserver

Validating models...

0 errors found
Django version 1.11, 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 install httpie
複製代碼

最後，咱們能夠得到snippets的列表：

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"
}
複製代碼