RESTful API 是一种应用程序编程接口，可使客户端与服务器之间的通信变得更加简单。它采用了基于资源的 URL 并使用 HTTP 动词对这些资源进行操作，具有独立性、可扩展性以及协作性等优点，因此在 Web 开发中被广泛应用。但是，RESTful API 的开发也需要注意一些规范，本文将详细介绍开发 RESTful API 时应遵循的规范，包括 URL 的设计、HTTP 动词的选择、HTTP 状态码的返回、错误处理等。
URL 的设计
URL 作为 RESTful API 的核心，应该遵循一些设计规范。
- 使用小写字母和短横线作为 URL 的命名方式，避免使用下划线或驼峰命名。例如，使用
/user-profile，而不是/userProfile。 - URL 应该明确表示资源和其属性，而不是动作。例如，使用
/users表示用户资源，而不是/get-users或/add-users。 - 避免使用动词在 URL 中，因为 HTTP 动词已经表示了操作。例如，使用
/users/1表示 id 为 1 的用户，而不是/users/get/1。 - URL 中应该避免使用多层嵌套，并尽量保持路径的简洁易懂。例如，使用
/users/1/books表示 id 为 1 的用户所拥有的书籍。
HTTP 动词的选择
HTTP 动词是 RESTful API 标准定义的几种 HTTP 请求方法，其选择应该符合实际操作的含义，遵循以下规范：
- 使用标准的 HTTP 动词，包括
GET、POST、PUT、PATCH和DELETE等。 - 使用
GET方法获取资源，使用POST方法创建资源，使用PUT或PATCH方法更新资源，使用DELETE方法删除资源。尽量避免使用POST或GET代替 PUT 或 DELETE 等。 - 应尽量避免使用自定义动词，以保持 RESTful API 的标准化。
例如，使用 POST 方法创建一个用户：
POST /users
{
"name": "Tom",
"age": 25
}HTTP 状态码的返回
HTTP 状态码是指响应客户端请求的结果，应该返回适当的状态码，以指示操作结果。以下是 RESTful API 常用的状态码：
- 2XX 成功状态码：表示请求成功，包括
200 OK、201 Created等。 - 3XX 重定向状态码：表示资源的 URI 已被更新，需要重新请求，包括
301 Moved Permanently、302 Found等。 - 4XX 客户端错误状态码：表示客户端请求错误，包括
400 Bad Request、401 Unauthorized、404 Not Found等。 - 5XX 服务器错误状态码：表示服务器错误，包括
500 Server Error等。
例如，使用 200 状态码返回用户数据：
GET /users/1 HTTP/ 1.1
Accept: application/json
HTTP/1.1 200 OK
{
"name": "Tom",
"age": 25
}错误处理
RESTful API 的错误处理应该清晰明了，方便客户端进行处理。以下是错误处理的规范：
- 使用标准的 HTTP 状态码和错误消息，以指示错误类型。例如，使用
404状态码表示资源未找到。 - 在 API 响应的 JSON 对象中定义一个
error属性，以包括有关错误的详细信息。 - Json 中的
error属性应该包含以下属性：code，message和data。
例如：
-- -------------------- ---- -------
--- ----------- --------
------- ----------------
-------- --- --- -----
-
-------- -
------- ------------
---------- ----- --- -------
------- ----
-
-总结
以上是开发 RESTful API 时应遵循的规范。遵守 RESTful 规范有助于构建简单、可扩展、易于维护的 API。在设计 URL、选择 HTTP 动词、返回 HTTP 状态码和处理错误方面，都应该遵循规范。开发人员应当在实践中总结经验，不断完善 RESTful API，以提高其效率和可用性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64aa4d2148841e989466f954