![4929bba5d07e996a51559bab0e6e97e9.png](https://i-blog.csdnimg.cn/blog_migrate/9eee26c2641d4bef0b12ea2c292bd818.jpeg)
欢迎关注我的个人微信公众号,不定期AI论文解读与开发技术分享
![8bc63120ad7188a7fbfa045c65c2de2f.png](https://i-blog.csdnimg.cn/blog_migrate/d1c1d56d3bd197ce9c58ce09a4759f43.jpeg)
关于RESTful API
现在,在开发过程中,经常会听到前后端分离这个技术名词,顾名思义,就是前台的开发和后台分离开来。这个技术方案的实现就是要借助API。API简单的来说就是开发人员提供编程接口被其他人来调用,他们被调用之后会返回数据供其使用。API的类型有多种,但是现在比较流行且使用的就是本文所要说的RESTful API。
RESTful API的起源
REST这个词,是Roy Thomas Fielding在他2000年的博士论文中提出的。
Fielding将他对互联网软件的架构原则,定名为REST,即Representational State Transfer的缩写。我对这个词组的翻译是"表现层状态转化"。要理解RESTful架构,最好的方法就是去理解Representational State Transfer这个词组到底是什么意思,它的每一个词代表了什么涵义。
资源(Resources)
REST的名称"表现层状态转化"中,省略了主语。"表现层"其实指的是"资源"(Resources)的"表现层"。
所谓"资源",就是网络上的一个实体,或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务,总之就是一个具体的实在。你可以用一个URI(统一资源定位符)指向它,每种资源对应一个特定的URI。要获取这个资源,访问它的URI就可以,因此URI就成了每一个资源的地址或独一无二的识别符。
所谓"上网",就是与互联网上一系列的"资源"互动,调用它的URI。
表现层(Representation)
"资源"是一种信息实体,它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式,叫做它的"表现层"(Representation)。
比如,文本可以用txt格式表现,也可以用HTML格式、XML格式、JSON格式表现,甚至可以采用二进制格式;图片可以用JPG格式表现,也可以用PNG格式表现。
URI只代表资源的实体,不代表它的形式。严格地说,有些网址最后的".html"后缀名是不必要的,因为这个后缀名表示格式,属于"表现层"范畴,而URI应该只代表"资源"的位置。它的具体表现形式,应该在HTTP请求的头信息中用Accept和Content-Type字段指定,这两个字段才是对"表现层"的描述。
状态转化(State Transfer)
访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必涉及到数据和状态的变化。
互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。而这种转化是建立在表现层之上的,所以就是"表现层状态转化"。
客户端用到的手段,只能是HTTP协议。具体来说,就是HTTP协议里面,四个表示操作方式的动词:GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源。
小结
总结一下什么是RESTful架构:
(1)每一个URI代表一种资源;
(2)客户端和服务器之间,传递这种资源的某种表现层;
(3)客户端通过四个HTTP动词,对服务器端资源进行操作,实现"表现层状态转化"。
Django RESTful API
搭建开发环境
pip install django
pip install djangorestframework
pip install pygments # 用来实现代码高亮
开始
首先创建一个名为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自带的那个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()时如何创建或修改完整的实例。
使用序列化器
首先进入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()
这时候查看数据库就会发现相关表中已经多了两行数据,就是我们刚才创建的数据:
![9143562cc7ef05fa6a8738264e46e062.png](https://i-blog.csdnimg.cn/blog_migrate/fcb9e3bbee5641a25fd486a021c556af.jpeg)
也可以继续在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格式的数据反序列化。
>>> 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))
![026e5100f916bc2a4b7ea2a463fc1d61.png](https://i-blog.csdnimg.cn/blog_migrate/b9978cd4efbcd7f5ea4b1f5f68010a4f.jpeg)
在我们新的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)
需要注意的是记得添加@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进行测试。