很多人最开始接触 RESTful 时，听到的说法往往是"URL 里用名词，别用动词，把 /getOrderById 改成 /orders/123 就对了"。我当年也信过这套，觉得自己把接口地址整理得漂漂亮亮，就算是玩懂 RESTful 了。后来真正去啃原始论文、去维护一个被几十个客户端调用的 API 时才发现，URL 风格只是浮在水面上的冰山一角。RESTful 是一门关于"资源"的架构风格，它约束的是你如何组织系统的边界、如何利用 HTTP 本身的语义、如何让服务端和客户端在尽可能少的信息前提下完成协作。
这篇文章我想把 RESTful 架构基础重新串一遍。不会只讲"名词式 URL"这种表象，而是从架构约束、资源设计、HTTP 语义、无状态、通用模式落地这几个真正影响系统质量的角度去拆，最后再聊聊我在实际项目里踩过的坑和取舍。适合刚接触后端接口设计的新人，也适合那些已经在写接口但没系统梳理过 RESTful 的开发者对照自查。
1. RESTful 的本质：架构约束而不是 URL 规范
1.1 从 REST 到 RESTful，先搞清楚我们在说什么
REST（Representational State Transfer，表现层状态转移）是 Roy Fielding 在博士论文里提出的一种分布式超媒体系统架构风格。注意"风格"这个词——它不像协议那样有强制性的规范文档，更像一套设计哲学，告诉你"系统应该长成什么样才算健康"。
RESTful 则是"符合 REST 风格"的形容词。一个接口、一个系统被人称作 RESTful，意思是它在尽最大努力遵从这套架构约束。但因为没有强制标准，市面上大量号称 RESTful 的接口，其实只是借了 URL 的壳，内里仍然是 RPC 的思路——把 HTTP 当成一个可以随意塞方法名的传输管道。
要判断一个系统是不是真的 RESTful，不能只看 URL 漂不漂亮，而要检查它是否满足了 REST 的六大架构约束：客户端-服务器分离、无状态、可缓存、统一接口、分层系统、按需代码。这六条约束不是理论爱好者的空谈，每一条都直接对应分布式系统的某个实际问题。
| 架构约束 | 解决的核心问题 |
|---|---|
| 客户端-服务器分离 | 关注点分离，客户端只管展示，服务端只管数据与业务 |
| 无状态 | 每个请求携带全部上下文，服务端不需要保存会话 |
| 可缓存 | 减少交互次数与带宽消耗，提升性能 |
| 统一接口 | 客户端与服务器通过同一套约定交互，降低耦合 |
| 分层系统 | 客户端不感知代理、网关等中间层，便于架构演进 |
| 按需代码 | 服务端可下发代码扩展客户端功能（如 JavaScript） |
在这六条里，"统一接口"是 REST 最核心也最容易被误解的一条。它内部又拆出四个子约束：资源标识、通过表示操作资源、自描述消息、HATEOAS。
- 资源标识：每个资源有一个 URI，客户端通过 URI 定位它。
- 通过表示操作资源：客户端拿着资源的表示（通常是 JSON、XML），结合 HTTP 方法对它进行增删改查。
- 自描述消息：每条消息里应该包含足够让接收方理解它的信息，例如 Content-Type、状态码、必要的元数据。
- HATEOAS：超媒体即应用状态引擎，服务器在响应里返回下一步可执行的操作链接，客户端不要再硬编码流程。
我看到很多团队做到了前两条，但完全忽略了自描述和 HATEOAS。结果就是客户端看文档才能猜出接口返回什么结构，状态码一律返回 200 再把业务错误塞在 body 里，就更别提"根据超链接驱动流程"了。
1.2 为什么要为一个"风格"这么较真
有人会问，我不完全遵守 REST 约束，接口不也能跑吗？确实能跑。但要理解约束的价值，得先想象一个没有这些约束的接口系统会变成什么样。
假如服务端保存会话状态，客户端每次请求都要靠 sessionId 才能让服务器想起来"这人是谁"。一旦流量上来要加服务器节点，就得引入 session 共享、粘性会话这些额外机制。假如接口 URL 是 /api/getUserInfo、/api/updateUserName，每次需求变更都要新增一个 URL，客户端跟着升级，接口数量边增加边腐化。假如状态码全部返回 200、错误靠 body 里的 code 字段区分，那么监控系统、网关、HTTP 客户端缓存都失去了判断依据，整个链路里的每个环节都要额外解析业务层协议。
REST 的约束看起来麻烦，但它们像交通规则一样，在牺牲一部分"自由"的同时换来了更可靠的整体秩序。把网络传输的语义交给 HTTP 标准，把业务表达聚焦在资源上，这是在分布式系统里降低耦合成本的有效方式。所以与其说 RESTful 是教条，不如说它是无数分布式实践沉淀出的边界智慧。
2. 资源设计：URI、集合与关联关系的取舍
2.1 用名词描述资源，把行为藏进 HTTP 方法里
学习 RESTful 时听到的第一条铁律是：URL 里用名词，不用动词。这条说对了一半——藏在这句话背后的真正含义是"系统对外暴露的是资源及其状态，而非函数调用"。
资源是一个业务概念，比如订单、用户、商品、评论。每个资源都应该有一个唯一的 URI，而对这个资源执行什么操作，交给 HTTP 方法表达。所以：
# 推荐：资源名词 + HTTP 方法表达动作 GET /orders # 查询订单列表 POST /orders # 创建订单 GET /orders/123 # 查询单个订单 DELETE /orders/123 # 删除订单 PUT /orders/123 # 替换订单 PATCH /orders/123 # 部分更新订单 # 不推荐：把行为塞进 URL GET /getOrders POST /createOrder POST /updateOrder POST /deleteOrder在 RPC 风格里，接口就是函数名，系统里每新增一个动作就要加一个地址。在 REST 风格里，地址描述的是"东西本身"，可对东西做的事被限制在 HTTP 方法的语义集合里。这个转变的直接好处是接口数量可控、语义可预测。客户端看到一个 /orders，即使没有文档，也能猜出大概支持哪些操作。
当然，"动词不能出现在 URI"不是绝对的。有些动作本质上不是对某个资源的增删改查，而是触发一个流程，例如审批、派单、结账。有人会硬把这些动作映射成资源状态变化，例如创建审批单、更新状态，但在流程动作语义太重时，采用子资源的 RPC 化表达也完全可以接受。RESTful 是一个风格指南，不是镣铐。
2.2 集合、元素与嵌套资源的两种建模思路
资源之间存在层级关系。REST 风格倾向于用 URI 层级结构来表达"从属"关系，例如一个用户下的订单：
GET /users/42/orders # 获取用户 42 的订单列表 GET /users/42/orders/7 # 获取用户 42 下编号 7 的订单这种写法的好处是直观，路径本身就是一种过滤条件。但嵌套层级不宜过深。常见的反例是把所有可关联的东西都往路径里塞，比如 /schools/1/classes/2/students/3/attendance/4，超过两层之后，URL 变得笨重，服务端的路由维护也开始难受。
第二种建模思路是"扁平关联加查询参数"。订单本质上属于用户，但订单本身独立存在，那么可以这样设计：
GET /orders?userId=42 GET /orders/7我在实践中倾向于"层级不超过两层，超过部分用查询参数表达"。原因有三个：第一，URI 是资源空间的地址，不是查询语言的载体，能少嵌套就少嵌套；第二，集合资源的分页、过滤参数在扁平结构里更好设计；第三，扁平结构更利于服务端做权限控制和数据隔离，因为路径越浅，越不容易在中间层漏掉归属校验。
用嵌套还是扁平，没有绝对正确，关键是团队内部形成一致约定。最怕的是同一个系统里一会儿 /users/42/orders，一会儿 /orders?userId=42，客户端开发者会被逼疯。
2.3 查询参数别滥用，它也有边界
查询参数适合表达"筛选、分页、排序、投影"这类只影响表示结果的选项，不适合表达"要执行的动作"。常见设计例子：
GET /orders?status=pending&page=2&pageSize=20&sort=-createdAt GET /products?category=phone&fields=id,name,price这里要留意一点：带查询参数的 URL 可能被缓存系统当成不同的缓存条目，查询条件越多样，缓存命中率越受影响。另外，如果有人把敏感筛选条件放进 URL，请求日志和浏览器历史都会留下痕迹。这在设计内部系统时可能无所谓，但对公网开放接口来说，查询参数设计也需要纳入安全和隐私的考量。
3. HTTP 语义的正确使用：方法、状态码与幂等性
3.1 从 CRUD 到 HTTP 方法，一张表说清楚
HTTP 协议已经定义了语义丰富的方法集合，RESTful 设计的核心工作之一是"把业务操作映射到正确的 HTTP 方法上"。下图是我在团队内部做接口评审时常用的对照表：
| HTTP 方法 | 语义 | 对应操作 | 幂等性 | 响应状态码 |
|---|---|---|---|---|
| GET | 获取资源表示 | 查询 | 幂等 | 200 |
| POST | 在集合下创建新资源或触发处理 | 创建/动作 | 非幂等 | 201 |
| PUT | 用请求体整体替换资源 | 全量更新 | 幂等 | 200/204 |
| PATCH | 对资源做部分修改 | 部分更新 | 不一定幂等 | 200/204 |
| DELETE | 删除资源 | 删除 | 幂等 | 200/204 |
幂等性这个词值得单独拎出来说。简单理解：同一个请求执行一次和重复执行多次，对服务端资源状态造成的影响是一样的。GET 无论查多少次都不会改数据；PUT 把资源整体替换成同一个目标值，执行多次结果一致；DELETE 删掉同一个资源，第一次删掉，第二次虽然可能返回 404，但资源最终状态还是"不存在"，所以也算幂等。POST 不是幂等的，因为每次 POST 都可能创建一个新的资源实例。
幂等性为什么重要？因为分布式系统的网络是不可靠的，请求超时后客户端需要重试。如果 POST 接口没有做好去重，用户点一次"提交订单"按钮因为超时又点了一次，就可能生成两笔订单。常见的做法是让客户端在 POST 请求里带上幂等键（Idempotency Key），服务端通过这个键记住已经处理过的请求，重复请求直接返回上一次的结果。
3.2 状态码不只是"给程序看的"，也是团队协作契约
很多团队的接口把业务错误统一放在 body 里，HTTP 状态码一律 200，理由是"HTTP 通道是通的，只是业务失败了"。这个做法短期看省事，长期看是给自己埋雷。状态码的作用不只是报告"这次请求成不成"，更是在给整个技术链路传递信号——网关、监控、缓存、负载均衡、客户端框架，全都依赖 HTTP 状态码做决策。
该用的状态码大致可以这样分：
- 2xx 成功：200 查询成功，201 创建成功，204 删除或更新后无返回体。
- 4xx 客户端错误：400 请求体格式错误、参数缺失，401 未认证，403 无权限，404 资源不存在，409 状态冲突，422 业务校验不通过。
- 5xx 服务端错误：500 未预期异常，502 网关错误，503 服务不可用。
我自己在项目里有个铁律：能区分到 4xx 的错误，绝不返回 5xx。很多团队把参数校验失败直接 500，这个习惯会让监控系统失真——明明是客户端传错参数，告警却显示服务端异常，大半夜爬起来排查，结果发现是调用方少传了个字段。这类问题可以通过一个简单约定根治：凡是客户端修正参数后就能成功的失败，都属于 4xx。
错误响应体的设计同样重要。别只返回一个 {"code": 40001, "message": "error"}。更实用的做法是给客户端足够的信息来定位问题：
{ "error": { "code": "ORDER_STATE_CONFLICT", "message": "订单当前状态不允许取消", "detail": { "orderId": "123456", "currentState": "SHIPPED" }, "traceId": "a1b2c3d4" } }这里有三个细节值得借鉴：机器可读的错误码放 code，人看的说明放 message，排障线索放 detail 和 traceId。客户端可以根据 error.code 做分支处理，而不是对字符串匹配。
3.3 PUT、PATCH 和 POST 的边界，经常在评审中被吵翻
这三个方法看似清晰，实际特别容易混。举个例子，一个订单资源有 status、amount、address 三个字段。如果客户端要"只改 address"，用 PUT 把整个订单对象传上去，但服务端设计时把"只更新非空字段"写进了逻辑，那 PUT 就退化成了 PATCH。而如果客户端用 PATCH 把整个新订单对象传上去，PATCH 又被用成了 PUT。
我的建议是：PUT 是"整体替换"，语义要求客户端提供资源的完整目标状态；PATCH 是"局部更新"，客户端只需描述要改哪些字段。选哪个，应当由业务上的保证需求决定，而不是看数据量大小。如果你要求客户端无论怎么改，最终提交的都是完整对象，那就用 PUT；如果业务经常是"只改一个字段"，那就用 PATCH，同时准备好冲突处理策略，因为 PATCH 的并发控制比 PUT 更复杂。
POST 的定位则是"当语义不属于 GET/PUT/PATCH/DELETE 时，默认回到 POST"。创建操作尤其典型：因为客户端无法决定新资源的最终 ID，POST /orders 让服务端在集合下创建对象，资源诞生后返回 201 和 Location 头。触发动作这类场景也常用 POST，比如 POST /orders/123/cancel，这是 REST 的务实妥协——流程动作没法优雅地拆成资源操作时，就用子资源加 POST 表达。
4. 无状态约束：从 Session 到 Token 的演变逻辑
4.1 无状态约束的准确含义
"无状态"是 REST 最容易引起误解的一条约束。它不是说服务端不能存任何数据，而是说服务端不应该保存"客户端会话状态"。也就是说，服务端不依赖内存里的 session 来记住"这个用户上次干到哪一步了"。每一个请求都必须携带足够的上下文，让服务端独立完成这次处理。
区分两个概念：Resource State（资源状态）和 Session State（会话状态）。订单数据、库存数据属于资源状态，原本就该存在数据库里；用户当前选中的购物车、登录状态则属于会话状态，REST 要求这类状态不要留在服务端进程内。移动端时代大家普遍能理解无状态的好处，但项目从 Session 迁移到 Token 的过程里，还是能看到一些半吊子设计：Token 确实不用服务端存了，却在数据库里建了一张 Session 表，内存和数据库两头不讨好。
4.2 无状态到底换来了什么
无状态最大的红利是水平扩展。传统 Session 方案下，同一个用户的请求每次都要命中同一台服务器，否则 Session 就丢了，于是要引入粘性负载均衡或者 Session 复制，这些问题随着节点增多会越来越麻烦。无状态接口下，每一个节点都是同等的，任何节点都能处理任何请求，负载均衡器可以随便分发，宕机节点也能安心摘除。
无状态还带来了流程上的透明度。因为请求自包含，网关、日志、监控都可以完整地把一次请求的信息串起来；对客户端来说，它不需要跟服务器保持一个长连接来维持"对话状态"，需要什么就请求什么，缓存和重试都变得更简单。
有人会反问：登录状态放到 JWT 里，JWT 里的数据和数据库相比不是冗余吗？这是权衡后的选择。JWT 确实带来了服务端无状态、客户端自包含的好处，但也引入了 token 失效不及时、payload 膨胀等问题。所以现代架构里往往不是纯粹的"全有或全无"，而是把长期会话状态收敛到 Redis 这类集中存储，同时用短期的 token 避免在请求里反复查库。这条实践本身已经偏离了严格 REST 的无状态理想，但工程上确实更省事。
4.3 无状态设计的实际落地手法
要在设计接口时保持无状态，可以把握几个原则：
第一，认证信息放请求头，不放 URL，不放业务字段。用 Authorization 头携带 token，代理层和业务层统一取用。
第二，分页游标、筛选条件这类"会话上下文"以参数形式显式传。比如"加载下一页"不再依赖服务端记住"上次查到哪了"，而是客户端把上一页返回的游标原样传回来。
第三，不要把客户端状态默认为"服务端记得"。接口的参数设计尽量完整，避免类似"上一个请求设置过筛选条件，这个请求默认沿用"的隐式约定。
我在早期项目里犯过一个具体错误：做了一个"导入任务"接口，用户先 POST 文件，再轮询 GET 任务进度。第二个接口能知道任务状态，是因为服务端把任务存进了数据库，这本身没问题。问题在于我给了导入的任务列表一个"默认只显示最当前任务"的逻辑，也就是依赖会话里"最近一次上传"这个状态，结果多用户同时上传时互相看到对方的任务。后来改掉这个隐式依赖，让客户端必须显式传 taskId，问题立刻消失。这个小坑很能说明"无状态约束"不只是理论，它直接影响并发场景下的正确性。
5. 通用模式落地：分页、过滤、排序与版本管理
5.1 分页：偏移量快照与游标三种方案
接口一旦遇到集合数据，分页是躲不开的。常见的有三种：
| 方案 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| 偏移量分页 | page=2&size=20 | 实现简单，可以随意跳页 | 数据增删时顺序漂移，深层翻页慢 |
| 基于快照分页 | page=2&size=20&updateTime=xxx | 以某个时间点做基准，翻页稳定 | 需要服务端记录快照状态，逻辑复杂 |
| 游标分页 | cursor=eyJpZCI6MTAwfQ&size=20 | 稳定，性能好，适合海量数据 | 无法随机跳页 |
我现在的默认选择是游标分页，尤其是数据量上来之后。偏移量分页在表数据超过几十万行时，深翻页会触发数据库 offset 全扫描，这个性能损耗在接口层面几乎无解。游标分页的代价只是"不能直接跳到第 N 页"，但对绝大多数 C 端场景，用户根本不需要精确跳页，只需要"下一页"和"回到顶部"。如果产品真的需要随机访问某一页，通常是数据量没那么大，偏移量分页配合合理索引也能接受。
分页接口的响应里，除了数据列表，还应该带上 nextCursor、total（如果计算代价可接受）等元信息。这属于 RESTful 里"自描述消息"的落地——客户端不需要额外约定就知道"有没有下一页"。
5.2 过滤、排序与字段投影，参数规范统一才有价值
集合资源的筛选条件放在查询参数里，这是共识。但参数怎么命名、排序怎么表达，团队里往往很快就开始混乱。我建议定几个简单的团队规则：
- 过滤字段用资源属性同名：/orders?status=paid，status 就是订单模型的属性名。
- 范围过滤用 gte/lte 后缀：price_gte=100&price_lte=500。
- 排序用 sort 参数，正序属性名，倒序加负号：sort=-createdAt,price 表示按创建时间倒序、再按价格正序。
- 字段投影用 fields 逗号分隔：fields=id,status,amount 减少大对象传输。
这些规则不复杂，但要在 API 设计评审时当作契约固定下来，否则就会出现 /getOrders?orderDateFrom=xxx、?order_by=xxx 这类各自为政的写法。客户端对接多个系统时，参数风格越一致，学习成本越低。
字段投影还有一个容易被忽视的收益：它让接口更容易兼容多端差异。同样是订单列表，列表页只需要 id 和 status，详情页才需要地址和支付明细。一个 fields 参数就能让客户端按需取数，省流量也省服务端序列化时间。
5.3 版本管理：URI 版本号 / 请求头版本号，别在舒适区里纠结
接口一定会变。只要一变，就会遇到老客户端兼容的问题。版本管理是 RESTful 实践里绕不开的主题，主流的做法就两种：
一是 URI 路径版本号：/v1/orders、/v2/orders。优点是直观、容易做日志分析和监控，缺点是把"版本"变成了资源寻址的一部分，严格 REST 视角下不优雅，但工程上非常实用。
二是请求头或媒体类型版本号：Accept: application/vnd.myapp.v2+json。优点是干净，符合 REST 的"资源 URI 唯一"理念，缺点是调试困难，客户端框架对自定义 Accept 支持不一，监控日志里也很难一眼看出客户端用的是哪个版本。
我的经验是：对外公共 API 优先用路径版本号，团队内部服务、移动端和云端一体的场景可以考虑请求头版本号。原因很现实——公共 API 的调用方技术栈五花八门，路径版本号对谁都是零门槛的；而内部 API 大家都用约定好的 SDK，请求头版本号反而能避免在路径里堆叠版本数字。无论选哪种，都要约定好"新版本发布后旧版本的生命周期"，我在维护一个对外接口时把老版本定在发布新版本后一年下线，并在响应头里加 Deprecation 标记，这样客户端团队和运维都能及时感知。
6. 实战踩坑：我对 RESTful 设计的个人实践体会
6.1 别把所有接口强行 REST 化
虽然这篇文章是在讲 RESTful，但我必须诚实地说：不是所有接口都适合 REST。搜索接口天然是查询动作，GET /search?q=xxx 没问题；但发送短信验证码、导入 Excel 文件这类流程性操作，硬拆资源反而别扭。我在某个项目里做过一个"生成报表并发送邮件"的接口，起初按理想方式拆成 POST /reports 和 POST /reports/{id}/send，两个步骤给客户端带来了额外的协调成本，后来前端同学直接对我说："你能不能给我一个 POST /report-generation/jobs 之后就完了？"
RESTful 是优秀的默认风格，但它不是唯一答案。架构设计的本质是在约束和便利之间做权衡。我的判断标准是：如果资源模型和业务场景契合度高，就用 REST；如果业务是强流程、强动作，那在局部使用 RPC 风格的端点，也不要背负心理负担。成熟的团队应该在规范里写明"哪些场景允许跳出 REST 约束"。
6.2 最容易忽视的约束是"自描述消息"
很多接口虽然叫 RESTful，但客户端在我这里接到的第一个抱怨永远是"文档和实际返回对不上"。根子在于服务端返回的 JSON 没有真正做到自描述。字段含义、单位、枚举取值、时间格式全靠文档口头约定，一旦文档滞后，接口就变成了黑盒。
我后来在两个地方做了改进，效果很明显。第一，所有枚举字段在接口文档和响应示例里同步暴露可接受值，不允许只写"具体见某某文档"。第二，所有带单位或格式的字段在命名上显式带上单位和时区，比如 durationMs、expiredAtUTC，或者干脆在响应里增加统一的元信息块声明时区。这类细节看似琐碎，但它是"自描述消息"约束落到实处的样子——客户端拿到消息，不需要查外部文档就能理解大部分含义。
6.3 查询参数会扩大攻击面，设计时要同步考虑权限和限流
RESTful 接口把查询条件暴露成参数后，攻击者可以自由组合参数去探测数据。例如 /orders?userId=42，如果服务端没有对 userId 做归属校验，就存在越权遍历的风险。这类问题在 RPC 接口时代同样存在，但 RESTful 的"资源可预测"特性会放大它——URL 太规整了，猜起来太容易。
我的建议是：凡是按用户维度过滤的查询，优先从认证信息里取 userId，不要信任请求里的 userId 参数；确实需要管理员代查时，单独校验角色权限。另一个容易被忽略的是排序和字段投影参数：如果直接用 sort 字段拼接 SQL，就有注入风险，而且字段投影参数允许任意传值，可能导致服务端错误地暴露内部字段。这些点都应在代码评审里作为固定检查项。
6.4 从零启动一个 RESTful 接口的推荐步骤
如果是新项目，我通常建议团队按下面这个顺序推进接口设计，而不是先打开编辑器写 Controller：
- 梳理业务对象清单，圈出真正的资源（用户、订单、商品），区分出流程动作（发送、审批、导入）。
- 为每个资源画出状态与操作矩阵，明确创建、查询、更新、删除分别对应哪个 HTTP 方法。
- 设计 URI 骨架，确定集合、元素、子资源的层级，避免超过两层。
- 为每个接口确定请求参数、响应结构、错误码、分页和排序方式。
- 最后再进入编码阶段，并且把接口设计评审作为必需的流程。
我自己踩过的最大教训是"让代码先跑起来，接口设计边写边改"。结果系统上线三个月后发现早期接口的参数命名和返回结构已经乱成一锅粥，再想梳理，就要同时改客户端和服务器。前期多花一两天做资源建模，后期省下的返工时间远不止一两天。
结尾
关于 RESTful 架构基础，我最后想说的是：它既不像很多人讲得那么玄，也不是"URL 好看一点"那么简单。它的价值在于为你提供一套思考分布式接口的框架——资源边界划在哪、状态该由谁保存、错误应该被谁看见、缓存和重试怎么才安全。这些问题的答案，会在你真正维护一个长命系统时一遍遍被验证。
对我个人而言，收获最大的一课不是学会了某个具体模式的写法，而是意识到"架构风格"本质上是一种沟通契约：它让团队里的每个人在评审接口时面前有一张共同的检查清单，而不是各自拍脑袋。如果你正在设计新接口，不妨先别急着写代码，拿这篇文章里的约束和方法，把你手头的接口设计过一遍——至少把方法映射、状态码、错误结构统一起来，你会发现后端和前端之间的摩擦会肉眼可见地减少。
