RESTful API 是一种基于 HTTP 协议的 Web API 设计风格，它的设计核心是资源的表达和状态的转移。而 URI（Uniform Resource Identifier，统一资源标识符）作为 RESTful API 中资源的唯一标识符，其设计质量直接影响 API 的可用性、可扩展性和易用性。因此，本文将深入探讨 RESTful API 中 URI 的设计原则和最佳实践，并提供示例代码和指导意义。
1. URI 的组成结构
URI 通常由以下几部分组成：
- 协议（Protocol）：指定访问资源时所使用的协议，如 HTTP、HTTPS、FTP 等。
- 域名（Host）：指定资源所在的服务器的域名或 IP 地址。
- 端口（Port）：指定服务器监听的端口号，默认为 80。
- 路径（Path）：指定访问资源所需的路径，由斜杠分隔的一串字符串。
- 查询参数（Query Parameters）：指定访问资源所需的参数，由问号和一系列键值对组成。
- 锚点（Fragment）：指定文档中的特定位置，由井号和一串字符串组成。
例如，以下 URI 表示访问名为 example.com 的服务器上的 /api/v1/users 路径下的用户列表资源：
https://example.com:443/api/v1/users?limit=10&page=2#user-5
2. URI 的设计原则
URI 的设计应遵循以下原则：
2.1. 可读性
URI 应该易于理解和记忆，以便用户可以轻松地使用 API。一般来说，URI 中应该包含有意义的词语和短语，而不是随意的字符或数字。
2.2. 可预测性
URI 应该遵循一定的约定和规范，以便用户可以预测和推断出资源的位置和属性。例如，URI 中应该使用复数名词表示资源集合，使用单数名词表示单个资源。
2.3. 可扩展性
URI 应该具有可扩展性，以便支持未来的变化和扩展。例如，URI 中应该使用版本号来区分不同版本的 API，而不是在路径中硬编码 API 的名称。
2.4. 唯一性
URI 应该是唯一的，以便标识和访问特定的资源。每个资源应该有一个唯一的 URI，而不是多个 URI 指向同一个资源。
2.5. 安全性
URI 应该具有一定的安全性，以便保护资源不被非授权访问和修改。例如，URI 中应该使用随机生成的 ID 来标识敏感资源，而不是使用易于猜测的数字或字符串。
3. URI 的最佳实践
基于上述设计原则，以下是一些 URI 的最佳实践：
3.1. 使用复数名词表示资源集合
URI 中应该使用复数名词表示资源集合，以便与单个资源区分开来。例如，以下 URI 表示用户列表资源：
GET /api/v1/users
3.2. 使用单数名词表示单个资源
URI 中应该使用单数名词表示单个资源，以便与资源集合区分开来。例如，以下 URI 表示 ID 为 1 的用户资源：
GET /api/v1/users/1
3.3. 使用 HTTP 动词表示操作类型
URI 中应该使用 HTTP 动词表示操作类型，以便与资源的状态转移相对应。例如，以下 URI 表示创建用户资源：
POST /api/v1/users
3.4. 使用查询参数表示可选参数
URI 中应该使用查询参数表示可选参数，以便用户可以根据需要进行筛选和排序。例如，以下 URI 表示返回前 10 个用户资源：
GET /api/v1/users?limit=10
3.5. 使用 URI 模板表示动态参数
URI 中应该使用 URI 模板表示动态参数，以便支持不同的参数组合和格式。例如，以下 URI 表示搜索用户资源：
GET /api/v1/users/search?q={query}&sort={sort}3.6. 使用版本号区分不同版本的 API
URI 中应该使用版本号区分不同版本的 API，以便支持向后兼容和升级。例如，以下 URI 表示访问 v1 版本的用户资源：
GET /api/v1/users
3.7. 使用 SSL/TLS 加密保护敏感资源
URI 中应该使用 SSL/TLS 加密保护敏感资源，以便保护资源不被非授权访问和修改。例如，以下 URI 表示访问加密的用户资源：
https://example.com/api/v1/users/1
4. 示例代码
以下是一个使用 URI 最佳实践的示例代码：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ---------- - ----------------------- ----- --- - ---------- --------------------------- -- --- ------------- ------------------------ ----- ---- -- - ----- - ------ ---- - - ---------- -- ----- ------ ---- -- ----- --- -- --- --------------- ---------------------------- ----- ---- -- - ----- - -- - - ----------- -- ----- ------ ---- ---- ----- -- --- -- ---- ------------- ------------------------- ----- ---- -- - ----- - ----- ----- - - --------- -- ----- ------ --- ---- ---- ----- ---- --- ----- --- -- --- --------------- ---------------------------- ----- ---- -- - ----- - -- - - ----------- ----- - ----- ----- - - --------- -- ----- ------ ---- ---- ----- -- --- --- ---- --- ----- --- -- ------ --------------- ------------------------------- ----- ---- -- - ----- - -- - - ----------- -- ----- ------ ---- ---- ----- -- --- ---------------- -- -- - ------------------- ------- -- ---- ------- ---
5. 指导意义
- URI 的设计是 RESTful API 设计中重要的一环，应遵循可读性、可预测性、可扩展性、唯一性和安全性等原则和最佳实践。
- URI 的设计应该与资源的状态转移相对应，使用 HTTP 动词表示操作类型，使用查询参数表示可选参数，使用 URI 模板表示动态参数，使用版本号区分不同版本的 API，使用 SSL/TLS 加密保护敏感资源等。
- URI 的设计应该易于理解和记忆，以便用户可以轻松地使用 API。同时，URI 的设计应该具有可扩展性，以便支持未来的变化和扩展。
- URI 的设计应该遵循一定的约定和规范，以便用户可以预测和推断出资源的位置和属性。同时，URI 的设计应该具有一定的安全性，以便保护资源不被非授权访问和修改。
- URI 的设计应该根据具体业务和需求进行调整和优化，以便满足用户的实际需求和使用场景。同时，URI 的设计应该与 API 的整体设计相协调，以便提高 API 的可用性、可扩展性和易用性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67d3d68fa941bf71347409cb
