Django編寫RESTful API（一）：序列化

歡迎訪問我的個人網站：www.comingnext.cn

關於RESTful API

現在，在開發的過程中，我們經常會聽到前后端分離這個技術名詞，顧名思義，就是前台的開發和后台的開發分離開。這個技術方案的實現就是要借助API，API簡單說就是開發人員提供編程接口被其他人調用，他們調用之后會返回數據供其使用。API的類型有多種，但是現在比較主流且實用的就是本文要說的RESTful API，關於RESTful API，可以通過阮大神的這篇文章了解一下：http://www.ruanyifeng.com/blog/2011/09/restful 

如果懶得看，那么可以看一下下面的這個關於 RESTful API 的總結：
1.每一個URL代表一種資源
2.客戶端和服務器之間，傳遞這種資源的某種表現層
3.客戶端通過四個HTTP動詞，對服務器端資源進行操作，實現"表現層狀態轉化"。具體為：
GET用來獲取資源，POST用來新建資源（也可以用於更新資源），PUT用來更新資源，DELETE用來刪除資源。 
看這個應該能看懂，想要深入的理解需要在開發中慢慢的學習。

---

這個系列的博客文章，我是邊學邊寫的，所以這里面可能會有一些理解錯誤的，歡迎各位大佬指正~主要目的是為了交流、分享、學習

關於Django編寫RESTful API，用的當然是那個很厲害的Django庫了—— djangorestframework，而且文檔非常詳細，我就是看官方文檔學習的，這一系列的文章也是根據官方文檔來的，所以代碼和思路基本是一樣的，當然這個並不是簡單的翻譯過來而已，我加入了很多自己的理解以及實際操作中可能會遇到的一些情況，包括一些截圖希望能讓你操作起來更快更易懂。

OK，不廢話了，下面進入主題。

---

搭建開發環境

首先當然是在虛擬環境中使用了，這個不多說，需要用到的包：

pip install django pip install djangorestframework pip install pygments # 用來實現代碼高亮 

其他開發環境：

- pycharm 2017
- win 10
- Python 3.5

---

開始

首先創建一個名為tutorial的工程，然后在這個工程中創建一個snippets的APP：

django-admin.py startproject tutorial
cd tutorial
python manage.py startapp snippets

創建完成之后在tutorial/settings.py中修改一下INSTALLED_APPS，添加兩個APP：

INSTALLED_APPS = (
    ...
    'rest_framework',
    'snippets.apps.SnippetsConfig', # 如果Django<1.9，那么使用snippets代替
)

 

---

創建模型類

創建一個Snippet模型類，用於儲存代碼段，編寫snippets/models.py：

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',)

 

除了注釋的那里，其他的代碼都很常規，和我們平時Django開發時是一樣的。然后就為這個模型創建並遷移數據（這里只是為了展示，所以使用的數據庫是Django自帶的那個sqlite）：

python manage.py makemigrations snippets
python manage.py migrate

 

---

創建序列化類

到了這里就開始進入文章標題所講的序列化了。首先解釋一下序列化：在這里可以先簡單的理解為serializer（等下的代碼會引入的一個Django-REST-Framework的序列化庫）把模型實例轉化為json格式然后響應出去，這樣便於客戶端調用時解析使用。

例如一個PostModel，里面有兩個字段分別為title和author，序列化之后就是{'title':'RESTful API','author':'ziv'}這樣的json格式，這樣明顯就更適合各種客戶端的使用人員解析使用。

那么反序列化其實道理差不多，反序列化之后的數據格式更便於后台使用，等下會有例子加深理解。

解釋完序列化，那么接下來就該敲代碼了，在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)
    # 利用字段標志控制序列化器渲染到HTML頁面時的的顯示模板
    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')

    # 給定經過驗證的數據，創建並返回一個新的 Snippet 實例
    def create(self, validated_data):
        return Snippet.objects.create(**validated_data)

    # 給定經過驗證的數據，更新並返回一個已經存在的 Snippet 實例
    def update(self, instance, 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

create和update方法定義在調用serializer.save()時如何創建或修改完整的實例。

 

關於下面這行代碼：

code = serializers.CharField(style={'base_template':'textarea.html'})

暫時需要知道的就是它的功能是控制序列化器渲染到HTML頁面時的的顯示模板，至於為什么要這樣做，是因為這對於控制如何顯示可瀏覽的API特別有用，這將在后面的文章中看到。

---

使用序列化器

首先進入shell模式：

python manage.py shell

 

接下來的操作就和學習Django的orm時那樣，創建並保存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()

 

這個時候查看數據庫就會發現相關的表中已經多了兩行數據，就是我們剛才創建的數據： 

也可以繼續在shell中查看：

>>> serializer = SnippetSerializer(snippet)
>>> serializer.data
{'code': 'print "hello, world"\n', 'title': '', 'linenos': False, 'style'
: 'friendly', 'language': 'python', 'id': 2}

 

將數據渲染成json格式：

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

 

這里已經出現了json格式，也就是說這個json格式的數據就是要展示在某個URL上，大概可以感覺到，等下我們在訪問某個URL時，會返回上面這堆數據供你使用，這其實就完成了一個序列化的過程，也可以看出客戶端的功能雛形。

序列化是為了返回json格式的數據給客戶端查看和使用數據，那么當客戶端需要修改、增加或者刪除數據時，就要把過程反過來了，也就是反序列化，把客戶端提交的json格式的數據反序列化。

下面的代碼把json數據流解析成Python自帶的數據格式，便於我們后台Django的操作：

>>> from django.utils.six import BytesIO
>>> stream = BytesIO(content)
>>> data = JSONParser().parse(stream)

 

檢查並保存數據：

>>> serializer = SnippetSerializer(data=data)
>>> serializer.is_valid()
True
>>> serializer.validated_data
OrderedDict([('title', ''), ('code', 'print "hello, world"'), ('linenos',
 False), ('language', 'python'), ('style', 'friendly')])
>>> serializer.save()
<Snippet: Snippet object>

 

這個時候查看數據庫又多了一條數據：

 

---

使用 ModelSerializers

在上面的SnippetSerializer類中，我們繼承的是serializers.Serializer類，可以看到SnippetSerializer類中有很多代碼其實是和models.py中的Snippet模型類似一樣的，所以這里我們可以改進一下。就像在Django中提供了Form類和ModelForm類一樣，django-rest-framework為我們提供了Serializer類和ModelSerializer類。利用它可以讓我們的代碼簡潔很多，修改serializers.py：

class SnippetSerializer(serializers.ModelSerializer):
    class Meta:
        model = Snippet
        fields = ('id', 'title', 'code', 'linenos', 'language', 'style')

 

我們可以通過在shell中的打印來檢查序列化器實例中的所有字段：

>>> from snippets.serializers import SnippetSerializer
>>> serializer = SnippetSerializer()
>>> print(repr(serializer))

 

打印后出現的效果如下（language非常長，只截取了一部分）： 

（兩個圖是同一次打印的，太長了分開截圖）

在我們新的SnippetSerializer類中，可以發現和之前的對比代碼少了很多，這里體現了ModelSerializer 類的快捷：

- 自動確定字段

- create和update方法的簡單默認實現

---

編寫常規的Django視圖

接下來要做的就是使用我們的新的Serializer類編寫一些API視圖。編輯snippets/views.py：

from django.http import HttpResponse, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from rest_framework.renderers import JSONRenderer
from rest_framework.parsers import JSONParser
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer


# Create your views here.
@csrf_exempt
def snippet_list(request):
    """
    列出所有已經存在的snippet或者創建一個新的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_exempt
def snippet_detail(request, pk):
    """
    檢索查看、更新或者刪除一個代碼段
    """
    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)

 

上面的代碼都比較好理解，定義了不同http動作時后台不同的操作，在這里也體現了restful API的理念。

需要注意的是記得添加@csrf_exempt修飾器。

為了讓視圖函數被調用，那當然需要設計一下url了，這里的處理和平時Django開發時是一樣的。首先創建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),
]

 

接着就是tutorial/urls.py，代碼如下：

from django.conf.urls import url, include

urlpatterns = [
    url(r'^', include('snippets.urls')),
]

 

---

對API進行測試

完成了上面那些工作后，就可以開始測試了，退出shell模式並啟動服務器，根據我們剛才設計的url發送請求，需要先安裝httpie模塊：

pip install httpie

 

然后在命令行窗口訪問，效果如下： 

 也可以訪問指定id的數據： 

 當然了，也可以直接在瀏覽器查看，直接輸入那個URL就可以了： 

到這里，也就實現了一個功能，當其他人訪問這個URL時返回json格式的數據給他使用。

在下一篇文章將講解處理請求和響應，多謝支持~

本文地址：http://www.cnblogs.com/zivwong/p/7417989.html
作者博客：ziv
歡迎轉載，請在明顯位置給出出處及鏈接