Title(EN): Django REST Framework Learning Notes (1): Hello RESTful API
Author: dog2

前后端分离是大势所趋

按

最近在学习Django Rest Framework，官方教程较短，看完感觉并没有学习到最佳实践，对DRF的了解还是不成体系。官方API文档虽然详细一些，但内容多且零散更适合查阅，对于系统性学习来说还是差了一点。

于是找到了一套不错的DRF源码分析视频来学习，并且在这里记下学习笔记。

参考了这两位同学的笔记，大部分是视频讲师在视频里做过的课堂笔记。

随笔分类 - Django REST framework笔记
随笔分类 - Django--drf相关

根据我个人理解对笔记做了部分修改、整理和补充。这里有我的测试代码可供参考，包括django项目、db数据和postman的测试数据包。

基本概念

RESTful: Representational State Transfer 表现层状态转换
ful: 形容词后缀，表示“（这一）类的、（这种）风格的”
API: Application Programming Interface 应用程序接口
接口：联系两个物质的媒介，完成信息交互
Web程序接口
- 功能：联系前台页面与后台数据库的媒介
- 组成
  - url: 长得像返回数据的url链接
  - 请求参数: 前台按照指定的key提供数据给后台
  - 响应数据: 后台与数据库交互后将数据反馈给前台

RESTful API

接口规范

功能：为了采用不同的后台语言，也能使用同样的接口，获取到同样的数据
接口：
- url
- 相应数据
接口文档：
- url + 请求参数
- 响应数据

URL规范

RESFful API的URL应包含如下部分：

用api关键字标识接口url

如 - api.baidu.com - www.baidu.com/api

优先选择https协议

接口数据安全性考量

版本标识

如

api.baidu.com/v1/...
api.baidu.com/v2/...

资源

接口操作的数据对象，在url中一般采用资源（名词）复数形式。一个接口可以包含对该资源的多种操作方式。如

api.baidu.com/books
api.baidu.com/books/(pk)

请求方法

HTTP请求方法，标识操作资源的方式，如

GET /books/ & GET /books/(pk): 获取所有/获取一个
POST /books/: 增加一个(多个)
DELETE /books/(pk): 删除一个
PUT /books/(pk): 整体更新一个
PATCH /books/(pk): 局部更新一个

请求参数

往往涉及数据的各种过滤操作及表现形式 - 筛选、排序、限制，如

api.baidu.com/books/?search=西&ordering=-price&limit=3

响应数据

API返回的数据，一般为Json格式，如

{

    "errcode": 0,
    "msg": "Query success.",
    "body": [
        {
            "type": 2,
            "location": "116.298457,39.848625",
            "radius": 41,
            "country": "中国",
            "province": "北京市",
            "city": "北京市",
            "citycode": "131",
            "district": "丰台区",
            "road": "丰台南路44号",
            "ctime": "1551178833",
            "indoor": "1",
            "error": 0
        }
    ]
}

响应状态码：由开发者（前端、后端、客户）定义，是对资源请求结果的应用层状态码，非HTTP响应状态码。
- 常见字段名示例：
  - "status"
  - "errcode"
- 常见值示例：
  - 0: 表示操作资源成功
  - 1: 表示操作资源失败
  - 2: 表示操作资源成功，但没匹配结果
响应状态码文字说明
- 常见字段名示例
  - "msg"
  - "message"
资源本身
- 常见字段名示例
  - "data"
  - "results"

注意：不能直接返回的资源(子资源、图片、视频等资源)，而是返回该资源的url链接

基于restful规范的原生Django接口

测试代码及数据请参见 demo项目 no1_my_restapi

原生接口对各种格式的POST数据的支持情况如下：

[x] form-data
[x] x-www-form-urlencoded
[ ] ~~raw：包括常见的json、xml等~~

也就是说 原生接口并不支持对POST请求中json数据的自动解析，后端只能拿到整个json字符串

DRF - Django REST Framework

DRF有如下主要模块：

from rest_framework.views import APIView, ...                      # 视图模块 - 对django原生视图类的封装
from rest_framework.response import Response, ...                  # 响应模块 - 对django原生响应类的封装
from rest_framework.request import Request, ...                    # 请求模块 - 对django原生请求类的封装
from rest_framework.serializers import Serializer, ...             # 序列化与反序列化模块
from rest_framework.settings import APISettings                    # DRF的配置文件
from rest_framework.filters import SearchFilter, ...               # RESTful API 基础功能 - 过滤
from rest_framework.pagination import PageNumberPagination, ...    # RESTful API 基础功能 - 分页
from rest_framework.authentication import TokenAuthentication, ... # RESTful API 基础功能 - 认证
from rest_framework.permissions import IsAuthenticated, ...        # RESTful API 基础功能 - 权限（是否登录）
from rest_framework.throttling import SimpleRateThrottle           # RESTful API 基础功能 - 频率

可以看到 DRF 在 django原有基础上进行类封装，并实现类 RESTful API的各大基础功能。

原生View不同，DRF实现了对json格式的POST请求数据的自动解析：

[x] form-data
[x] x-www-form-urlencoded
[x] raw：包括常见的json、xml等

扩展阅读

A RESTful Tutorial
API Design Cheat Sheet: 中文 / EN
DRF API 指南
DRF 官方文档（历史版本）中文翻译
HTTP后台端：RESTful API接口设计

雪泥鴻爪

Django REST Framework 学习笔记（一）：RESTful API 初探

按