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
欢迎转载，请在明显位置给出出处及链接