RESTful API 是目前互联网服务中使用最广泛的一种 API 设计风格。它具有简单易用、高效灵活、易于扩展等特点，是当今 Web 开发、移动应用以及云计算等领域不可或缺的一部分。在设计 RESTful API 时，一个重要的问题就是如何正确地设计 URL，本文将会深入探讨如何设计出合理、易用、易理解的 RESTful API URL。
何为 RESTful API
RESTful API，是一种 Web API 的设计风格，它定义了一组架构约束，以保证互联网中的各种应用程序能够按照一定的规则进行交互。RESTful API 使用 HTTP 操作，具有自描述性、无状态、可缓存、分层系统、统一接口等特点。
设计原则
RESTful API 的设计原则分为两个部分：服务器和客户端。
服务器端：
- 对于每个资源，使用唯一的 URL 作为标识。
- 使用 HTTP 动词来描述操作。
- 使用 JSON 格式进行数据交换。
客户端：
- 对于用户来说，URL 应具有描述性，易于理解。
- URL 应当便于使用和记忆，最好是短的且能够自解释。
URL 设计规范
在具体设计 URL 时，可以采用以下规范：
小写字母
在 RESTful API 中，URL 应使用小写字母。
例如：
-- -------------------- ---- ------- -- -- ----------------------------- ------------------------------- ---------------------------- -- --- ----------------------------- ----------------------------- -----------------------------
使用连字符
在 RESTful API 中，URL 应该使用连字符。
例如：
-- -------------------- ---- ------- -- -- ----------------------------- ------------------------------- ---------------------------- -- --- ----------------------------- ----------------------------- -----------------------------
类型不应出现在 URL 中
通常，URL 正文应该是指一种资源。
例如：
// 好的 https://example.com/api/posts https://example.com/api/posts/1 // 不好的 https://example.com/api/post https://example.com/api/posts1 https://example.com/api/posts-one
具有描述性
URL 应该要具备描述性，让人能够在看到 URL 后便能够猜测出这个 URL 所表示的资源是什么。
例如：
// 好的 https://example.com/api/posts/1 https://example.com/api/posts/1/comments/3 // 不好的 https://example.com/api/p https://example.com/api/get-post https://example.com/api/123
不同操作由 HTTP 方法进行描述
在 RESTful API 中，我们将具体的 HTTP 方法与资源 URL 关联起来，再通过 HTTP 方法来描述对资源进行的具体操作。
例如：
GET：获取资源信息。 POST：创建新的资源记录。 PUT：修改已存在的资源信息。 DELETE：删除资源记录。
资源层级应有层次结构
RESTful API 中，资源路径的组织应该是一种包含层次结构的方式，使之更加易于理解。
例如：
// 好的 https://example.com/api/users/123/accounts https://example.com/api/users/123/accounts/1 // 不好的 https://example.com/api/getAccountByUserId/123 https://example.com/api/user/123/account/1
参数应放在请求体中
在 RESTful API 中，尽可能的避免在 URL 上使用参数，因为这样会让 URL 变得冗长、不易阅读，而将需要的参数放在请求体中是一种更好的方式。
例如：
-- -------------------- ---- ------- -- -- ---- ----------------------------- -------- ------------- ---------------- - --------- ----- ------- -------- ---- --- -- ------------ ------- -- ----- -- ------- ------- ---------- ------ - -- --- ------------------------------------------------------------------------------------------------------------------------------------------------
示例代码
示例代码将使用 Express 来实现相应的 RESTful API。
-- -------------------- ---- -------
-- --------
----- ------- - -------------------
----- ---------- - -----------------------
----- --- - ----------
-- -- ---- ----
---------------------------
-- ---- ----- --------
----------------- ------------- ---- ----- -
-- -----------
---------------- - ---- ------- -------- ------- -------- ------- -
-- ------- ----- ------
-- - ---- --------
------------------
---
---
-- ---- ----- ---------
------------------------- ------------- ---- ----- -
-- -- ------ -----
---------------- - ---- ----- ----- -- - --- -------------------- -------- ------- -------- ------- -
-- ------- ----- ------
---------------------
---
---
-- -----
------------------ ------------- ---- ----- -
-- ------------
---------------- ---- ----- ----------- --------- ------ --- ---- -------------------- ------------------- -------- ------- -------- ------- -
-- ------- ----- ------
-------------------
---
---
-- ------
------------------------- ------------- ---- ----- -
-- -------
---------------- ----- --- --------- - -- -------- - - ----- -- - --- -------------------- ------------------ ------------------- -------- ------- -------- ------- -
-- ------- ----- ------
-------------------
---
---
-- ----
---------------------------- ------------- ---- ----- -
---------------- ---- ----- ----- -- - --- -------------------- -------- ------- -------- ------- -
-- ------- ----- ------
------------------- ----- ------- -----------------
---
---
-- ---------
---------------- ---------- -
------------------- -- ------- -- ---- -------
---结论
设计好 URL 对于 RESTful API 的成功使用和易用性至关重要。本文提供了不同的 URL 设计规范来帮助您设计良好的 RESTful API。
在设计好 URL 后，还需要考虑其他因素，例如数据类型、HTTP 方法、错误处理等等。我们应该将对 RESTful API 的设计视为一项长期的过程，并不断进行优化、演进。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/673941b8317fbffedf15e057