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
      2
      student-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
      4
      Accept=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/json
      • 406 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 可读;下一篇文章按「协议/域名/版本/路径/方法/过滤/状态码/错误处理」逐项展开。

参考

本文结束 感谢您的阅读
正在加载今日诗词....