Django-理解RESTful
这篇讲什么
- REST 是 Roy Fielding 在 2000 年博士论文里提出的设计风格,不是标准;抓住「资源、表现层、状态转化」这三个关键词,后面 DRF 的许多规矩为什么这么定就顺了。
- 这篇偏概念,讲「网站即软件」的来路和 RESTful 架构的构成;涉及具体行为的部分以本机 Django 5.2.19 + DRF 3.18.3 的实测为准。
概述
- 网站即软件:它是一种新型的软件,采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时(high latency)、高并发等特点。
- 网站开发完全可以采用软件开发的模式。但传统上软件和网络是两个领域,很少有交集:软件开发针对单机环境,网络研究系统之间的通信。互联网兴起后两者开始融合,现在要考虑的是「如何开发在互联网环境中使用的软件」。
- REST 是 Roy Thomas Fielding 在 2000 年的博士论文里提出的,Representational State Transfer 的缩写,中文一般译作「表现层状态转化」。REST 是设计风格,不是标准;符合 REST 原则的架构才叫 RESTful 架构。
- 本篇所有「DRF 是怎么落地这些原则的」都是本机实测出来的(Django 5.2.19 + DRF 3.18.3)。
RESTful 架构的三个关键词
-
资源(Representations)
- 资源就是网络上的一个实体、一段具体信息:可以是一段文本、一张图片、一首歌、一种服务。
- 用一个 URI(统一资源定位符) 指向它,每种资源对应一个特定 URI,要获取它就访问这个 URI,所以 URI 成了资源的地址和唯一标识。所谓「上网」,就是与互联网上一系列资源互动、调用它们的 URI。
- 设计要点:URI 里放名词不放动词。实测 DRF 的
DefaultRouter生成的就是这种形状:「删除某个学生」不写成1
2student-list ^vs/students/$
student-detail ^vs/students/(?P<pk>[^/.]+)/$/delete_student?id=1,而是DELETE /students/1/——动词在 HTTP 方法上,不在路径里。
-
表现层(State)
- 资源是信息实体,可以有多种外在表现形式:文本可以是 txt、HTML、XML、JSON,甚至二进制;图片可以是 JPG、PNG。
- URI 只代表资源的位置,不代表它的格式。严格说网址末尾的
.html是多余的,因为后缀表示格式、属于表现层。具体表现形式应该在 HTTP 请求头里用Accept和Content-Type指定,这两个字段才是对表现层的描述。 - DRF 把这件事做成了「内容协商」,实测同一个 URL 换
Accept就换返回:1
2
3
4Accept=application/json -> 200 | Content-Type=application/json
Accept=text/html -> 200 | Content-Type=text/html; charset=utf-8 # 可浏览 API 页面
Accept=application/xml -> 406 | Content-Type=application/json # 没有 XML 渲染器
Accept=*/* -> 200 | Content-Type=application/json406 Not Acceptable就是「你要的表现层我没有」,这是 REST 里表现层概念的直接体现。- 默认渲染器实测是两个:
JSONRenderer+BrowsableAPIRenderer(后者就是浏览器里那个可交互页面)。
-
状态转化(Transfer)
- 访问网站就是客户端和服务器的一次互动,过程中必然涉及数据和状态的变化。
- HTTP 是无状态协议,所以如果客户端要操作服务器,必须通过某种手段让服务器端发生状态转化,而这种转化建立在表现层之上,因此叫「表现层状态转化」。
- 客户端能用的手段只有 HTTP 协议本身,也就是四个表示操作方式的动词:GET 取资源、POST 新建资源(也可用于更新)、PUT 更新资源、DELETE 删除资源。
- 实测 DRF 对这几个动词的真实响应(
StudentViewSet挂在 router 上):动作 请求 实测状态码 说明 取列表 GET /api/vs/students/200 未分页时直接是数组 取一条 GET /api/vs/students/1/200 / 404 不存在时 {"detail": "No Student matches the given query."}新建 POST /api/vs/students/201 校验不过回 400 + 字段错误字典 全量更新 PUT /api/vs/students/1/200 需要带齐必填字段 部分更新 PATCH /api/vs/students/1/200 只给改的字段 删除 DELETE /api/vs/students/1/204 响应体为空 不支持的方法 DELETE /api/fbv/students/405 带 Allow: POST, GET, OPTIONS头
总结
- 每一个 URI 代表一种资源。
- 客户端和服务器之间传递的是这种资源的某种表现层(靠
Accept/Content-Type描述,不是靠 URI 后缀)。 - 客户端通过 HTTP 动词对服务器端资源进行操作,实现表现层状态转化;服务器只回状态码 + 表现层数据,不保存会话状态。
- 补充一条 REST 之外但很实用的约定:状态码要语义化。DRF 直接给了 64 个
HTTP_*常量(实测dir(rest_framework.status)数出来的),写status.HTTP_400_BAD_REQUEST比写400可读;下一篇文章按「协议/域名/版本/路径/方法/过滤/状态码/错误处理」逐项展开。
参考
- REST 博士论文(Fielding, 2000):REST 概念的原始出处。
- Django REST framework 官方文档:API guide:资源、路由、内容协商的落地方式。
- MDN:HTTP 请求方法:GET/POST/PUT/PATCH/DELETE 的语义与安全方法定义。
- MDN:Accept 头:表现层协商的请求头。