RESTful笔记-1

1. RESTful设计方法和规范

• 常用的 HTTP 动词有下面 4 个（括号里是对应的 SQL 命令）。
  GET（SELECT）：从服务器取出资源（一项或多项）
  POST（CREATE）：在服务器新建一个资源
  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）
  DELETE（DELETE）：从服务器删除资源
  PATCH（UPDATE）：在服务器更新(更新)资源（客户端提供改变的属性）
  HEAD：获取资源的元数
  OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

2. 过滤信息（Filtering）

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=score&order=asc：指定返回结果按照学生的成绩（score）正序（asc）排列顺序。

3. 状态码

• 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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

4. 返回结果

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

5. 数据格式

• 服务器返回的数据格式，应该尽量使用 JSON，避免使用 XML

# JSON
{"name":"XiaoMing",
"age":"12",
"gender":"male"}

# XML
<?xml version="1.0" encoding="UTF-8" ?>
	<name>XiaoMing</name>
	<age>12</age>
	<gender>male</gender>
	

6. 序列化和反序列化

• 序列化：
  - 按照前端需求，在数据库检索相应数据，转化为前端所需的数据形式（如 JSON），发给前端
  - 将程序中的一个数据结构类型转换为其他格式（字典、JSON、XML等），例如将 Django 中的模型类对象转换为 JSON 字符串的过程
• 反序列化：
  - 将前端发来的数据，按照数据库的要求，转化为数据库所能接受的形式，存入数据库
  - 将其他格式（字典、JSON、XML等）转换为程序中的数据，例如将JSON字符串转换为Django中的模型类对象的过程
• 案例：

>> import json
# 序列化(将python内部的字典结构转化为JSON字符串)
>> student = {'name': 'Xiao Ming', 'age': 12} # 未序列化前，数据是python字典形式
>> json.dumps(student)
# 输出结果
'{"name": "Xiao Ming", "age": 12}' # 经过序列化，数据已成为 python 字符串形式

# 反序列化(将JSON字符串转化为python内部的字典结构)
>> student_str = '{"name": "Xiao Ming", "age": 12}' # 未返回序列化前，数据类型为python字符串
>> json.loads(student_str)
# 输出结果
{'name': 'Xiao Ming', 'age': 12} # 序列化之后，数据类型为python字典形式

• 总结：
  - 将数据库数据序列化为前端所需要的格式，并返回
  - 将前端发送的数据反序列化为模型类对象，并保存到数据库中

7. 构建RESTful Web API

• 安装 Django REST framework
• 创建工程和应用
• 注册rest_framework应用：在 settings.py 的 INSTALLED_APPS 中注册

# settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
]

• 创建、迁移模型，并添加数据

# models.py

from django.db import models

class StudentsInfo(models.Model):
		'''
		学生信息模型
		'''

• 终端中运行命令以迁移模型

python manage.py makemigrations
python migrate

8. 创建序列化器

• 在 Restful Web API 中，序列化器相当于客户端和数据库之间数据对接的桥梁，它可将服务器中的数据，序列化为客户端可解析的数据形式，相反，也可将客户端提供的数据，反序列化为符合数据库要求的数据形式

# serializers.py

from rest_framework import serializers
from AppDemo.models import StudentsModel

class StudentsSerializer(serializers.ModelSerializer):

    class Meta:
        # 对StudentsModel进行序列化
        model = StudentsModel
        # __all__表示对 StudentsModel 中所有字段序列化进行序列化
        fields = '__all__'
        # fileds = ('')
        # exclude = ('')
        read_only_fields = （'id')

• model ：指明该序列化器处理的数据字段从模型类 Client 参考生成
• fields ：指明该序列化器包含模型类中的哪些字段，'all’指明包含所有字段
• exclude：用来指定哪些字段不需要进行序列化
• read_only_fields：指明只读字段

9. 编写视图

• 在 Restful Web API 中，视图扮演的角色是数据处理器，例如，客户端需要获取一个学生一次期末考试后各科成绩的平均值，而数据库中仅存了各科的成绩，这时，就需要视图对数据处理，根据各科成绩求出平均值后返回给客户端

# views.py

from rest_framework import viewsets
from AppDemo.models import StudentsModel
from AppDemo.serializers import StudentsSerializer

class StudentsViewSet(viewsets.ModelViewSet):

    queryset = StudentsModel.objects.all()
    # 使用上一步创建的StudentsSerializer对模型进行序列化
    serializer_class = StudentsSerializer

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

10. 定义路由

• 路由是用来定义 RESTful Web API 不同接口所对应的不同路径地址

from django.contrib import admin
from django.urls import path, include
from rest_framework import routers

from AppDemo.views import StudentsViewSet

router = routers.DefaultRouter() # 创建路由器
router.register(r'students', StudentsViewSet)	# 在路由器中注册视图集路由地址

urlpatterns = [
  	# 拼接路由路径
    path('api/', include(router.urls)),
]