RESTful API 的 URI 设计最佳实践-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 的 URI 设计最佳实践

在构建 Web 应用程序时，RESTful API 是非常常用的一种架构风格。其中 API 的 URI 设计十分重要，因为它不仅影响了用户体验，也影响了代码的可读性和可维护性。本文将介绍 RESTful API URI 设计的最佳实践，并提供示例代码作为参考。

一、URI 的基本原则

可读性 URI 应该简明易读，易于理解和记忆。一个好的 URI 应该具有描述性和直观性，让用户一目了然地知道资源的类型和操作。
永久性 URI 应该是永久不变的，因为很多应用程序会保存或缓存 URI，如果 URI 发生变化，则会导致链接失效或产生不必要的错误。
可扩展性 URI 应该设计成可扩展的，方便后续版本的扩展和修改。
资源层次结构 URI 应该采用资源的层次结构来组织。

二、URI 设计规范

使用名词由于 RESTful API 的资源指的是名词，因此 URI 应该使用名词而不是动词。例如，GET /api/users 表示获取用户列表，而非 GET /api/getUsers。
使用复数将 URI 设计成复数形式，表示这是一个资源的集合。例如，/api/users 表示用户资源的集合。
使用斜杠分隔符使用斜杠 / 作为 URI 的分隔符。例如，/api/users/123 表示用户资源的唯一标识符，而非 /api/users-123。
避免使用动词 URI 应避免使用动词来表示操作，而应该使用标准 HTTP 方法来表示。例如，GET /api/users 表示获取用户列表，而非 GET /api/getUsers。
使用查询参数 URI 中可以使用查询参数来过滤、分页和排序数据。例如，/api/users?limit=10 表示获取最多 10 个用户。
不要暴露数据 ID URI 不应该直接暴露资源的 ID，而应该使用唯一的资源识别符 (UUID)。例如，/api/users/1af6d030-6e0e-11ec-8d26-0242ac130003。
使用连字符在 URI 中使用连字符 - 而不是下划线 _ 来分隔单词。例如，/api/user-profiles，而不是 /api/user_profiles。
清晰表达资源之间的关系 RESTful API 中资源之间存在父子关系或者附属关系，这种关系应该在 URI 中表达。例如，/api/companies/123/users 表示获取公司 123 的用户列表。

三、示例代码

获取用户列表

GET /api/users HTTP/1.1
Accept: application/json

获取单个用户

GET /api/users/{userId} HTTP/1.1
Accept: application/json

创建用户

POST /api/users HTTP/1.1
Content-Type: application/json

{
    "name": "John Doe",
    "email": "johndoe@example.com",
    "password": "mypassword"
}

更新用户

PUT /api/users/{userId} HTTP/1.1
Content-Type: application/json

{
    "name": "Jane Smith",
    "email": "janesmith@example.com",
    "password": "newpassword"
}

删除用户

DELETE /api/users/{userId} HTTP/1.1

四、总结

本文介绍了 RESTful API URI 设计的最佳实践，包括 URI 的基本原则、URI 设计规范和示例代码。通过合理的 URI 设计，可以让 API 更易于理解和使用，提高代码的可读性和可维护性。在实现 RESTful API 时，应该遵循这些规范，以便开发出高质量、易于扩展和维护的 Web 应用程序。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/6458d684968c7c53b0b2514b