从 URI 到 RESTful API 的设计之路

随着互联网的发展和应用场景的多样化，API 的设计变得越来越重要。其中，RESTful API 是一种最常用、最基础的 API 设计风格。本文将从 URI 开始，详细探讨如何设计 RESTful API，并提供一些相关示例代码。

URI 是什么？

URI（Uniform Resource Identifier，统一资源标识符）是一个字符串序列，用于标识互联网上的资源。URI 包含两个重要的子集：URL（Uniform Resource Locator，统一资源定位符）和 URN（Uniform Resource Name，统一资源名称）。其中，URL 指定了资源的位置，而 URN 指定了资源的名称。

RESTful API 的设计原则

在理解 URI 后，我们可以开始考虑如何设计 RESTful API。根据 Roy Fielding 的博士论文，RESTful API 应该遵循以下几个设计原则：

  1. 客户端-服务器架构：客户端和服务器之间应该有明确的分离，使得它们可以独立地演化和扩展。
  2. 无状态：服务器不应该存储客户端的状态，每个请求都应该包含足够的信息来让服务器理解。
  3. 缓存：服务器应该尽可能地可缓存，以减少网络传输。
  4. 统一的接口：RESTful API 应该采用统一的接口，包括资源的标识、资源的操作、自描述消息和超媒体作为应用状态转移的引擎（HATEOAS）。
  5. 按需代码：服务器应该只需要传输客户端所需要的数据。

URI 的设计

在 RESTful API 中，URI 是资源的唯一标识符，其设计应该遵循以下几个原则：

  1. URI 应该体现资源的层次结构，具有清晰、简洁的结构，便于客户端使用。
  2. URI 应该使用名词而非动词，即 URL 应该是对资源的描述，而非对动作的描述。
  3. URI 应该使用小写字母，横线分割单词，以提高可读性。
  4. URI 最好是永久的，不可改变的，避免客户端的混乱。
  5. URI 应该是唯一的，以避免歧义和冲突。

以下是一些 URI 设计的示例。

GET a user's profile

--- -----------

CREATE a new user

---- ------

UPDATE a user's information

--- -----------

DELETE a user

------ -----------

RESTful API 的响应

在使用 RESTful API 时，服务器应该返回一些有意义的信息，以帮助客户端理解。以下是 RESTful API 响应的各个部分。

1. 状态码

状态码用于表示请求的处理结果。以下是一些常见的状态码：

  • 200 OK：请求成功
  • 201 Created：请求成功，并且服务器创建了新的资源
  • 400 Bad Request：请求无效，缺少必需的参数
  • 401 Unauthorized：请求需要用户身份验证，但未提供有效的凭据
  • 403 Forbidden：请求被禁止，没有足够的权限访问资源
  • 404 Not Found：请求的资源不存在
  • 500 Internal Server Error：服务器发生错误

2. 响应头

响应头包含一些元数据，如内容类型、过期时间和缓存控制等。

3. 响应体

响应体包含实际的数据，一般使用 JSON 或 XML 格式。

RESTful API 的示例代码

以下是一个使用 Node.js 和 Express.js 实现的 RESTful API 示例代码。这个示例实现了一个简单的用户管理系统。

安装 Node.js 和 Express.js

--- ------- ------ ------- -------- ----------- ------------ -------- -------

创建 Express.js 应用

----- ------- - -------------------
----- -------- - --------------------
----- ---------- - -----------------------
----- ------ - --------------------
----- --- - ------------------------

----- --- - ----------

------------------------------- --------- ---- ----
---------------------------

--------------------------------------------------- -
  ---------------- -----
  ------------------- -----
  --------------- -----
---

----- ---------- - -----------------
  --------- - ----- ------- --------- ----- ------- ---- --
  --------- - ----- ------- --------- ---- --
---

----- --------- - ---------------------- ------------

-- ----
----- ------------ - ----- ---------- -- -
  ----- ---- - ----- -------------------
  ----- ---- - ----- --------------------- ------
  ------ -----
--

-- -- -----
----- ------------- - ------ -- -
  ------ ---------- --------- ------------- -- ----------
--

-- -- -----
----- ----------------- - ----- ---- ----- -- -
  ----- ---------- - -----------------------------
  ----- ----- - ---------- -- ------------------ ------
  -- ------ -- ----- ------ --------------------
  ----------------- --------- ----- ----- -- -
    -- ----- ------ --------------------
    -------- - -----
    -------
  ---
--

-- ----
---------------------- ----- ----- ---- -- -
  ----- - --------- -------- - - ---------
  ----- ---- - ----- -----------------------
  ----- ------- - --- ----------- --------- --------- ---- ---
  --- -
    ----- ---- - ----- ---------------
    ---------------------------
  - ----- ------- -
    ---------------------- ------ ------------- ---
  -
---

-- ------
--------------------- ------------------ ----- ----- ---- -- -
  --- -
    ----- ----- - ----- -----------------
    ----------------
  - ----- ------- -
    ---------- ------ ------------- ---
  -
---

-- ------
------------------------- ----- ----- ---- -- -
  ----- -- - --------------
  --- -
    ----- ---- - ----- -----------------------
    -- ------ -
      ---------------
    - ---- -
      ---------------------- ------ ----- --- ------ ---
    -
  - ----- ------- -
    ---------------------- ------ ------------- ---
  -
---

-- ------
------------------------- ----- ----- ---- -- -
  ----- -- - --------------
  ----- - --------- -------- - - ---------
  ----- ---- - ----- -----------------------
  --- -
    ----- ---- - ----- ----------------------------
      ---
      - --------- --------- ---- --
      - ---- ---- -
    --
    -- ------ -
      ---------------
    - ---- -
      ---------------------- ------ ----- --- ------ ---
    -
  - ----- ------- -
    ---------------------- ------ ------------- ---
  -
---

-- ------
---------------------------- ----- ----- ---- -- -
  ----- -- - --------------
  --- -
    ----- ---- - ----- --------------------------------
    -- ------ -
      ---------------
    - ---- -
      ---------------------- ------ ----- --- ------ ---
    -
  - ----- ------- -
    ---------------------- ------ ------------- ---
  -
---

-- -- ---------- --
---------------- -- -- -
  ------------------- ------- -- ---- -------
---

总结

本文介绍了从 URI 到 RESTful API 的设计之路。只有遵循良好的设计原则和规范，才能创建出易于维护和扩展的高质量 API。希望读者能够通过本文学习到 RESTful API 的基本设计方法和一些最佳实践，并在实践中掌握相关技术。

来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/6546ff977d4982a6eb164819

阅读全文

猜你喜欢

  • 在 ES6 中使用 Map 对象实现数据存储

    在前端开发中，我们经常需要处理大量的数据，包括各种类型的数据结构。ES6 中新增了一个 Map 对象，可以方便地实现数据的存储和访问。本文将详细介绍在 ES6 中使用 Map 对象实现数据存储的方法和...

    1 年前
  • Deno 中如何使用 WebSocket 心跳检测

    在前端开发中，WebSocket 是一种非常重要的实时通信协议。然而，在 WebSocket 通信过程中出现意外断开连接的问题，给开发带来了一定的挑战。为了解决这个问题，我们可以使用 WebSocke...

    1 年前
  • ES8 的 Promise.prototype.finally() 方法

    Promise 是实现异步编程的一种方式，通过它我们可以更容易地处理异步操作并避免回调地狱。ES8 中引入了 Promise.prototype.finally() 方法，允许我们在一个 Promis...

    1 年前
  • webpack2 + babel-loader + react-hot-loader：无法加载组件

    本文主要介绍如何使用 webpack2、babel-loader 和 react-hot-loader 解决在开发过程中，无法实时加载组件的问题。同时，我们还会提供一些示例代码，供读者参考。

    1 年前
  • ES12 中的 Function.toString 方法解析

    ES12 中的 Function.toString 方法解析 在 JavaScript 中，Function.toString() 方法是用于获取函数代码的字符串表示形式。

    1 年前
  • 如何使用 ESLint 规则约束开发工具 chain 规则

    在前端开发中，我们经常会使用开发工具来提高开发效率，其中 chain 是一个流畅的函数式工具，它可以帮助我们以函数链式调用的方式对数组进行各种操作。但在使用 chain 时，我们可能会遇到一些语法错误...

    1 年前
  • ECMAScript 2020："大管家"BigInt

    ECMAScript 2020："大管家"BigInt 随着数字领域的发展，JavaScript 也有了两个新的数值类型： BigInt 和 Number。在 JavaScript 中，每个数字都是一...

    1 年前
  • 使用 Fastify-Webpack-HMR 实现前端热更新

    在前端开发中，热更新是一个非常有用的功能。它可以帮助开发人员提高效率，减少开发时间，并且更快地推出项目。在本文中，我们将介绍如何使用 Fastify-Webpack-HMR 实现前端热更新。

    1 年前
  • Material Design 中 RecyclerView 各种 Item 布局实现详解

    前言 在移动端应用开发中，RecyclerView 是一个非常流行的组件，它提供了高度的灵活性和性能优化，使得在大数据集下的快速滑动和数据变更成为可能。而在 Material Design 设计规范中...

    1 年前
  • 基于 Hapi 框架实现用户认证的方法

    随着互联网的普及，前端技术得到了快速发展。而用户登录认证作为网站必不可少的一部分，也越来越受到前端工程师们的关注。本文将详细介绍如何基于 Hapi 框架来实现用户认证，并提供示例代码及学习参考。

    1 年前
  • 解决 Cypress 在 Safari 中无法找到元素的问题

    前言 Cypress 是一个非常好用的前端自动化测试框架，支持多种常见浏览器，如 Chrome、Firefox 等等。但是在使用 Cypress 进行 Safari 浏览器的自动化测试时，可能会遇到无...

    1 年前
  • Socket.io 与 WebSocket 技术区别详解

    随着现代网络应用程序的兴起，有两种主要的技术出现，Socket.io 和 WebSocket。虽然它们非常相似，但是它们之间有一些重要的区别。本文将深入探讨 Socket.io 和 WebSocket...

    1 年前
  • 使用 Sequelize 在 Node.js 和 MySQL 中实现 ORM

    前言 在 Web 开发中，Object-Relational Mapping（ORM）是一个不可或缺的部分。ORM 将数据库变成对象，通过面对对象的方式进行访问和操作。

    1 年前
  • ES7 中 fetch 与 xmlhttprequest 的异同

    ES7中添加了一种新的网络请求api: fetch。在之前的版本中，我们使用XMLHttpRequest（XHR）作为网络请求的主要方法。本文将比较这两种方法的异同点。

    1 年前
  • 自定义 Jest 匹配器实现更灵活的断言

    Jest 是一款流行的 JavaScript 测试框架，它提供了丰富的断言方法用于测试代码的正确性。但是有时候，我们可能需要自定义一些与业务相关的断言方法，这时候自定义 Jest 匹配器就派上用场了。

    1 年前
  • 使用 AngularJS 时如何处理未定义的 $filter？

    本文将详细介绍在使用 AngularJS 开发 Web 应用时，我们如何解决未定义的 $filter 引起的问题。$filter 是 AngularJS 中非常重要的一个服务，它通常用于格式化和修改数...

    1 年前
  • 如何使用 Serverless 快速搭建 Web 应用

    Serverless 是一种新型的云计算模式，它以函数为单位，提供了无服务器的运行环境，可以帮助开发者快速搭建 Web 应用，极大地降低了运维成本和开发难度。本文将介绍如何使用 Serverless，...

    1 年前
  • webpack hash-chunkhash-contenthash 的区别以及使用场景

    如果你是一名前端开发者，那么你一定对 webpack 不陌生。webpack 是一款强大的前端打包工具，可以帮助我们打包和管理各种前端资源，使得项目更加可维护和可靠。

    1 年前
  • PM2 如何使用文件转储功能

    PM2 是一款功能强大的 Node.js 进程管理工具，可以管理多个 Node.js 应用程序，提供了丰富的功能，例如进程守护、自动重启、负载均衡等。而其文件转储功能可以帮助我们更好地管理日志文件，可...

    1 年前
  • 使用 Deno 的 Http Server 库构建 Web 应用

    作为一名前端开发者，我们可能会选择 Node.js 作为后端开发工具，但是最近更新的一个新兴技术，Deno，已经被越来越多的开发者所青睐。Deno 是一款基于 Rust 和 V8 引擎的 JavaSc...

    1 年前

相关推荐

    暂无文章