什么是 RESTful API？它的设计规范是什么？

简化版

RESTful 是一种 API 设计风格：把一切都看成资源，用 URL 定位资源（名词，不带动词），用 HTTP 方法表示操作（GET 查、POST 增、PUT 改、DELETE 删），用 HTTP 状态码表达结果。核心是「URL 表示资源、HTTP 方法表示动作」，让接口语义清晰、统一、可预测。

详细版

REST 的几条核心原则：

资源用 URL 表示，且用名词：/users、/users/1、/users/1/orders，而不是 /getUser、/deleteUser。
用 HTTP 方法表达操作（对同一个资源 URL）：

操作	HTTP 方法	示例
查询列表	GET	`GET /users`
查询单个	GET	`GET /users/1`
新增	POST	`POST /users`
全量更新	PUT	`PUT /users/1`
局部更新	PATCH	`PATCH /users/1`
删除	DELETE	`DELETE /users/1`

用状态码表达结果：200 成功、201 创建成功、204 无内容、400 参数错、401 未认证、404 找不到、500 服务端错。
无状态：每个请求自带所有信息（如 Token），服务器不依赖上下文会话。

完整版教学

一、RESTful 到底解决什么

在 REST 之前，接口命名五花八门：/getUserList、/queryUser、/user_delete、/updateUserInfo……每个人一套，调用方得挨个查文档，没有规律。

RESTful 提供了一套统一约定：既然操作无非「增删改查」，而 HTTP 方法本来就有 GET/POST/PUT/DELETE，那就用方法表示动作、URL 只表示资源。这样接口变得可预测——看到 DELETE /users/1 你不用查文档就知道是「删除 id 为 1 的用户」。它的价值是一致性和自描述性，降低沟通和理解成本。

二、最关键的一条：URL 用名词，动作交给 HTTP 方法

这是 RESTful 最核心、也最容易违反的规范。URL 里不应该出现动词：

❌ 反例（动词在 URL 里）：
POST /createUser
POST /deleteUser?id=1
POST /getUserList

✅ RESTful：
POST   /users        创建用户
DELETE /users/1      删除用户
GET    /users        查询用户列表

同一个 URL /users/1，配不同的 HTTP 方法就表达不同操作。URL 回答「对谁操作」，HTTP 方法回答「做什么操作」，职责分离，清爽统一。

三、用对状态码，别永远返回 200

很多不规范的接口无论成功失败都返回 200，然后在 body 里塞个 {"code": -1}。RESTful 提倡用 HTTP 状态码本身表达结果：

创建成功用 201，而不是 200；
删除成功无返回体用 204；
参数错误用 400，没权限用 403，找不到用 404；
服务端异常用 500。

这样调用方（包括各种 HTTP 工具、监控、网关）能直接根据状态码判断成败，而不用去解析业务 body（HTTP 状态码详见那道题）。

四、RESTful 不是银弹

REST 是风格/约定，不是强制标准，也不是万能：

复杂操作难以套用：有些操作不是简单的增删改查（如「批量导出」「触发一次结算」「登录」），硬套 REST 反而别扭，这时用动词化的端点或 RPC 风格更自然；
多资源聚合、字段裁剪：前端想一次拿多个关联资源、只要部分字段，REST 要么多次请求、要么接口膨胀——这类场景 GraphQL 更灵活；
性能敏感、内部服务：微服务间高性能调用常用 gRPC（基于 HTTP/2 + Protobuf）而非 RESTful。

所以实践中要灵活：对外资源型 API 用 REST，复杂/高性能场景选合适的其他风格。

五、常见误区

❌ URL 里带动词（/getUser、/deleteUser）——URL 应是名词资源，动作用 HTTP 方法。
❌ 所有请求都用 POST——查用 GET、删用 DELETE、改用 PUT/PATCH，语义化。
❌ 无论成败都返回 200——用状态码表达结果（201/204/400/404/500）。
❌ 把 RESTful 当成必须严格遵守的标准——它是风格，复杂场景可用 GraphQL/gRPC。

六、常见误区与追问

考点	正确口径
资源	URL 使用名词表示资源
方法	GET/POST/PUT/PATCH/DELETE 表达动作
状态码	用 HTTP 状态码表达结果
无状态	每个请求自带必要上下文

GET /users/1
POST /users
PUT /users/1
DELETE /users/1

RESTful 的关键是围绕资源建模，而不是把动词都塞进 URL。

误区：RESTful 就是 URL 好看。 它还包括方法语义、状态码、无状态、资源表示和统一接口等约束。
误区：删除用户应设计成 /deleteUser。 更符合资源语义的是 DELETE /users/{id}。
误区：所有接口都返回 200。 应使用 201、204、400、401、403、404、409 等状态码表达不同结果。
追问：PUT 和 PATCH 怎么选？ PUT 偏整体替换，PATCH 偏局部更新。
追问：RESTful 是否要求前后端完全无状态？ 服务端不保存客户端会话上下文；认证信息可通过 token 等随请求携带。
追问：RESTful 不适合什么场景？ 复杂动作、批处理、强 RPC 风格操作可能用 RPC 或 GraphQL 更自然。

七、加强记忆

RESTful 是 API 设计风格：URL 表示资源（用名词，如 /users/1）、HTTP 方法表示操作（GET 查/POST 增/PUT 改/DELETE 删）、状态码表达结果、无状态。核心是「URL 定位资源、方法表达动作」，价值在于一致、自描述、可预测。但它不是银弹，复杂或高性能场景可选 GraphQL、gRPC。

简化版

详细版