REST API 工作原理——一次请求的往返

REST API 如何工作，在一张交互式画布上讲清楚：构造 HTTP 请求、服务器上的路由与校验，以及完成这次往返的响应。

REST API 是一场用 HTTP 进行的对话：客户端发出一个指明资源与动作的请求，服务器处理它，响应则带回一个状态码和结果。

REST API 工作原理——一次请求的往返

The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.

How to read this visual

  • 从左往右读这三列：请求、服务器处理、响应。
  • 客户端那一行与服务器那一行交替出现，所以每一个箭头要么是客户端发出了什么，要么是服务器决定了什么。
  • “请求有效吗？”这个决策要么通向正常路径，要么通向拒绝终点——这就是每一次 API 调用可能有的两种结果。

请求

“客户端构造 HTTP 请求（方法、URL、请求头、请求体）”是每一次 REST 交互的起点。方法就是动词——GET 读取，POST 创建，PUT 替换，PATCH 更新，DELETE 删除——而 URL 为资源命名，所以 /users/42 就是读取某一个用户的那次请求。“客户端通过 HTTPS 发送请求”是传输：REST 跑在 HTTP 之上，而 HTTPS 让这场对话在其他几张图解所描绘的同一套互联网基础设施上保持私密。

服务器的工作

“服务器把 URL 路由到匹配的处理程序”把请求映射到代码，而“请求有效吗？”就是那道关卡：身份认证（你是谁）、授权（你是否被允许）与负载校验全都发生在这里，失败的请求则被送到“服务器返回 400 / 401 / 403”这个拒绝终点。“处理程序执行业务逻辑”与“服务器在数据库中读取或写入该资源”才是真正的工作——也正是客户端永远看不见的那一部分。

响应

“服务器用状态码和 JSON 响应体构造响应”是契约的机器形态：200 表示成功，201 表示已创建，404 表示不存在，500 表示服务器故障。“客户端收到响应并解析它”与“客户端把结果呈现给用户”闭合了整个回路——这次往返在它开始的地方结束，也就是客户端，这正是图解要回到客户端那一行的原因。

Key relationships and takeaways

  • REST 是一份用 HTTP 写成的契约：方法是动词，URL 是资源，状态码是机器可读的结果。
  • 客户端是无状态的——每一个请求都自带服务器所需的一切，因此不需要共享会话。
  • 校验就是安全边界；无效的请求会在任何业务逻辑运行之前被拒绝。
  • 响应首先由它的状态码定义，其次才是它的响应体。
  • REST 流量跑在其他几张技术图解所描绘的同一套 DNS、HTTPS 与互联网基础设施之上。

When to use this visual

  • 在工程师设计第一个端点之前，先教会他们 HTTP 方法、URL 与状态码这套模型。
  • 对照 REST 惯例审视一个 API 的契约——错误到底是用状态码表达，还是用 200 加一个标志位？
  • 把关于幂等与缓存的讨论，落到请求究竟是怎样构造和校验的这件事上。

运作方式

  1. 把你自己的端点映射到请求方框上

    加上注释，列出你真实的方法与路由——GET /orders、POST /payments——让图记录下你这套 API 的全貌。

  2. 写清你的状态码

    在响应那一步注明你的 API 针对每种结果实际返回的状态码，并把契约中 200 与 400 之外用到的那些也补上。

  3. 加入身份认证

    在客户端与校验关卡之间插入令牌那一步——Authorization 请求头里的一个 JWT 或 OAuth 令牌——好显示身份是在哪里进入请求的。

  4. 画出重试与失败分支

    为网络故障、限流与服务器错误各加一个明确的终点，每一个都写上它触发的客户端行为（重试、退避、错误状态）。

常见问题

什么是 REST API？

REST API 是一组把系统资源暴露出来的 HTTP 端点。客户端用 HTTP 方法对资源操作——GET 读取，POST 创建，PUT 或 PATCH 更新，DELETE 删除——服务器则以一个状态码和一份表示形式作答，通常是 JSON。REST 是一种风格而不是标准，它的价值在于任何会说 HTTP 的客户端都能用它。

GET、POST、PUT 与 DELETE 有什么区别？

它们是 REST 契约里的动词。GET 读取一个资源，且不应有副作用。POST 创建一个新资源并返回它的标识。PUT 整体替换一个资源，并且是幂等的——重复执行不会再改变什么。PATCH 做局部更新。DELETE 删除一个资源。动词加上 URL 才共同指明完整的动作，这也是图中的请求方框把方法放在第一位的原因。

为什么状态码在 REST 里很重要？

因为它们是这次请求机器可读的结果。客户端不必解析响应体就能按状态码分支：2xx 成功，4xx 是客户端的错，5xx 是服务器的错。那些返回 200、却在响应体里塞一个错误标志的 API 破坏了这份契约，逼得每一个客户端都要为响应做特殊处理。

什么样的 API 才算“RESTful”？

实用的核对清单：用 URL 为资源命名，用 HTTP 方法表达动作，请求无状态（每一个都自带服务器所需的一切），响应正确使用状态码，往往还有超媒体或带版本的 URL。这张画布建模的就是那次往返——请求、校验、处理、响应——那正是每一次 RESTful 交互共有的形状。

在 QueryChart（FlowJam）中编辑这张图解

把上面这张 REST 画布原样打开成你自己的图表，把客户端和服务器改名为你自己的服务，再标注你的端点。

在 QueryChart（FlowJam）中编辑这张图解

可视化图解中的更多内容