1、DRF实战总结：DRF特点、序列化与RESTful API规范

Django这种基于MVC开发模式的传统框架，非常适合开发基于PC的传统网站，因为它同时包括了后端的开发(逻辑层、数据库层) 和前端的开发(如模板语言、样式)。现代网络应用Web APP或大型网站一般是一个后台，然后对应各种客户端(iOS, android, 浏览器)。由于客户端的开发语言与后台的开发语言经常不一样，这时需要后台能够提供可以跨平台跨语言的一种标准的资源或数据(如json或xml)供前后端沟通，这就是Web API(网络应用程序接口)的作用了。

Django REST Framework介绍与特点

Django REST framework是一个强大且灵活的工具包，用以构建Web APIs。Django的未来与Web开发未来发展趋势紧密相关。Django本身并不是为了开发符合REST规范的Web API而设计, 不过借助Django REST Framework (DRF)这个神器可以快速开发出优秀而且规范的Web API来。Django REST framework 给Django提供了用于构建Web API 的强大而灵活的工具包, 包括序列化器、认证、权限、分页、过滤和限流。

DRF特点：

1. 提供了定义序列化器Serializer的方法,可以快速根据 Django ORM 或者其他库自动序列化/反序列化；
2. 提供了丰富的类视图和Mixin扩展类，可以进一步简化视图的编写；
3. 多种身份认证和权限认证方式的支持；
4. 内置了限流系统；
5. 直观的API Web界面；
6. 可扩展性, 插件丰富；
7. 完备的文档以及良好的社区支持；
8. 同时支持ORM和非ORM数据源的序列化；
9. 可以配置各个环节，若无需更多强大的特性，使用一般基于类（function-based）的视图（views）即可。

Django REST Framework的安装

Django REST framework (DRF)是基于Django实现的一个RESTful风格API框架，能够帮助快速开发RESTful风格的API。

使用pip安装DRF：pip install djangorestframework

如果想要获取一个图形化的页面来操作API，需要将 rest_framework 注册到项目的INSTALL_APPS中，如下所示：

INSTALLED_APPS = [
    # 默认APP
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 新安装第三方APP
    'rest_framework',
    'rest_framework_mongoengine',
    # 将自己新建的APP应用（people）添加到 settings.py中的INSTALLED_APPS中，告诉Django有这么一个应用
    ……
]

安装和注册好DRF，但在正式使用它开发API前还需要了解两件事情。什么是数据的序列化(Serialization)以及什么是RESTful规范的API, 这对于理解DRF中的序列化serializers类和每个API端点对应的url设计至关重要。

序列化基础知识

每种编程语言都有各自的数据类型, 将属于自己语言的数据类型或对象转换为可通过网络传输或可以存储到本地磁盘的数据格式（如：XML、JSON或特定格式的字节串）的过程称为序列化(seralization)；反之则称为反序列化。API开发的本质就是各种后端语言的自己的数据类型序列化为通用的可读可传输的数据格式，比如常见的JSON类型数据。

Python数据序列化

Python自带json模块的dumps方法可以将python常用数据格式（比如列表或字典)转化为json格式,如下所示。注意到了吗? 生成的json格式数据外面都加了单引号，这说明dict类型数据已经转化成了json字符串。

import json

infos = {"name": "SteveRocket", "language": "Python", "version": 3.11}
dump_infos = json.dumps(infos)
print(dump_infos, type(dump_infos))

输出：{"name": "SteveRocket", "language": "Python", "version": 3.11} 

Django查询集序列化

Django还有自己专属的数据类型比如查询集QuerySet和ValueQuerySet类型数据，还提供了自带的serializers类。使用Django自带的serializers类也可以轻易将QuerySet格式的数据转化为json格式。

# Django Queryset数据 to Json
from django.core import serializers
from drf_pro.models import SerializerDemo

peoples = serializers.serialize("json", SerializerDemo.objects.all())
peoples2 = serializers.serialize("json", SerializerDemo.objects.all(), fields=("name", "id"))
people = serializers.serialize("json", SerializerDemo.objects.filter(name="SteveRocket"))

有时候只需要查询结果集的部分字段，可以使用values('字段名','字段名2')来要求返回所需要的数据，可以提升些性能，但是返回来的结果需要先转换成列表格式，再用 json.dumps()方法序列化成json格式。

import json
from django.core.serializers.json import DjangoJSONEncoder
value_query_set = SerializerDemo.objects.filter(name="SteveRocket").values("age", "description")
people_desc = json.dumps(list(value_query_set), cls=DjangoJSONEncoder)

尽管Django自带的serializers类也能将Django的查询集QuerySet序列化成json格式数据，Django REST Framework才是真正需要的序列化工具。与django自带的serializers类相比，DRF的序列化器更强大，可以根据模型生成序列化器，还能对客户端发送过来的数据进行验证。

RESTful API

REST ful是目前最流行的API设计规范，用于Web数据接口的设计。是Rest式的接口，REST与技术无关，它代表的是一种软件架构风格。

REST是REpresentational State Transfer三个单词的缩写，，中文的含义是: "表征状态转移" 或 "表现层状态转化"。由Roy Fielding于2000年论文中提出。简单来说，就是用URI表示资源，用HTTP方法(GET, POST, PUT, DELETE)表征对这些资源进行增删查改的操作。

是基于HTTP、URI、XML、JSON等标准和协议，支持轻量级、跨平台、跨语言的架构设计。

RESTful API 可以通过一套统一的接口为所有web相关提供服务，实现前后端分离。

RESTful API原则

1. 每一个URI代表一种资源。
2. 同一种资源有多种表现形式(xml/json)。
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。

如果要想编写的API被称为RESTful api，只要遵循其规定的约束即可。

为什么所有的操作都是无状态的?

http请求本身是无状态的，它是基于 client-server 架构，客户端向服务器端发的每一次请求都必须带有充分的信息能够让服务器端识别到，请求的一些信息通常会包含在URL的查询参数、header或请求体中，服务器端能够根据请求的各种参数, 不需要保存客户端的状态, 直接将数据返回给客户端。无状态的优点是：可以大大提高服务器端的健状性和可扩展性。

客户端可以通过token来标识会话状态。从而可以让该用户一直保持登录状态。

RESTful API规范

REST接口约束定义为: 资源识别；请求动作；响应信息; 它表示通过uri表示出要操作的资源，通过请求动作(http method)标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。

协议、域名和版本

尽量使用https协议，使用专属域名来提供API服务。API版本可以放在URL里面，也可以用HTTP的header进行内容协商，如下所示：

https://api.example.com/v1
https://www.example.com/api/v1

uri(统一资源标识符)

在RESTful架构中，每个网址代表一种资源（resource），这个网络地址就是uri (uniform resource identifier), 有时也被称为URL (uniform resource locator)。 因为URI对应一种资源，所以里面不能有动词，只能有名词。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数形式。

https://api.example.com/v1/users # 用户列表资源地址
https://api.example.com/v1/users/{id} # 用户id=5对应资源。注意：这里是users/5，而不是user/5
https://api.example.com/v1/users/{id}/articles # 用户id=5发表的文章列表

如果需要对一个用户信息进行编辑或删除，一个传统Django开发者可能将URL写成如下所示：

https://api.example.com/v1/users/{id}/edit/ # 编辑用户
https://api.example.com/v1/users/{id}/delete/ # 删除用户

上面URL设计其实是不符合RESTful规范的。一个 URI就应该是一个资源，本身不能包含任何动作 (action)。REST的规范是资源的URI地址是固定不变的，对同一资源应使用不同的HTTP请求方法进行不同的操作，比如常见的增删查改。

[POST]    https://api.example.com/v1/users   // 新增
[GET]     https://api.example.com/v1/users/1 // 查询
[PATCH]   https://api.example.com/v1/users/1 // 更新
[PUT]     https://api.example.com/v1/users/1 // 覆盖，全部更新
[DELETE]  https://api.example.com/v1/users/1 // 删除

有时候URL比较长，可能由多个单词组成，建议使用中划线”-“分割，而不是下划线”_“作为分隔符，另外每个url的结尾不能加斜线”/”。

https://api.example.com/v1/user-management/users/{id} # 好
https://api.example.com/v1/user_management/users/{id} # 不好
https://api.example.com/v1/user-management/users/{id}/ # 不好

 

参数命名规范

参数推荐采用下划线命名的方式。

http://127.0.0.1/api/today_login               // 获取今天登录的用户。

http://127.0.0.1/api/today_login&sort=login_desc // 获取今天登录的用户、登录时间降序排序。

HTTP请求方法

常用的HTTP请求方法有下面五个（括号里是对应的SQL命令)，每个方法对应一个操作。客户端在消费服务器提供的API服务时不仅要指定请求地址，还需指定请求方法。

	GET（SELECT）：查询；从服务器取出资源（一项或多项）。
	POST（CREATE）：新增;在服务器新建一个资源。
	PUT（UPDATE）：更新;在服务器更新资源（客户端提供改变后的完整资源）。
	PATCH（UPDATE）：更新；在服务器更新资源（客户端提供改变的属性）。
	DELETE（DELETE）：删除;从服务器删除资源。

另外还有两个不常用方法HEAD和OPTIONS，HEAD和GET本质是一样的，区别在于：

HEAD不含有呈现数据，而仅仅是HTTP头信息，请求的是资源的元数据，比如一张照片的元数据则可能包含了，照片拍摄的设备，地点，时间等。服务器一般将对应资源的元数据置于响应的报头集合返回给客户端，这样的响应一般不具有主体部分。

OPTIONS极少使用，它主要用于获取当前URL所支持的方法，发送一种“探测”请求以确定针对某个目标地址的请求必须具有怎样的约束（比如应该采用怎样的HTTP方法以及自定义的请求报头），然后根据其约束发送真正的请求。

HTTP状态码（Status Codes）

服务器在处理客户端请求后还应向用户返回响应的状态码和提示信息，DRF给出Respone时可以指定各种各样状态码，很容易使用，常见的有以下一些状态码。

1xx: 信息，请求收到了，继续处理。

2xx: 代表成功. 行为被成功地接收、理解及采纳。

3xx: 重定向。

4xx: 客户端错误，请求包含语法错误或请求无法实现。

5xx: 服务器端错误。

2xx 状态码

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功

 

4xx状态码

400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
405：Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
415: Unsupported Media Type: 客户端要求的返回格式不支持，比如，API只能返回JSON格式，但是客户端要求返回XML格式。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
429：Too Many Requests: 客户端的请求次数超过限额。

 

5xx 状态码

500 INTERNAL SERVER ERROR - [*]：服务器发生错误
502：网关错误。
503: Service Unavailable 服务器端当前无法处理请求。
504：网关超时。

 

过滤信息（filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。符合RESTful规范的API应该支持过滤，DRF与django-filter可以轻松实现过滤。下面是一些常见的通过参数过滤的方式。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个姓名排序，以及排序顺序。
?user_type_id=1：指定筛选条件，比如用户类型。

统一返回数据格式

Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。比如，当用户向127.0.0.1的根目录发出请求，会得到这样一个文档，DRF支持HyperLinkedModel，很容易实现这点。

{
"link": {
       "rel":   "collection https://127.0.0.1/zoos",
       "href":  "https://api.example.com/zoos",
       "title": "List of zoos",
       "type":  "application/vnd.yourformat+json"
}
}

 

返回的数据格式

RESTful规范中的请求应该返回统一的数据格式。对于返回的数据，一般会包含如下字段:

1) code: http响应的状态码。

2) status: 包含文本, 比如：'success'(成功), 'fail'(失败), 'error'(异常)

HTTP状态响应码在500-599之间为 'fail'; 在400-499之间为 'error', 其他一般都为 'success'。对于响应状态码为 1xx, 2xx, 3xx 这样的可以根据实际情况可要可不要。

当status的值为 'fail' 或 'error'时，需要添加 message 字段，用于显示错误信息。

3) data: 当请求成功的时候, 返回的数据信息。但是当状态值为 'fail' 或 'error' 时，data仅仅包含错误原因或异常信息等。

响应成功的示例：

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

响应失败的示例：

{
    "code": 401,
    "status": "error",
    "message": '用户没有权限',
    "data": null
}

参考资料

• 官网：https://www.django-rest-framework.org/
• 中文文档：主页 - Django REST framework中文站点
• https://github.com/encode/django-rest-framework/tree/master
• Home - Django REST framework

输入才有输出，吸收才能吐纳。——码字不易