初学者指南：REST API——资源、方法、状态码与无状态性
一本用通俗语言讲解REST API是什么、使其正常运行的五大原理、它在实际团队中的应用场景，以及如何构建和测试第一个REST API的指南。
来源: REST API Explained for Beginners: What It Actually Is and Why It Matters
“学习 REST API”是每位新开发者都会听到的建议，但很少有人会进一步解释这一说法的具体含义。大多数解释要么用大量专业术语（动词、端点、无状态性）让读者不知所措，要么将其简化为“连接前端与后端的工具”，虽然没错，却无法提供任何有用的信息。
本指南采取了折中的方法。你将了解构成几乎所有 REST API 的五大核心概念、有助于记忆这些概念的思维模型、REST 在日常工程工作中的应用场景，以及使用 Node.js 和 Express 构建和测试第一个 API 的实际步骤，同时还会了解到最常阻碍初学者的错误。
简短定义
REST API是一组规范，用于让两个程序通过互联网进行通信。最常见的场景是前端向后台请求数据或要求其存储某些内容。在亲自构建之前，这个概念可能显得很抽象，但一旦开始实践，很快就能理解其原理。正因如此，无论人们是选择专攻服务器端开发，还是成为需要处理应用各层面的全栈开发者，REST通常都是他们最先学习的真正意义上的后台概念之一。
REST代表“表述性状态转移”，这是一种被正式定义的架构风格，用于描述网页应有的工作方式。要熟练使用它并不需要掌握那些正式的理论，日常的REST API实际上依赖的是以下这些实用规范。
为何REST会让这么多初学者感到困惑
有两点使得这个主题比应有的难度更高。
首先是词汇概念的模糊。在网络上，“API”几乎被用来指代任何一种软件之间提供的接口：浏览器API、库中的函数、云服务等等。REST是一种特定且极为流行的设计Web API的方式。由于它的广泛应用，人们常常用“API”来指代“REST API”，导致学习者难以区分这两个概念的界限。
其次是API没有可视化的界面。按钮或布局是能够直接看到的东西，而REST API则不然。人们完全有可能花费数周时间构建前端项目，却仍将“调用API”视为一个黑箱。通常只有在真正需要自己创建API时，这种困惑才会显现出来，因为此时这个概念必须立刻变得具体可感。
每个REST API背后的五个核心理念
去掉缩写后，REST API就是一种通过URL加上少量标准操作来使用HTTP请求和传输数据的方式。五个核心概念几乎涵盖了它的所有内容。
资源及其URL
资源是API所管理的事物：用户、帖子、订单、任务等。每个资源或资源集合都有各自的地址。/users通常指用户集合，而/orders/42则指某个特定的订单。优秀的REST设计会用名词来命名资源，让HTTP方法描述操作，这就是为什么会出现/orders/42而非/getOrder?id=42的原因。
HTTP方法
该方法用于告诉服务器你对资源想要执行什么操作：
GET用于读取数据且不会对其进行修改。
POST用于创建新内容，通常是在如/tasks这样的集合中。PUT用于替换现有的资源，而PATCH则用于更新其部分内容。DELETE用于删除该资源。一个值得尽早了解的属性是幂等性。GET、PUT和DELETE都应具备幂等性：重复发送相同请求后，服务器的状态应与仅发送一次时相同。POST通常不具备幂等性，因为两次相同的请求可能会创建两条记录。这一区别能解释许多后续的API设计决策，比如为何某些请求可以安全重试，而另一些则存在风险。
请求与响应
客户端会向这些URL中的一个发送请求。该请求包含方法、URL、标头（如内容类型或授权令牌等元数据），对于POST或PATCH之类的方法，还会包含请求体。服务器则会返回一个响应，其中包含状态码、标头以及通常还有请求体。在现代API中，该请求体几乎总是JSON格式。
状态码
每个响应都会附带一个三位数，用于概括处理结果。成功时显示 200，资源不存在时显示 404，服务器出现故障时则显示 500。第一位数字表示响应类别：2xx 表示成功，4xx 表示客户端发送了服务器无法接受的内容（如错误请求、缺少认证信息或资源不存在），5xx 表示服务器自身存在问题。首先查看响应类别是快速判断应从系统哪一端开始排查的最佳方法。
无状态性
每个请求都必须包含服务器处理它所需的所有信息。服务器不会依赖对用户刚才所提请求的记忆。例如，如果某个接口要求用户进行身份验证，那么每个请求都会包含相应的凭证，通常是以头部字段的形式出现的令牌。无状态性正是让 REST API 易于扩展的原因：任何服务器实例都能处理任意请求，因为它们都不依赖对话的私有内存。
一旦这五个概念变得直观易懂，大多数 REST API 文档就不再像外语那样难以理解了。你遇到的几乎所有参考页面都只是列出了资源、各资源支持的方法、请求和响应体的格式，以及可能收到的状态码。
思维模型：在餐厅点餐
用餐厅作类比很恰当。顾客不会走进厨房亲自做饭，他们会查看菜单，告诉服务员自己的需求，然后由厨房准备食物并端上桌。
- 菜单就相当于API文档：它列出了你可以请求的内容。
- 服务员则对应请求与响应的流程，负责将你的订单送进去并把结果带回来。
- 厨房则相当于服务器，负责处理那些你无法直接看到的工作。
从方法的角度来看，GET请求用于查询菜单上有什么或检查桌上已有的内容。POST用于下新订单，而DELETE则用于退回某道菜。你无需了解厨房内部的组织结构，只需正确下单，就能每次获得可预测且一致的响应。这个类比虽然存在局限（餐厅会记住你的座位，而无状态API则不会），但很好地体现了职责的分工。
REST在实际工程中的应用
REST并非仅存在于教科书中的概念，它几乎是每个产品团队日常工作中都会用到的技术：
- 前端开发人员会调用REST接口来加载个人资料、提交表单或刷新控制面板。
最后这一点正是REST成为Web API默认风格的重要原因。一套精心设计的端点能够同时支持浏览器客户端、iOS和Android应用以及外部合作伙伴的集成。认真设计这些端点至关重要，因为所有客户端最终都会依赖它们；我们在关于会破坏前端可靠性的API契约错误的文章中探讨了若不这样设计会出现的问题。
为何REST仍是合适的起点
也存在其他方法。例如GraphQL和gRPC在处理某些问题时比REST更为优雅，比如允许客户端精确请求所需字段或实现高效的服务间调用。出于三个实际原因，REST依然是初学者入门的最佳选择。
首先，REST无处不在。从支付服务提供商到天气数据，再到社交平台，你可能用到的大多数公共API都提供REST接口，而且通常是其默认接口。掌握它一次后，每当遇到陌生的文档时，你就能运用这一思维模型来理解其结构。
其次，REST遵循网络本身的设计原则。HTTP方法与状态码并非为REST而发明的，它们本就是浏览器和服务器早已使用的协议。正确学习REST意味着了解无论使用何种框架，网络底层的工作原理，而这种知识不会因特定库的更迭而过时。
第三，这是掌握前端基础之后的自然下一步。一旦你对HTML、CSS和JavaScript已经熟练，当界面开始加载真实数据而非硬编码的占位符时，通常就意味着项目从原型阶段过渡到了可以实际使用的形态。对于许多偏向前端的开发者来说，正是此时自行构建API不再是一种可选选项，他们也开始迈向全栈开发之路。若想进一步深入比较各种样式，可参阅REST与GraphQL及其各自的权衡。
使用Node.js和Express构建你的第一个REST API
仅靠阅读无法完全掌握这个主题。一旦你实际构建出某个东西，哪怕只是很小的作品，就会明白其中的道理。使用 Node.js 和 Express 开发的典型第一个项目通常会按照以下步骤进行：
- 创建一个最简服务器，它在指定端口上监听传入的 HTTP 请求。
- 添加如
/tasks这样的路由，并将其关联到一个能返回列表的GET处理函数。 - 在相同路径上添加一个
POST处理函数，用于接收新任务；此时将它们存储在普通的内存数组中即可。 - 通常在
/tasks/:id路径上添加PUT（或PATCH）和DELETE处理函数，用于更新和删除单个条目。 - 当 API 的结构确定后，用真正的数据库替换内存数组。
- 在连接任何前端之前，使用 Postman 等工具测试每一条路由。
有两个要点让这个流程行之有效。首先，使用内存数组可以让开发者将注意力集中在路由、方法及状态码上，而非数据库配置上。而最后一步——单独测试各路由——正是初学者最常忽略的环节。在依赖某个接口之前先独立检测该API，能极大简化调试过程，因为这样就不必再纠结错误出在API本身还是调用它的代码中了。
在实际开发中，不要对所有请求都返回200状态码，而应根据情况返回合适的状态码：执行POST操作创建任务时返回201，当id不存在时返回404，请求体缺少必填字段时返回400。正是这些细微的设定决定了API的使用体验。
初学者通常会遇到的难题
那些在 REST 开发中遇到困难的人往往并非能力不足，他们停滞不前通常是由于一些可以预见且可解决的缘由：
- 同时学习 REST 概念和 Express 等框架，导致无法区分哪些规则属于 HTTP，哪些属于框架本身。
- 从不使用 Postman 等工具直接测试路由，这使得前端和后端的错误难以区分。
- 忽视状态码和错误处理机制，当客户端无法区分成功与失败时便感到困惑。
- 在尚未完善基本的创建、读取、更新和删除路由之前就急于实现认证功能。
- 机械地复制教程中的 API，而不是用不同的资源构建小型应用，这掩盖了是否真正理解了相关概念。
这些都是结构上的问题，而非能力问题。解决这些问题通常能区分出那些真正擅长构建后端 API 的人，与那些只会背诵术语却还无法从空白文件开始设计接口的人。
根据自身起点调整学习路径
这些基本原则对所有人适用，但侧重点会因个人情况而有所不同。
- 学生应尽早学习 REST，因为这通常是让个人项目从静态页面转变为真正应用程序的第一步。
- 求职者不仅需要具备构建和调用 API 的实际技能，还要能够清晰地解释相关概念，因为许多职位的面试中都会出现 REST 相关问题。
帮助牢记概念的习惯
有一些习惯能将真正理解REST的人与仅知晓其名称的人区分开来。
不要只阅读文档，而应动手创建一些小型且具有原创性的东西，比如待办事项列表或笔记API。只有当你需要调试出问题的路由时，这些概念才能真正被牢记。
学会诊断故障而非凭猜测行事。查看状态码和错误信息，判断问题出在客户端还是服务器端，再通过直接请求进行确认。在实际工作中，这种直觉比死记硬背的定义更为重要，它也是区分那些真正构建过 API 与仅调用过 API 的人的关键。随着技能的提升，以统一且有文档记录的格式返回错误信息，能让所有使用你 API 的人更轻松地进行故障诊断。
快速获得反馈。能够向经验丰富的开发者、同事或社区论坛询问为何某个请求会返回错误数据，往往决定了一个 API 项目是能顺利完成还是被迫放弃。如果没有这种反馈机制，长时间被动观看视频会让许多学习者失去动力。
初学者常见问题
用一句话解释什么是 REST API？
这是一套规范，使得应用程序能够通过标准的HTTP请求和可预测的响应在互联网上进行通信。
前端开发者需要学习REST吗？
需要。前端工作涉及持续使用REST API，因此几乎所有岗位都要求开发者对其有基本的了解。如果日后想转向全栈开发，这也是最容易入门的途径之一。
学习REST难吗？
一旦概念被清晰地解释出来，其核心思想其实很容易理解。大部分难度来自于充斥着专业术语的解释，而非概念本身。
构建后端API需要计算机科学学位吗？
不需要。许多在职开发者，包括全栈开发者，都是通过培训课程、自学或师徒指导来掌握相关技能的，并非依靠正式学位。
可以在全职工作的同时学习这个吗？
可以。相关概念相当简洁，只需在几个晚上或周末完成一个小项目就能将其具体化。
总结
REST并没有人们想象中那么令人生畏。它是一种让软件请求和传输信息的一贯方式，建立在已经支撑着互联网的HTTP协议之上，而且存在于你日常使用的绝大多数应用程序背后。
- 有五个核心概念最为重要：带URL的资源、HTTP方法、请求与响应、状态码以及无状态性。
- 先学习这些概念，再使用Express框架将其具体应用。
- 在任何前端代码依赖之前，先单独测试每条路由。
- 应将状态码和错误处理视为设计的一部分，而非事后才考虑的问题。