Restful 接口设计规范

最新推荐文章于 2025-05-28 09:52:57 发布

yqcoder

最新推荐文章于 2025-05-28 09:52:57 发布

阅读量636

点赞数 10

文章标签： restful 设计规范后端

本文链接：https://blog.youkuaiyun.com/weixin_64684095/article/details/146125549

版权

一、资源与 URL

1. 使用名词表示资源

URL 应该以名词为主，用来表示具体的资源，而不是动词。例如，/users 表示用户资源集合，/users/{id} 表示单个用户资源。

2. 采用复数形式

一般来说，资源的 URL 应该使用复数形式，这样更符合 RESTful 的设计理念，也更直观。如 /orders 而不是 /order。

3. 避免层级过深

URL 的层级结构不宜过深，尽量保持简洁，以便于理解和使用。例如，/api/v1/orders/{orderId}/items 比 /api/v1/orders/{orderId}/related-items/item-list 更清晰。

4. 使用清晰的命名

URL 中的单词应该使用有意义的命名，遵循一定的命名规范，如使用驼峰命名法或下划线分隔单词，提高可读性。

二、HTTP 方法

GET：用于获取资源。例如，`GET /users` 获取所有用户，`GET /users/{id}` 获取单个用户。
POST：用于创建新资源。例如，`POST /users` 用于创建一个新用户，请求体中包含新用户的信息。
PUT：用于更新资源的全部属性。例如，`PUT /users/{id}` 更新指定 ID 的用户的所有信息，请求体中包含完整的用户数据。
PATCH：用于更新资源的部分属性。例如，`PATCH /users/{id}` 可以只更新用户的部分字段，如 `name` 或 `email`。
DELETE：用于删除资源。例如，`DELETE /users/{id}` 删除指定 ID 的用户。

三、状态码

1. 2xx 成功

200 OK：表示请求成功，通常用于 GET、PUT、PATCH 请求。
201 Created：表示资源创建成功，常用于 POST 请求。
204 No Content：表示请求成功，但没有返回内容，常用于 DELETE 请求或某些不需要返回数据的 PUT、PATCH 请求。

2. 4xx 客户端错误

400 Bad Request：表示客户端请求有误，如请求参数不合法、缺少必要参数等。
401 Unauthorized：表示用户未授权，需要提供有效的身份验证信息才能访问资源。
403 Forbidden：表示用户已认证，但没有权限访问资源。
404 Not Found：表示请求的资源不存在。

3. 5xx 服务器错误

500 Internal Server Error：表示服务器内部发生错误，通常是服务器端的代码或配置问题。
503 Service Unavailable：表示服务器暂时不可用，可能是由于服务器维护、过载等原因。

四、数据格式

1. 使用 JSON

推荐使用 JSON 格式作为数据交换的格式，因为它具有良好的可读性和兼容性，易于在不同的平台和语言之间进行解析和处理。

2. 定义清晰的结构

返回的数据应该有清晰的结构，包含必要的字段和信息。例如，对于用户资源，返回的 JSON 数据可能包含 id、name、email 等字段。

3. 错误信息格式

当发生错误时，返回的错误信息应该包含明确的错误码、错误消息和相关的上下文信息，以便于客户端进行处理和调试。例如：{"errorCode": "400", "errorMessage": "Invalid request parameters", "details": {"param1": "Required parameter is missing"}}。