Django REST framework 框架（一）

Django REST framework 框架

一、Web应用模式

• 前后端不分离
• 前后端分离

1.前后端不分离

在前后端不分离的应用模式中，前端看到的效果都是由后端控制的，由后端渲染页面或者重定向，也就是后端需要控制前端的展示，前端与后端的耦合度很高。

这种应用模式比较适合纯网页应用，但是当后端对接App时，App可能并不需要后端返回一个HTML的网页，而仅仅是数据本身，所以后端原本返回网页的接口不再适用于前端App应用，为了对接App后端还需要再开发一套接口。

2.前后端分离

在前后端分离的应用模式中，后端仅仅返回前端需要的数据，而不再渲染HTML页面，不再控制前端的效果。至于前端用户看到什么样的效果，从后端请求的数据如何加载到前端中，都由前端自己决定，网页有网页的处理方式，App也有App的处理方式，但无论哪种前端，所需要的数据基本相同，后端仅需要开发一套逻辑对外提供数据即可，前端与后端的耦合度相对较低。

在前后端分离的应用模式中，我们通常将后端开发的每一个视图都称为一个接口，或者API，前端通过访问接口来对数据进行增删改查。

二、认识RESTful

在前后端分离的应用模式里，后端API接口如何定义?

例如对于后端数据库中保存了商品的信息，前端可能需要对数据进行增删改查，那相应的每一个操作都需要后端提供一个API接口：

1.POST /add-goods 增加商品

2.POST /delete-goods 删除商品

3.POST /update-goods 修改商品

4.GET /get-goods 查询商品

对于接口的请求方式和url，每个后端开发人员可能都有自己的定义方式。

是否存在一种统一的定义方式，被广大开发人员接受认可呢？

这就是被普遍猜用的API的RESTful设计风格。

REST即Representational State Transfer的缩写，维基百科称为“具象状态传输“，国内大部分人理解为”表现层状态转化“。

RESTful是一种开发理念。维基百科说，REST是设计风格而不是标准。REST描述的是在网络中client和server的一种交互形式；REST本身不实用，实用的是如何设计RESTful API（REST风格的网络接口），一种万维网软件架构风格。

REST的特点：

• url简洁，将参数通过url传到服务器，而传统的url比较啰嗦，而且现实中浏览器地址栏会出现一大串字符串。但是采用REST的风格就会简洁很多，典型的就是url的短化转换。

三、RESTful设计方法

请求相关

1.域名

应该尽量将API部署在专用域名下

https://api.example.com

如果确定API很简单，不会有进一步扩展，也可以考虑放在主域名下

https://example.org/api/

2.版本（Versioning)

应该将API的版本号放入URL中

http://www.example.com/app/1.0/foo
    
http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo    

另一种做法是，将版本号放在HTTP头信息中，但不如放在URL中方便和值观。Github采用这种做法。

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URL。版本号可以在HTTP请求头信息的Accept字段中进行区分：

Accept: vnd.example-com.foo-json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

3.路径（Endpoint）

路径又成为终点，表示API的具体网址，每个网址代表一种资源（resource）

1）资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表名对应。

对于一个简单的结构，应该始终使用名词。此外，利用HTTP方法可以分离网址中的资源名称的操作

GET /products :将返回所有产品清单
POST /products ：将产品新建到集合
GET /products/4 ：将获取产品 4
PUT /products/4 ：将更新产品 4    

2）API中的名词应该使用复数。无论是子资源还是所有资源。

获取单个产品：http://127.0.0.1:8000/AppName/rest/products/1
获取所有产品：http://127.0.0.1:8000/AppName/rest/products

4.HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面四个（括号里是对应的SQL命令）

• GET（SELECT）：从服务器取出资源（一个或者多个）
• POST（CREATE）：在服务器中新建一个资源
• PUT（UPDATE）：在服务器中更新资源（客户端提供改变资源的完整路径）
• DELETE（DELETE）：从服务器中删除资源

还有三个不常用的HTTP动词。

• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）
• HEAD：获取资源的元数据
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

下面是一些例子：

GET /zoos：列出所有的动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

5.过滤信息（Filtering）

如果记录数量很多，服务器不可能将他们全部都返回给用户，API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置
?page=2&per_page=100：指定页数，以及每页的记录数
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL路径偶尔有重复。比如GET /zoos/ID/animals 与 GET /animals?zoo_id = ID的含义是相同的。

响应相关

1.状态码（这里只列举一些常用的常态码，具体详细信息大家可以百度）

服务器向用户返回的状态码和提示信息，常用的有以下一些（方括口号中是该状态码对应的HTTP动词）

• 200 OK - [GET]：服务器成功返回用户请求的数据
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
• 204 NO CONTENT - [DELETE]：用户删除数据成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
• 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
• 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
• 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

2.错误处理（Error handling）

如果状态码是4xx，服务器就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
    error:'Invalid API key'   
}

3.返回结果

针对不同操作，服务器向用户返回的结果应该符合一下规范。

• GET /collection：返回资源对象的列表或者元组
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

4.超媒体（Hypermedia API）

RESTful API最好做到Hypermedia（即返回结果中提供链接，连向其他API方法），使用户不查文档的情况下，也知道下一步应该做什么。 比如Github的API就是这中设计。

5.服务器返回的数据格式

尽量使用JSON，避免使用XML。

使用Django开发REST API

我们以在我之前发布的文章作品中的Django框架使用的图书英雄案例来写一套支出图书信息增删改查的REST API接口，来理解REST API的开发。

# views.py

from django.views.generic import View
from book.models import BookInfo
from django.http import JsonResponse,HttpResponse
import json

# Create your views here.
class BookListView(View):
    """
    查询所有图书、增加图书
    """
    def get(self, request):
        """
        查询所有图书
        路由：GET /books/
        """
        queryset = BookInfo.objects.all()
        book_list = []
        for book in queryset:
            book_list.append({
                'id': book.id,
                'name': book.name,
                'pub_date': book.pub_date
            })
        return JsonResponse(book_list, safe=False)

    def post(self, request):
        """
        新增图书
        路由：POST /books/
        """
        json_bytes = request.body
        json_str = json_bytes.decode()
        book_dict = json.loads(json_str)

        # 此处详细的校验参数省略

        book = BookInfo.objects.create(
            name=book_dict.get('name'),
            pub_date=book_dict.get('pub_date')
        )

        return JsonResponse({
            'id': book.id,
            'name': book.name,
            'pub_date': book.pub_date
        },safe=False)

class BookDetailView(View):
    """
    获取单个图书信息
    修改图书信息
    删除图书
    """
    def get(self, request, id):
        """
        获取单个图书信息
        路由： GET  /books//
        """
        try:
            book = BookInfo.objects.get(id=id)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        return JsonResponse({
            'id': book.id,
            'name': book.name,
            'pub_date': book.pub_date
        })

    def put(self, request, id):
        """
        修改图书信息
        路由： PUT  /books/
        """
        try:
            book = BookInfo.objects.get(id=id)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        json_bytes = request.body
        json_str = json_bytes.decode()
        book_dict = json.loads(json_str)

        # 此处详细的校验参数省略

        book.name = book_dict.get('name')
        book.pub_date = book_dict.get('pub_date')
        book.save()

        return JsonResponse({
            'id': book.id,
            'name': book.name,
            'pub_date': book.pub_date
        })

    def delete(self, request, id):
        """
        删除图书
        路由： DELETE /books//
        """
        try:
            book = BookInfo.objects.get(id=id)
        except BookInfo.DoesNotExist:
            return HttpResponse(status=404)

        book.delete()

        return HttpResponse(status=204)

urlpatterns = [
    url(r'^books/$',views.BookListView.as_view()),
    url(r'^books/(?P\d+)$',views.BookDetailView.as_view()),
]

明确REST接口开发的核心任务

分析一下刚才做的小案例，是不是可以发现，在开发REST API接口的时候，视图中做的最主要有三件事：

• 将请求的数据（json）转换为模型类对象
• 对数据库进行操作
• 将模型类对象转换为响应的数据（json）

序列化Serialization

维基百科中对序列化的定义太复杂了，不易理解。

所以简而言之，我们可以将序列化理解为：

将程序中的一个数据结构类型转换为其他格式（字典、JSON、XML等），例如将Django中的模型类对象转换为JSON格式的字符串的过程，我们就可以称之为序列化。

反之，将其他格式（字典、JSON、XML等）转换为程序中的数据，例如将JSON字符串转换为Django中的模型类对象的过程，我们就可以称之为反序列化。

总结：

在开发REST API接口的时候，我们在视图中做的最核心的事情就是：

• 将前端发送的数据反序列化为模型类对象，操作数据库
• 将模型类对象序列化为前端需要的格式，并且返回

Django REST framework

1.在序列化与反序列化的时候，虽然操作的数据有些不同，但是执行的过程却是相似的，也就是说这部分代码是可以复用简化编写的。

2.在开发REST API的视图中，虽然每个视图操作的数据不同，但是对于增、删、改、查的实现流程基本套路是一样的，所以这部分代码也是可以复用简化编写的：

• 增：校验请求数据 -> 执行反序列化过程 ->保存数据库 ->将保存的对象序列化并返回
• 删：判断要删除的数据是否存在 -> 执行数据库删除
• 改：判断要修改的数据是否存在 ->校验请求的数据 -> 执行反序列化过程 ->保存数据库 ->将保存的对象序列化并返回
• 查：查询数据库 -> 将数据序列化并返回

Django REST framework 可以帮助我们简化上述两部分代码的编写，大大提高REST API的开发速度

Django REST framework框架是一个用于构建Web API 的强大而又灵活的工具。

通常简称为DRF框架或者REST framework。

DRF框架是建立在Django框架的基础之上的，由Tom Christie 大牛二次开发的开源项目。

特点

• 提供了定义序列化器Serializer的方法，可以快速根据 Django ORM 或者其它库自动序列化/反序列化；
• 提供了丰富的类视图、Mixin扩展类，简化视图的编写；
• 丰富的定制层级：函数视图、类视图、视图集合到自动生成 API，满足各种需要；
• 多种身份认证和权限认证方式的支持；
• 内置了限流系统；
• 直观的 API web 界面；
• 可扩展性，插件丰富

DRF 网页界面开发

1.创建序列化器

在子应用中创建serializer.py文件

class BookInfoSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = "__all__"
     

• model指明该序列化器处理的数据字段是从模型类BookInfo参考生成
• fields指明该序列化器包含模型类中的哪些字段，all表示所有字段

2.编写视图

在子应用的views.py文件中创建视图

class BookInfoViewSet(ModelViewSet):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer

• quertset指明该视图集在查询数据的时候使用查询集
• serializer_class指明该视图的进行序列化或反序列化的时候使用的序列化器

3.定义路由

在子应用的urls.py文件中定义路由信息

router = DefaultRouter()  # 可以处理视图的路由器
router.register(r'books',views.BookInfoViewSet,base_name="") # 向路由中注册视图集

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

4.运行测试

运行当前程序

python manage.py runserver

在浏览器中输入网址127.0.0.1:8000，可以看到DRF提供的API Web浏览页面：

接下来就可以通过这个页面来对图书信息进行增删改查的操作了。

Srializer字段和选项

1.定义Serializer类

Django REST framework中的Serializer使用类来定义，须继承自rest_framework.serializers.Serializer。

例如，我们已经有了一个数据库模型类BookInfo。

class BookInfo(models.Model):
    name = models.CharField(max_length=20, verbose_name='名称') #图书名称
    pub_date = models.DateField(verbose_name='发布日期') #发布日期
    readcount = models.IntegerField(default=0, verbose_name='阅读量') #阅读量
    commentcount = models.IntegerField(default=0, verbose_name='评论量') #评论量
    is_delete = models.BooleanField(default=False, verbose_name='逻辑删除') #逻辑删除
    image = models.ImageField(upload_to='book/', verbose_name='图片', null=True)
    #元类信息 : 修改表名
    class Meta:
        db_table = 'bookinfo' # 指明数据库表名
        verbose_name = '图书'  # 在admin站点中显示的名称
        verbose_name_plural = verbose_name  # 显示的复数名称

    def __str__(self):
        """定义每个数据对象的显示信息"""
        return self.name

我们想为这个模型类提供一个序列化器，可以定义如下：

class BookInfoSerializer(serializers.Serializer):
    
    '''图书信息序列化器'''
    id = serializers.IntegerField(label='ID', read_only=True)
    name = serializers.CharField(label='名称', max_length=20)
    pub_date = serializers.DateField(label='发布日期', required=False)
    readcount = serializers.IntegerField(label='阅读量', required=False)
    commentcount = serializers.IntegerField(label='评论量', required=False)
    image = serializers.ImageField(label='图片', required=False)

注意：serializer不是只能为数据库模型类定义，它也可以为非数据库模型类的数据定义。serializer是独立于数据库之外的存在。

2. 字段与选项

常用字段类型：

字段	字段构造方式
BooleanField	BooleanField()
NullBooleanField	NullBooleanField()
CharField	CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)
EmailField	EmailField(max_length=None, min_length=None, allow_blank=False)
RegexField	RegexField(regex, max_length=None, min_length=None, allow_blank=False)
SlugField	SlugField(maxlength=50, min_length=None, allow_blank=False) 正则字段，验证正则模式 [a-zA-Z0-9-]+
URLField	URLField(max_length=200, min_length=None, allow_blank=False)
UUIDField	UUIDField(format=‘hex_verbose’) format: 1)'hex_verbose'如"5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 2）'hex'如"5ce0e9a55ffa654bcee01238041fb31a" 3）'int'- 如:"123456789012312313134124512351145145114" 4）'urn'如:"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
IPAddressField	IPAddressField(protocol=‘both’, unpack_ipv4=False, **options)
IntegerField	IntegerField(max_value=None, min_value=None)
FloatField	FloatField(max_value=None, min_value=None)
DecimalField	DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None) max_digits: 最多位数 decimal_palces: 小数点位置
DateTimeField	DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None)
DateField	DateField(format=api_settings.DATE_FORMAT, input_formats=None)
TimeField	TimeField(format=api_settings.TIME_FORMAT, input_formats=None)
DurationField	DurationField()
ChoiceField	ChoiceField(choices) choices与Django的用法相同
MultipleChoiceField	MultipleChoiceField(choices)
FileField	FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ImageField	ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ListField	ListField(child=, min_length=None, max_length=None)
DictField	DictField(child=)

选项参数：

参数名称	作用
max_length	最大长度
min_lenght	最小长度
allow_blank	是否允许为空
trim_whitespace	是否截断空白字符
max_value	最大值
min_value	最小值

通用参数：

参数名称	说明
read_only	表明该字段仅用于序列化输出，默认False
write_only	表明该字段仅用于反序列化输入，默认False
required	表明该字段在反序列化时必须输入，默认True
default	反序列化时使用的默认值
allow_null	表明该字段是否允许传入None，默认False
validators	该字段使用的验证器
error_messages	包含错误编号与错误信息的字典
label	用于HTML展示API页面时，显示的字段名称
help_text	用于HTML展示API页面时，显示的字段帮助提示信息

3.创建Serializer对象

定义好Serializer类之后，我们就可以实例化Serializer对象了。

Serializer的构造方法如下：

Serializer(instance=None, data=empty, **kwarg)

说明：

1）用于序列化时，将模型类对象传入instance参数

2）用于反序列化的时候，将被反序列化的数据传入data

3）除了instance和data参数外，在构造Serializer对象的时候，还可以通过context参数额外添加数据，并且通过Serializer对象的context属性调用