REST API 特征详解（以及大多数人容易搞错的地方）

每次你同步 CRM、拉取物流更新，或者连接两套 SaaS 工具，背后真正干活的，往往都是 REST API。大多数人平时不会特意去想它——直到出了问题。

有意思的是：哪怕在开发者之间，对于什么才算“RESTful” API 也常常说不清。这词被用得太随意了，以至于有个 Reddit 讨论直接把话挑明了——“我觉得自己按照 Roy Fielding 的定义，从来没真正做出过一个 RESTful API。” 说这话的是开发者，不是业务用户。这个概念最早来自 Roy Fielding 在 UC Irvine 的，他把 REST 描述为一种架构风格——一组设计约束，而不是协议、不是产品，也不是你下载下来就能直接用的规范。可根据 ，API 专业人士中 REST 的使用率高达 93%。也就是说，几乎人人都在用，但仍有不少团队并不真正理解它到底要求什么。本文会用通俗语言带你梳理 REST API 的 6 个核心特征，指出多数团队最容易搞错的地方，介绍一个可以自查成熟度的模型，并把 REST 与 SOAP、GraphQL 和 gRPC 做对比。

什么是 REST API？（通俗定义）

REST（Representational State Transfer，表述性状态转移）是一套规定软件系统如何通过网络进行通信的设计原则。

更准确地说，它是一种架构风格，定义了一组约束——比如无状态、可缓存、统一接口——来指导客户端（你的浏览器、移动应用或自动化工具）如何与服务器（数据所在的位置）交互。REST 通常运行在 HTTP 之上，返回的一般是 JSON，但 REST 本身并不绑定任何特定协议或数据格式。

你可以把它想成一场晚宴的礼仪规则。REST 不会规定你上什么菜、说什么语言——它定义的是怎么传菜、怎么再添一份，以及怎么表示你已经吃完了。只要遵守同一套礼仪，两套系统即使从没见过面，也能稳定地互相沟通。

REST 不是这样： REST 不是你安装的某个产品。它也不是像 HTTP 或 SOAP 那样的协议。把一个 API 叫做“RESTful”，并不意味着它完全符合 Fielding 最初提出的所有约束——通常只是说明它使用了资源 URL 和 HTTP 方法。行业里对“REST-ish”和“真正 RESTful”的混淆，正是最常见的误区之一，下面我们会详细拆开讲。

一眼看懂 REST API 的 6 个特征

在深入之前，先看一份速查表。Fielding 定义了 6 条 API 若要被视为 RESTful 就应遵守的约束。其中 5 条是必须的，1 条是可选的。

This paragraph contains content that cannot be parsed and has been skipped.

要把这些约束放进一个真实系统里看，可以想象下面这种分层架构：

1客户端 / 移动应用
2        ↓
3CDN / 边缘缓存（例如 Cloudflare）
4        ↓
5API 网关（限流、认证、CORS）
6        ↓
7负载均衡器
8        ↓
9应用服务器
10        ↓
11数据库 / 内部服务

客户端只和 CDN 层对话。它根本不知道自己后面还有多少层。这就是分层系统约束的实际作用——安全、缓存和扩展也正是在这一层层结构里实现的，而客户端无需知道细节。

下面进入详细拆解。

逐条解释 REST API 的特征

客户端-服务器分离

Fielding 的第一条约束：客户端（用户交互的一端）和服务器（数据存放与逻辑运行的一端）必须分离。他把这称为关注点分离。

这在实践里为什么重要？因为它意味着一款手机银行应用可以彻底重做界面，而银行完全不用动它的账户数据库或交易引擎。比如 会通过资源端点暴露联系人、活动、旅程和推送通知。无论你是在做定制仪表盘、移动应用，还是连接第三方工具，后端都保持不变。

对业务团队来说，这意味着迭代速度更快。前端设计师和后端工程师不必被同一个发布节奏绑死。只要 API 合同稳定，双方就可以独立推进。

无状态

请求之间不保留记忆。客户端发给服务器的每一次调用，都必须包含服务器处理请求所需的全部信息——服务器不会保留上一次交互留下的状态。

我更愿意把它类比成打客服电话：你每次都得重新解释自己的问题。烦吗？当然烦。可好处也很大：任何空闲客服都能接手，而且呼叫中心可以直接再加 500 个座席，不需要重构任何东西。这就是水平扩展。

从技术角度说，无状态意味着没有粘性会话。负载均衡器可以把你的下一次请求路由到任意一台健康服务器上。如果一台服务器挂了，另一台可以无缝接上。Fielding 的论文，无状态能提升可见性（监控工具可以把每个请求单独理解）、可靠性（故障不会破坏共享会话状态）和可扩展性（服务器可以在请求之间释放资源）。

现实中的补充说明：实际系统里依然会有认证令牌、购物车和 OAuth 流程。重点并不是“任何地方都不能有状态”，而是服务器不能在自己内存里跨请求保存客户端会话状态。令牌、数据库和共享缓存会负责这些工作。

可缓存性

这个响应能不能复用？这就是可缓存性要回答的问题。响应应该明确声明自己是否可以被缓存；如果可以，客户端和中间层（如 CDN）就会在后续相同请求中复用它，从而减少服务器负载并提升速度。

HTTP 的机制很直接：Cache-Control、ETag、Last-Modified 和 Expires 这些头部会告诉缓存，这个响应还能用多久、什么时候需要重新验证。对业务读者来说，可以把它理解成响应上的标签：“这个答案接下来一小时都有效”或者“每次都要重新问我”。

性能收益是实打实的。 测试显示，尾部缓存命中响应时间可改善 50–100ms。Fielding 自己的论文也记录了 Web 流量如何从 1994 年每天 10 万次请求增长到 1999 年每天 6 亿次请求——而缓存正是其中关键的设计因素。

通常可缓存的内容： 商品目录、公开博客内容、国家/币种列表、API 文档。
通常不适合缓存的内容： 个人仪表盘、结账总额、银行余额、管理员报表。

统一接口

这是 Fielding 自己称为 REST 与其他架构风格区别开来的核心特征。它标准化了客户端与资源的交互方式，让 API 更可预测。

这个大原则下又包含四个子约束：

1. 资源标识： 每个资源都有稳定的 URI。/customers/123 是一个客户，/orders/456 是一笔订单。
2. 通过表述操作资源： 客户端操作的是资源的表述（JSON、XML、HTML），而不是服务器内部对象。
3. 自描述消息： 请求和响应会携带足够的元数据——方法、状态码、内容类型、错误细节——让任何中间件或客户端都能理解它们。
4. HATEOAS（超媒体即应用状态引擎）： 响应中包含与相关操作和资源有关的链接，这样客户端无需把每个端点都写死，就能知道下一步该做什么。

HTTP 方法映射是统一接口最直观的部分：

This paragraph contains content that cannot be parsed and has been skipped.

明确说明，GET 应该是安全的，而 GET、PUT 和 DELETE 应该是幂等的。GitHub、Stripe 和 Spotify 这些知名 API 都严格遵循这些模式，所以学会一个，就能很快上手另一个。

分层系统

你的客户端根本不知道自己面对的是源服务器、CDN 缓存、API 网关，还是负载均衡器。这正是重点——每个组件只看见自己相邻的一层。

这就使得以下能力成为可能：

• CDN：像 Cloudflare 这样的 CDN 放在 API 前面，用于缓存和加速响应
• API 网关：AWS API Gateway、Kong、Apigee 负责认证、限流和配额
• 负载均衡器：把无状态请求分发到多台应用服务器上

指出，使用 AWS API Gateway，26% 使用 Azure 的网关，31% 同时使用多个网关。分层架构不是理论概念，而是真实生产系统的工作方式。

代价是：每增加一层，都会带来一点点延迟。不过 Fielding 认为，在大多数现实系统里，中间层的共享缓存所带来的收益，足以抵消这部分开销。

按需代码（可选）

这是最“另类”的一条。按需代码是唯一可选的 REST 约束：服务器可以发送可执行代码——比如 JavaScript——来即时扩展客户端功能。

现实中最常见的例子，就是网页从服务器加载 JavaScript。可对于移动应用、后端任务或自动化工具消费的普通 JSON REST API 来说，按需代码几乎从来不会用到。API 客户端通常不希望执行来自远端服务器的任意代码。

对大多数读者而言，这条约束更像脚注。它存在于 Fielding 的模型里，是为了完整性，但不会影响你日常对 API 的判断。

大多数人都搞错了什么：现在的 REST API 真的都 RESTful 吗？

这是没人愿意直说的部分：大多数把自己称为“RESTful”的生产 API，其实只是带有 REST-ish 风格约定的 HTTP JSON API。它们会用资源 URL、HTTP 方法和状态码——大概也就这些。Reddit 上 r/softwarearchitecture 的一个讨论里，有开发者承认自己从没做过真正符合 Fielding 定义的 REST API。另一个 r/learnprogramming 讨论则直接变成了争论：到底有没有人能就“RESTful”到底是什么意思达成一致。

一项 2026 年的研究采访了 16 位 REST API 专家，发现尽管规范指南确实能提升可用性，但开发者对严格 REST 规则存在明显抵触——他们认为指南太长，而且与自己所在组织的实际情况不匹配。

那这些约束在实践中到底落实得怎么样？

This paragraph contains content that cannot be parsed and has been skipped.

团队为什么跳过 HATEOAS： 客户端开发者更愿意看 OpenAPI 文档、用 SDK，而不是在运行时动态追踪链接。HATEOAS 需要稳定的媒体类型、链接关系定义和工作流建模——短期成本很高，而对大多数团队来说收益并不明显。

更务实的结论是：一个 API 不需要 100% 符合 Fielding 才能有用。可如果你知道自己跳过了哪些约束、又会因此失去什么，就更能做出更好的设计和集成决策。

Richardson 成熟度模型：你的 API 到底有多 RESTful？

如果“它到底是不是 RESTful”这种二元问题帮不上忙，Richardson 成熟度模型会是更实用的框架。该模型由 Leonard Richardson 提出，并由 ，它把 REST 的采用程度分成 4 个等级。

This paragraph contains content that cannot be parsed and has been skipped.

你在现实中见到的大多数 API 都停留在2 级。它们正确使用资源、动词和状态码。这已经足够实用、足够可互操作，也足够得到工具生态支持。3 级才是 Fielding 的完整愿景，但真正落地的并不多。

你的 API 处于哪一层？ 你可以问自己：

• 这个 API 是不是所有功能都走一个统一端点？（0 级）
• 每个业务对象是否都有自己的 URI？（1 级及以上）
• HTTP 方法和状态码是否用对了？（2 级）
• 响应能不能告诉客户端下一步可以做什么，而不是只能靠外部文档？（3 级）

对我来说，这个模型是最能帮你跳出“它到底是不是 REST”争论的工具。它把二元判断变成了一个光谱。

常见 REST API 误区（以及如何避免）

我在对接第三方 API 时踩过的坑已经够多了，列表都能列一长串。而从开发者论坛来看，我不是唯一一个。下面是最常见的反模式——每一项都直接对应某条 REST 约束的违背。

This paragraph contains content that cannot be parsed and has been skipped.

要求使用官方 HTTP 状态码，并建议错误响应使用 Problem JSON。则规定，Problem Detail 只能用于 4xx/5xx，绝不能和 2xx 混用。这些不是学院派的偏好，而是运营大规模 API 团队沉淀出来的生产标准。

Reddit 上 r/learnprogramming 的一个帖子里，有开发者认真询问：错误时一直返回 HTTP 200 是否可行。到了 2026 年这个问题还在被反复问到，足以说明这些反模式有多顽固。

REST vs SOAP vs GraphQL vs gRPC：REST API 特征如何对比

单独理解 REST 很有用。把它和其他方案放在一起看，会更有帮助。

建议你根据兼容性、数据形状、操作方式和工具支持来选择。

什么时候选什么：

• REST：当你需要广泛兼容、简单 CRUD 操作和 HTTP 缓存时，REST 是首选。它是公开 API 以及 Web/移动端集成的默认方案。
• SOAP：当企业系统对合同要求严格、需要 WS-Security，或者你还要对接长期不会下线的遗留系统时，SOAP 仍然有意义。
• GraphQL：当你的前端需要灵活的嵌套查询，而且你想避免过度获取或获取不足的数据时，GraphQL 特别适合——复杂移动应用里很常见。
• gRPC：当你做的是内部微服务通信，而且低延迟和二进制序列化比浏览器兼容性更重要时，gRPC 更合适。

举个真实世界中的 REST 例子： 采用的是简单直接的 POST 端点（/distill 和 /extract），JSON 请求/响应体，Bearer 令牌认证，以及标准 HTTP 状态码（400、401、402、408、422、429、500、502、503、504）。它展示了一个生产级 AI 产品如何体现 REST 特征，而不需要 SOAP 合同或 gRPC 的复杂性。它不是 HATEOAS 的展示案例，但确实是一个实用的 2 级 API，业务团队和开发者都很容易集成。

为什么 REST API 特征对业务团队很重要

销售、运营、电商——这些团队都不会写 API 代码。但你们会选供应商、连接工具、搭建自动化流程，而 REST API 的质量会直接影响这些集成到底是痛苦还是顺滑。

工具集成： 当你的 CRM 和营销自动化平台同步时，REST API 的设计会决定这个同步是稳定还是脆弱。比如 通过可预测的资源端点管理联系人、活动、旅程和推送通知。如果这些端点遵循 REST 约定，你的 RevOps 团队就能自动化处理，而不必写各种补丁式绕路方案。

电商运营： 管理履约订单、追踪号和发货状态。物流应用和履约工具都依赖这一层。当 API 设计得好——状态码准确、商品目录可缓存、错误信息清晰——你的物流流程就会很顺。设计不好时，你就会在凌晨 2 点面对莫名其妙的失败。

评估供应商： 了解这 6 条约束后，你就有了一份实用检查清单：

• API 是不是使用标准状态码，还是每次失败都像 200 OK？
• 错误信息是否足够具体，自动化工具能不能据此恢复？
• 限流、分页和认证是否有清晰文档？
• 常见响应能否缓存，以减轻负载？

数据提取与自动化： 像 这样的工具基于 REST 架构，让业务用户可以从网站、PDF 和图片中提取结构化数据，再导出到 Google Sheets、Airtable、Notion 或 Excel。Thunderbit 的 用一个 2 步界面把复杂性藏到了背后，但在底层，正是 REST 原则——无状态请求、JSON 响应、标准错误——让集成层保持可靠。

还有一个值得注意的数据点：Postman 2025 报告发现，只有会在设计 API 时主动考虑 AI 代理，而 51% 的人担心 AI 代理会发起未经授权或过量的 API 调用。随着自动化和 AI 驱动流程在业务团队中成为常态，可预测的 REST 模式、最小权限 API key 和限流机制，就不只是开发者关心的问题了——它们是运营风险因素。

Thunderbit 如何把 REST 原则用在业务用户身上

我们构建 时默认了一件事：大多数用户根本不会去读 REST 规范——而且也不该被要求去读。但让 Thunderbit 易用的那些设计选择，正是建立在本文讨论的 REST 特征之上。

下面简单看一下实际流程：

1. 从 安装 Chrome 扩展，然后打开你想提取数据的任意网站、PDF 或图片。
2. 点击“AI 建议字段”，Thunderbit 的 AI 会读取页面，并自动生成一个结构化列列表——产品名、价格、邮箱，页面里有什么就提什么。
3. 如有需要，调整列设置，然后点击“爬取”。Thunderbit 会自动处理分页、子页面和动态内容。
4. 将数据导出到 Google Sheets、Airtable、Notion、CSV 或 Excel——免费，不设付费墙。

对于开发者和自动化流程，Thunderbit 的 以 REST 风格的 POST 端点形式提供 /distill（清理后的 Markdown 提取）和 /extract（结构化数据提取），配合 JSON 请求体和标准 HTTP 错误码。按 Richardson 成熟度模型来看，这已经是很扎实的 2 级——有资源、方法正确、状态码有意义。

如果你想更广泛地了解网页抓取或数据提取，我们还写了更深入的指南：、以及。

关键结论

• REST 是一种架构风格，不是协议。 它定义了 6 条约束——客户端-服务器、无状态、可缓存、统一接口、分层系统，以及可选的按需代码——来指导 API 设计。
• 大多数所谓“RESTful” API 并不完全 RESTful。 绝大多数停留在 Richardson 2 级（资源 + HTTP 动词 + 状态码）。HATEOAS 和按需代码很少真正实现。
• Richardson 成熟度模型是最好的自查工具。 它把“是不是 REST”这个二元问题，变成了一个更实用的光谱（0–3 级）。
• 常见错误——错误时返回 200 OK、所有操作都用 POST、缺少缓存头——依然很普遍。 了解这些约束，能帮助你识别并修正这些反模式。
• REST vs SOAP vs GraphQL vs gRPC 不是“谁最好”，而是“谁更适合”。 REST 主导公开 API 和 CRUD 集成；GraphQL 适合复杂前端；gRPC 擅长内部微服务；SOAP 仍存在于企业/遗留场景。
• 业务团队理解 REST 特征是有收益的，尤其在评估供应商、连接工具和构建自动化流程时。像 这样的工具把 REST 原则落地，让数据提取变得可用，而不需要你具备技术背景。

常见问题

REST API 的 6 个特征是什么？

REST 的 6 条约束是：(1) 客户端-服务器分离，(2) 无状态，(3) 可缓存，(4) 统一接口，(5) 分层系统，以及 (6) 按需代码（可选）。根据 Fielding 的原始定义，前 5 条是一个 API 被视为 RESTful 的必要条件。

REST 和 RESTful 有什么区别？

REST 是架构风格，也就是 Roy Fielding 定义的那套设计约束。“RESTful”则用来描述遵循这些约束的 API。实际中，很多被标成“RESTful”的 API 其实只是部分符合，通常实现了资源、HTTP 方法和状态码，但跳过了 HATEOAS 和按需代码。

所有 REST API 都遵守每一条 REST 约束吗？

不会。大多数生产 API 会遵守客户端-服务器分离、无状态以及基础统一接口（资源 + HTTP 动词）。可缓存性和分层系统的实现并不稳定。HATEOAS 很少见，而按需代码在 JSON API 中几乎从不使用。

REST 和 GraphQL 有什么区别？

REST 通过多个端点暴露资源，并使用标准 HTTP 方法（GET、POST、PUT、DELETE）。GraphQL 通常只用一个端点，由客户端在查询中精确指定需要哪些字段。REST 的原生 HTTP 缓存更强；GraphQL 在处理复杂嵌套数据需求时更灵活，也能减少过度获取。

什么是 HATEOAS？真的有人在用吗？

HATEOAS（超媒体即应用状态引擎）意味着 API 响应会包含链接，告诉客户端下一步可以执行哪些动作——这样客户端就不用把每个端点都写死。它是 Fielding 对 REST 的核心愿景之一（Richardson 3 级），但在实践里，真正实现它的公开 API 很少。大多数团队会停在 2 级，然后改靠文档和 SDK。

了解更多