什么是 RESTful API

本章导读：在动手学习规范细节之前，我们先建立一个清晰的整体认知——RESTful API 到底是什么、它解决什么问题、长什么样子。本章以一个最小可运行的例子贯穿始终，让你先"看见"REST，再去理解它背后的设计思想。

1. 从一次真实的接口调用说起

假设你要开发一个博客系统，前端需要"获取 id 为 42 的文章"。在 RESTful 风格出现之前，很多团队的接口长这样：

POST /api/articleService
Body: { "method": "getArticleById", "id": 42 }

这是一个典型的 RPC（远程过程调用）风格：URL 描述的是"要执行的动作"，所有信息都塞进请求体，HTTP 只是隧道的壳。

而同样的需求，RESTful 风格的写法是：

GET /api/articles/42 HTTP/1.1
Host: book.example.com
Accept: application/json

响应：

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "title": "RESTful API 设计规范",
  "author": "麻瓜",
  "status": "published",
  "createdAt": "2026-01-15T08:30:00Z"
}

两种风格的核心差异一目了然：

对比项	RPC 风格	RESTful 风格
URL 含义	动词/服务名（`getArticleById`）	名词/资源（`/articles/42`）
动作表达	藏在请求体里	由 HTTP 方法（GET/PUT/DELETE）表达
操作结果	业务字段自解释（各团队各写各的）	标准 HTTP 状态码（200/404/409…）
HTTP 协议利用程度	只当传输通道	充分利用语义（方法、状态码、缓存、内容协商）

RESTful API 的本质：把 HTTP 协议本身的设计（URI、方法、状态码、头部）用足、用对，让接口"不言自明"。

2. REST 的定义

REST（REpresentational State Transfer，表现层状态转化）这一概念由 Roy Fielding 在其 2000 年的博士论文《Architectural Styles and the Design of Network-based Software Architectures》中提出。Fielding 是 HTTP 规范的主要作者之一，REST 正是从 HTTP 协议的设计初衷中提炼出来的架构风格。

用一句话概括：

REST 是一种架构风格（architectural style），它通过一组约束条件（constraints），指导你设计出以资源为核心、无状态、统一接口的分布式系统。

注意三个关键词：

架构风格，不是协议、不是标准、不是框架。REST 只说"应该遵循这些原则"，具体怎么落地（URL 怎么写、JSON 字段叫什么名）需要团队自己制定规范——这正是本教程要讲的内容。
**资源（Resource）**是核心。每个 URI 标识一个资源，客户端通过操作资源的"表现（Representation）"来与服务器交互。
表现层状态转化：服务器保存资源的状态（数据），客户端每次请求都携带足够信息（如 Token），服务器读取/改写资源后返回新的表现（如 JSON），完成一次"状态转化"。

3. 一个 RESTful API 的解剖

我们放大看一个完整的"删除文章"请求，标注出 REST 的各个要素：

DELETE /api/v1/articles/42 HTTP/1.1        ← 方法 + URI：对哪个资源做什么操作
Host: api.book.example.com
Authorization: Bearer eyJhbGciOiJIUzI1...   ← 凭证：无状态设计，不依赖服务器会话
Accept: application/json                    ← 内容协商：希望服务器返回什么格式
If-Match: "9a3f-bb12-..."                   ← 条件请求：乐观并发控制

响应：

http

HTTP/1.1 204 No Content                     ← 状态码：操作结果的标准表达
                                       ← 204 表示成功且无响应体，这是 RFC 9110 的规定

一次交互中体现了 REST 的四大接口要素（后续章节逐一展开）：

要素	本例中的体现	规范依据
资源标识	`/api/v1/articles/42`	RFC 3986 (URI Generic Syntax)
资源操作	`DELETE` 方法	RFC 9110 (HTTP Semantics)
资源表现	`Accept: application/json` 协商	RFC 9110 + RFC 8259 (JSON)
交互结果	`204 No Content` 状态码	RFC 9110 状态码注册表

4. "RESTful" 与 "REST" 的区别

日常交流中两个词经常混用，但严格来说：

REST：Fielding 论文中定义的那套完整架构约束（含 HATEOAS，见后文）。
RESTful：工程实践中对"遵循了资源建模 + HTTP 方法 + 状态码这套设计方式的 API"的通俗称呼。

绝大多数商业 API（GitHub、Stripe、腾讯云等）其实是 "RESTful" 而非教科书意义上的完整 REST——它们通常不实现 HATEOAS。本教程以工程视角为主：既讲清楚 Fielding 的原始约束，也给出业界公认的设计规范，帮你写出符合 RFC 语义、团队可维护、机器可理解的 API。

5. 什么样的 API 不算 RESTful

以下反例在真实项目中非常常见，先建立"嗅觉"：

❌ POST /api/getArticleList              ← 动词出现在 URI 中
❌ GET  /api/deleteArticle?id=42         ← 用 GET 做删除，破坏方法语义
❌ GET  /api/article/42,43,44            ← 资源标识混乱
✅ GET  /api/articles?author=42         ← 正确：查询参数表达过滤
✅ DELETE /api/articles/42              ← 正确：方法表达动作

❌ 永远返回 200，靠 body 里的 code 区分成败
{ "code": -1, "msg": "not found" }
✅ 返回 404 + 标准错误体（见"错误处理规范"一章）

IMPORTANT

Fielding 本人曾在 2009 年的博文《REST APIs must be hypertext-driven》中针对"只用了 URL 和 JSON 就自称 REST"的实践发出著名吐槽："如果 API 使用了 POST 和 GET，URI，并且用 JSON 或 XML 作为媒体类型，那它就完全不是 RESTful。"（原文见 roy.gbiv.com）真正的 REST 要求统一接口与超媒体驱动。不必教条照搬，但这提醒我们：REST 的灵魂是"用协议说话"，而不是贴标签。

6. 为什么要严格遵守规范

你可能会问：接口能跑就行了，为什么要在意 RFC？

互操作性：状态码 401 与 403 语义不同，网关、SDK、监控系统可以自动处理（如 401 触发重新登录，403 提示无权限）。
缓存：正确使用 GET + Cache-Control + ETag，CDN 与浏览器可以免费帮你扛流量；乱用 POST 则永远无法缓存。
工具链：符合 OpenAPI 规范的接口能自动生成文档、客户端代码、Mock 服务、契约测试。
协作成本：新同事看到 DELETE /articles/42 → 204 无需读文档就明白行为；看到 POST /doArticle 则必须翻代码。
长期演进：遵循规范的系统（版本、弃用、条件请求）才能平滑升级而不破坏老客户端。

7. 本章小结

RESTful API = 以资源为中心，用 URI 标识资源、用 HTTP 方法操作资源、用状态码表达结果、用**表现层（JSON 等）**传递数据。
REST 出自 Fielding 博士论文，与 HTTP 同源；"RESTful" 是工程上的通俗叫法。
判断 API 好坏的快速标准：把 body 遮住，只看方法 + URI + 状态码，能不能读懂 80% 的意图。

8. 下一步

想了解 REST 的理论根基与官方规范地图 → REST 的起源与官方规范
想评估自己现有 API 的"REST 含量" → 理查森成熟度模型

什么是 RESTful API ​

1. 从一次真实的接口调用说起 ​

2. REST 的定义 ​

3. 一个 RESTful API 的解剖 ​

4. "RESTful" 与 "REST" 的区别 ​

5. 什么样的 API 不算 RESTful ​

6. 为什么要严格遵守规范 ​

7. 本章小结 ​

8. 下一步 ​