REST 与资源风格 API：名词、动词与状态

REST（Representational State Transfer）是一种架构风格，常用于设计 HTTP API： 把业务对象建模成资源（名词），用 HTTP 方法（动词）表达操作， 用状态码与标准标头传达结果。它不等同于「返回 JSON」，JSON 只是常见表示形式。

入门：资源与 URI

资源应有稳定可预测的 URI，例如 /users/123、/orders?state=open。 「动词挤进路径」如 /createUser 不是 RESTful 的唯一反面教材——但若全局如此，往往更难缓存与授权建模。

入门：动词的大致分工（语义层面）

• GET：安全且幂等（不应改变服务端状态）；可缓存。
• POST：常用于创建或非幂等动作；具体语义由文档约定。
• PUT/PATCH：替换或部分更新资源。
• DELETE：删除资源（幂等期望常被提及，仍以 API 契约为准）。

深入：幂等与网络重试

客户端在遇到超时可能重复发送同一请求；若服务端未做到幂等，可能重复扣款或重复创建订单。 工程上常用幂等键（idempotency key）或业务唯一约束兜底——这已经超出「REST 名词解释」，但是 REST 风格 API 落地的必经之路。

HATEOAS 与成熟度

教科书里的 Richardson 成熟度模型提到超媒体驱动（响应里带下一步链接）；现实中纯 HATEOAS 并不多， 往往与 OpenAPI 文档、版本化路径（/v1/）并用。

「是否 REST」在业界争论已久；交付价值优先于标签。阅读 HTTP 语义请以 RFC 9110 为准。

与其它主题的衔接

表示层常用 JSON；传输层依赖 HTTPS； 状态码见 HTTP 状态码；认证与会话见 Cookie 与 Session。