RESTful规范

RESTful 是一种基于 HTTP 协议设计 API 的规范，核心是通过「HTTP 方法+URL 路径」的组合，以统一、无状态的方式操作资源（如数据、文件等），且返回格式通常为 JSON（或 XML）。

简单来说，就是把 API 中的操作对象（如用户、商品、订单）视为“资源”，用 HTTP 方法表达对资源的“操作意图”，而非通过 URL 路径直接包含动词（如/getUser、/deleteOrder）。

我们以「用户资源（User）」为例，展示 RESTful 风格如何定义不同操作的请求格式，对比传统非 RESTful 写法，更易理解差异：

操作意图	RESTful 请求格式	非 RESTful（不推荐）写法	核心说明
1. 获取所有用户	`GET /api/users`	`GET /api/getAllUsers`	`GET`方法表示“查询”，URL 直接指向资源集合`/users`，无多余动词。
2. 获取单个用户	`GET /api/users/123`	`GET /api/getUser?id=123`	用 URL 路径参数`123`（用户 ID）指定具体资源，而非 URL 带查询参数`?id=123`。
3. 创建新用户	`POST /api/users`	`POST /api/addUser`	`POST`方法表示“新增”，请求体携带用户数据（如姓名、年龄），URL 仍指向资源集合。
4. 更新用户信息	`PUT /api/users/123`（全量更新）	`POST /api/updateUser?id=123`	`PUT`方法表示“全量替换”，需传递该用户的所有必填字段；URL 指定要更新的资源。
5. 部分更新用户	`PATCH /api/users/123`（部分更新）	`POST /api/updateUserName?id=123`	`PATCH`方法表示“部分修改”，只需传递要更新的字段（如仅改姓名）。
6. 删除用户	`DELETE /api/users/123`	`GET /api/deleteUser?id=123`	`DELETE`方法表示“删除”，语义明确，避免用`GET`（`GET`应无副作用）。

资源为核心：URL 中只包含资源名称（复数形式，如/users、/orders），不包含动词（如get、add、delete）。
HTTP 方法表意图：用GET（查）、POST（增）、PUT/PATCH（改）、DELETE（删）表达操作，语义清晰。
无状态：每个请求必须包含所有必要信息（如身份验证 Token），服务器不存储客户端的状态（如“登录状态”）。
统一响应格式：通常用 JSON 返回数据，包含状态码（如业务码code）、提示信息message、数据data，便于客户端解析。
正确使用 HTTP 状态码：如200（成功）、201（创建成功）、400（请求参数错误）、404（资源不存在）、500（服务器错误），而非全用 200。