在现代 Web 应用程序中，RESTful API 已成为了一种确保 Web 应用程序正确处理和利用资源的标准。
RESTful API 的架构设计需要在几个方面上考虑，如表现层、状态转移和资源的引用。本文将在这些方面深入探讨，希望能够提供关于优雅的 RESTful API 的架构设计的详细指导意义。
1. 表现层
表现层是 RESTful API 的构建块之一，它定义了 API 所支持的所有文章、media类型以及状态码。在实践中，我们经常看到 JSON 格式的 API 响应，因此，JSON 是绝大多数 RESTful API 的表现层的首选。
我们可以通过以下几个方面来优化表现层的设计：
1.1. 优美的 URL 设计
RESTful API 的 URL 应该看起来易于理解，并且应该通过动作和资源名称来定义。这使得 API 的用户可以快速了解 API 的功能和用法。
以下是优美的 URL 设计的一些设计准则：
- 路径应该是有意义的和可读的
- URL 中使用的动词应该是 RESTful 规范支持的 GET、POST、PUT、PATCH 和 DELETE
- 在 URL 中使用名词表述 API 资源
例如，以下是一个良好的 URL 设计示例：
/api/posts/123
这个 URL 表示获取 ID 为 123 的文章、评论等。
1.2. 状态码的正确使用
状态码是 RESTful API 中的另一个重要组成部分之一。状态码应该清晰地表达了 API 的执行结果，以便于客户端可以做出适当的响应。
以下是状态码的一些使用准则：
- 成功的操作应该返回 2XX 状态码
- 需要对客户端进行处理的响应应该返回 4XX 状态码
- 服务器端错误应该返回 5XX 状态码
例如，以下是使用状态码的示例：
- 成功地创建一个新文章：201 Created
- 请求参数错误：400 Bad Request
- 未授权访问请求：401 Unauthorized
- 禁止访问请求的资源：403 Forbidden
- 找不到请求的资源：404 Not Found
- 服务器端错误：500 Internal Server Error
1.3. 使用 JSON 格式响应
使用 JSON 格式作为 RESTful API 的首选响应格式始终是一个好主意。
以下是一些关于使用 JSON 格式响应的准则：
- 始终使用 UTF-8 编码
- 如果响应可以是空的，那么应该返回一个空 JSON 对象，例如 {}
- 始终使用最小化的 JSON 表示，以减少带宽
例如，以下是使用 JSON 格式响应的示例：
-- -------------------- ---- -------
-
----- ----
-------- -------- --- -------
---------- ---- --- ------------- --- -------- --- -------------------
--------- -
------- --------
-------- -------------------
--
--------------- ---------------------------
------- ------- ----------
-2. 状态转移
状态转移是 RESTful API 的另一个核心部分。状态转移指的是 Web 应用程序通过 URI、HTTP 方法和 HTTP 状态码来操作资源，并在它们之间进行状态转移。
以下是一些优化状态转移的建议：
2.1. 使用 HTTP 方法
RESTful API 中最常用的 HTTP 方法是 GET、POST、PUT、PATCH 和 DELETE。我们应该在使用 RESTful API 时遵循这些 HTTP 方法的约定。
以下是 HTTP 方法的一些使用建议：
- GET 用于检索资源。
- POST 用于创建新资源。
- PUT 用于替换现有资源。
- PATCH 用于更新现有资源。
- DELETE 用于删除资源。
例如，以下是一个使用 HTTP 方法的示例：
-- -------------------- ---- -------
---- ---------- --------
------------- ----------------
-
-------- -------- --- -------
---------- ---- --- ------------- --- -------- --- -------------------
--------- -
------- --------
-------- -------------------
--
------- ------- ----------
-2.2. 使用 HTTP 状态码
在 RESTful API 中，HTTP 状态码通常用于表示操作状态和结果。
以下是 HTTP 状态码的一些建议：
- 2XX 状态码表示成功的响应，例如 200 OK
- 4XX 状态码表示客户端错误，例如 400 Bad Request 或 404 Not Found
- 5XX 状态码表示服务器端错误，例如 500 Internal Server Error
例如，以下是一个使用 HTTP 状态码的示例：
-- -------------------- ---- -------
-------- --- -------
------------- ----------------
--------- --------------
-
----- ----
-------- -------- --- -------
---------- ---- --- ------------- --- -------- --- -------------------
--------- -
------- --------
-------- -------------------
--
--------------- ---------------------------
------- ------- ----------
-3. 资源引用
在 RESTful API 中，资源引用指的是用 URL 引用另一个资源。资源引用可以让 Web 应用程序管理数据并尽可能少地重复。
以下是一些资源引用的建议：
3.1. 使用嵌套资源
如果资源之间具有层次依赖关系，则可以使用嵌套的 URL 表示它们之间的关系。
例如，以下 URL 表示文章 123 的评论列表：
/api/posts/123/comments
3.2. 使用超媒体
超媒体是一种让客户端自我描述 API 的机制。超媒体通常使用 HTML 或 JSON 等标记语言的扩展来定义链接。
以下是一些超媒体的使用建议：
- 始终包含超媒体链接，以使客户端知道可以在 API 中执行哪些操作。
- 避免硬编码 URL，始终使用可以更改的 URL。
例如，以下是一个使用超媒体的示例：
-- -------------------- ---- -------
-
-------- -------- --- -------
---------- ---- --- ------------- --- -------- --- -------------------
--------- -
------- - ------- ---------------- --
----------- - ------- ------------------------- --
------- - ------- --------------------- --
--------- - ------- ----------------------- -
--
----------- --
-结论
RESTful API 的设计非常重要，因为它对 API 的可用性、可靠性和效率产生巨大的影响。本文提供了关于优雅的 RESTful API 的架构设计的一些详细指导意义，包括表现层、状态转移和资源的引用。在实践中，请务必遵循这些准则，以确保实现一个出色的 RESTful API。
（完）
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/66f611eec5c563ced57f51e9