RESTful API - freeCodeCamp.org

REST API 最佳实践——REST 端点设计实例

Chengjun.L — Tue, 04 Jul 2023 03:30:00 +0000

原文： https://www.freecodecamp.org/news/rest-api-best-practices-rest-endpoint-design-examples/

在 Web 开发中，REST API 在确保客户端和服务器之间的顺利通信方面发挥了重要作用。

你可以把客户端看作是前端，把服务器看作是后端。

客户端（前端）和服务器（后端）之间的通信通常不是超级直接的。因此，我们使用一个叫作“应用编程接口”（或 API）的接口，作为客户端和服务器之间的中介。

因为 API 在这种客户端-服务器通信中起着至关重要的作用，所以我们在设计 API 时应该始终考虑到最佳实践。这有助于维护它们的开发人员和那些使用它们的人，在履行职责时不会遇到问题。

在这篇文章中，我将带你了解创建 REST API 时需要遵循的 9 个最佳实践。这将帮助你创建最好的 API，并使你的 API 用户使用起来更容易。

首先，什么是 REST API

REST 是Representational State Transfer 的缩写。它是由 Roy Fielding 在 2000 年创造的一种软件架构风格，用于指导网络的架构设计。

任何遵循 REST 设计原则的 API（应用编程接口）都被称为 RESTful。

简单地说，REST API 是两台计算机通过 HTTP（超文本传输协议）进行通信的媒介，与客户端和服务器的通信方式相同。

REST API 设计最佳实践

使用 JSON 作为发送和接收数据的格式

在过去，接受和响应 API 请求主要是通过 XML 甚至 HTML 完成的。但如今，JSON（JavaScript Object Notation）已经在很大程度上成为发送和接收 API 数据的事实格式。

这是因为，以 XML 为例，对数据进行解码和编码往往有点麻烦——所以 XML 不再受到框架的广泛支持。

例如，JavaScript 有一个内置的方法来通过 fetch API 解析 JSON 数据，因为 JSON 主要是为它而生成的。但是如果你使用任何其他编程语言，如 Python 或 PHP，它们现在也都有解析和操作 JSON 数据的方法。

例如，Python 提供 json.load() 和 json.dumps() 来处理 JSON 数据。

为了确保客户端正确地解释 JSON 数据，你应该在发出请求时将响应头中的 Content-Type 类型设置为 application/json。

另一方面，对于服务器端的框架，许多框架会自动设置 Content-Type。例如，Express 现在有 express.json() 中间件来实现这一目的。body-parser NPM 包也仍然适用于同一目的。

在端点中使用名词而不是动词

当你设计一个 REST API 时，你不应该在端点路径中使用动词。端点应该使用名词，表示它们各自的作用。

这是因为 HTTP 方法，例如 GET、POST、PUT、PATCH 和 DELETE，已经以动词形式执行基本的 CRUD（创建、读取、更新、删除）操作。

GET、POST、PUT、PATCH 和 DELETE 是最常见的 HTTP 动词。还有其他一些动词，如 COPY、PURGE、LINK、UNLINK 等等。

因此，举例来说，一个端点不应该是这样的：

https://mysite.com/getPosts or https://mysite.com/createPost

它应该是这样的： https://mysite.com/posts

简而言之，你应该让 HTTP 动词来处理端点的工作。因此，GET 将检索数据，POST 将创建数据，PUT 将更新数据，DELETE 将删除数据。

用复数名词命名集合

你可以把你的 API 的数据看成是来自用户的不同资源的集合。

如果你有一个像 https://mysite.com/post/123 这样的端点，用 DELETE 请求删除一个帖子，或用 PUT 或 PATCH 请求更新一个帖子，可能是可以的，但它没有告诉用户在这个集合中可能还有一些其他的帖子。这就是为什么你的集合应该使用复数的名词。

所以，不应该是 https://mysite.com/post/123，而是 https://mysite.com/posts/123。

在错误处理中使用状态码

你应该在对你的 API 请求的响应中始终使用常规的 HTTP 状态代码。这将帮助你的用户知道发生了什么——请求是否成功，或者是否失败，或者其他情况。

下面的表格显示了不同的 HTTP 状态代码范围和它们的含义：

状态码范围	含义
100 – 199	信息性回应：例如，102 表示该资源正在处理中
300 – 399	重定向：例如，301 表示永久移动
400 – 499	客户端错误：400 表示错误的请求，404 表示未找到资源
500 – 599	服务器端错误：例如，500 表示内部服务器错误

在端点上使用嵌套来显示关系

很多时候，不同的端点可以相互联系，所以你应该对它们进行嵌套，这样更容易理解它们。

例如，对于一个多用户博客平台，不同的帖子可能是由不同的作者写的，所以在这种情况下，像 https://mysite.com/posts/author 这样的端点会成为一个有效的嵌套。

同样地，帖子可能有各自的评论，所以要检索评论，可以使用 https://mysite.com/posts/postId/comments 这样的端点。

你应该避免超过 3 层的嵌套，因为这可能使 API 不那么优雅和具有可读性。

使用过滤、排序和分页来检索请求的数据

有时，API 的数据库可能非常大。如果发生这种情况，从这样的数据库中检索数据可能非常缓慢。

过滤、排序和分页都是可以在 REST API 的集合上执行的操作。这样只能检索、排序和排列必要的数据，并将其分页，以防服务器请求过载。

以下是一个已过滤的端点的示例：https://mysite.com/posts?tags=javascript。此端点将检索具有 JavaScript 标签的任何帖子。

使用 SSL 保障安全

SSL 指的是安全套接层。这对于 REST API 设计的安全性至关重要。这将保护你的 API，使其更不容易受到恶意攻击。

你还应考虑其他安全措施，包括：使服务器和客户端之间的通信保密，确保使用 API 的任何人不会获得他们请求的以外的数据。

SSL 证书不难加载到服务器上，而且大多数情况下在第一年是免费的。即使需要购买，它们也并不昂贵。

运行在 SSL 上的 REST API 的 URL 与不运行在 SSL 上的 URL 的明显区别是 HTTP 中的 “s”：https://mysite.com/posts 运行在 SSL 上，http://mysite.com/posts 不运行在 SSL 上。

明确版本划分

REST API 应该有不同的版本，所以你不会强迫客户（用户）迁移到新版本。如果你不小心，这甚至可能破坏应用程序。

网络开发中最常见的版本控制系统之一是语义版本控制。

语义版本管理的一个例子是 1.0.0、2.1.2 和 3.3.4。第一个数字代表主要版本，第二个数字代表次要版本，第三个数字代表补丁版本。

许多科技巨头和个人的 RESTful API 通常是这样的：https://mysite.com/v1/ 代表版本 1，https://mysite.com/v2 代表版本 2。

Facebook 的 API 版本是这样的：

Spotify 以同样的方式做他们的版本管理：

并不是每个 API 都是这样的情况。Mailchimp 的 API 版本是这样的：

当你以这种方式创建 REST API 时，你不强制客户端在选择不迁移的情况下迁移到新版本。

提供准确的 API 文档

当你创建 REST API 时，你需要帮助用户（消费者）正确学习并了解如何使用它。最好的方法是为 API 提供良好的文档。

文档应包含：

API 的相关端点
端点的示例请求
在几种编程语言中的实现
不同错误的消息列表及其状态代码

你可以用于 API 文档的最常用工具是 Swagger。你也可以使用 Postman 来记录你的 API，这是软件开发中最常见的 API 测试工具。

总结

在这篇文章中，你了解了在创建 REST API 时需要记住的几个最佳实践。

将这些最佳实践和惯例付诸实践是很重要的，这样你就可以创建功能强大的应用程序，使其运行良好、安全，并最终使你的 API 用户能够更加容易地使用它。

谢谢你阅读本文。现在，去用这些最佳实践创建一些 API 吧。

REST API 设计最佳实践手册——如何使用 JavaScript、Node.js 和 Express.js 构建 REST API

PapayaHUANG — Wed, 25 May 2022 04:54:41 +0000

原文：REST API Design Best Practices – How to Build a REST API with JavaScript, Node.js, and Express.js，作者：Jean-Marc Möckel

在过去几年我创建和使用过不少 API，期间我遇到过优秀的实践方式，也遭遇过极其不好的实践方式，但曙光总是存在。

网上有许多最佳实践相关的文章，但是它们大多数都缺乏实用性。通过少量示例来了解理论是一个好办法，但是我一直都在思考如何通过更实际的例子来展现 API 的应用。

简单的例子确实可以帮助概念的理解，也省去了复杂度。但实际情况往往并不简单，我确信你对此也深有体会。😁

这就是我决定写这个教程的原因。我将过去好的坏的学习经验都融入了到这边文章之中，并提供例子，使文章易读易懂。我们会通过一个又一个最佳实践来创建一个完整的 API。

开始之前的注意事项：

如你所想，最佳实践并不是必须遵从的具体规则。它们是人们逐渐总结出来的有效的惯例，确实有一些成为现在的标准，但这并不意味着你需要百分之一百的采用这些实践。

最佳实践指导如何使 API 更加符合用户（使用 API 的人和其他工程师）的使用习惯、更加安全和提高性能。

请记住不同的项目有不同的实践方法，肯定存在一些情况下你无法遵守这些规范，每一个工程师都应该自己决定使用什么方法。

话不多说，让我们开始吧！

示例项目

图片作者Alvaro Reyes，来自Unsplash

在正式开始在示例中应用最佳实践前，我先简单介绍一下我们要创建什么。

我们将为交叉训练应用（CrossFit Training Application）创建 REST API。交叉训练是一种健身方式，融合了竞技类运动和高强度训练，以及各种各样的运动元素（奥林匹克举重、体操等）。

这个应用可以创建、读取、更新和删除WOD（Workout of the Day，即每日训练），帮助用户（健身馆主）指定和维护已有的健身计划。除此之外，还可以在一些重要的训练旁批注一些训练建议。

我们的工作就是设计和实现这个应用的 API。

前提条件

在学习这门教程之前，你必须使用过 JavaScript、Node.js、Express.js 以及后端架构，熟悉 REST 和 API 这类术语，并且了解主从式架构（客户端/服务器架构）。

当然你不需要成为这些话题的专家，熟悉并且有这些实际操作经验就足够了。

即便你不符合上述条件，也不是跳过这篇教程的理由。你还是可以从这篇文章中学到很多东西，具备上述条件可以帮助你更轻松地阅读这篇文章。

虽然这里的 API 是用 JavaScript 和 Express 写的，但不表示这些最佳实践仅适用于此。你也可以在其他的编程语言和框架中应用这些最佳实践。

架构

如前所述，我会是用 Express.js 来搭建 API。我不想弄得太复杂，所以我会使用 3 层结构：

在控制器，我们将处理所有 HTTP 相关的内容，也就是说我们在这里处理端点的请求和响应。在这层之上是 Express 的路由把请求传递给相应的控制器。

所有业务逻辑都在服务层，服务层导出特定服务（方法）供控制层器用。

第三层是数据访问层，在这里处理数据库。我们将导出一些处理数据的方法，如创建 WOD，供服务层使用。

在我们的教学示例中，我们不会使用 真实的 数据库，如 MongoDB 或者 PostgreSQL，因为我想专注于最佳实践本身。因此我们会使用本地 JSON 文件来模拟数据库，但是使用逻辑可以迁移到其他的数据库。

基础设置

现在我们开始配置 API 的基础设置。不会太复杂，我们只创建一个简单、有组织的结构。

首先，我们创建一个总文件目录结构，包含所有必需的文件和依赖项。创建完了之后，我们将快速地检查一下一切是否运行正常。

# 创建项目目录并且打开这个目录
mkdir crossfit-wod-api && cd crossfit-wod-api

# 创建 src 目录并打开这个目录
mkdir src && cd src

# 创建子目录
mkdir controllers && mkdir services && mkdir database && mkdir routes

# 创建 index 文件（API 接入点）
touch index.js

# 我们现在位于 src 目录，所以要返回一级
cd .. 

# 创建 package.json 文件
npm init -y

安装基础设置的所有依赖项：

# 开发依赖项
npm i -D nodemon 

# 依赖项 
npm i express

在你最喜欢使用的文字处理器中打开我们的项目，然后配置 Express：

// 在 src/index.js 中
const express = require("express"); 

const app = express(); 
const PORT = process.env.PORT || 3000; 

// 供测试用代码
app.get("/", (req, res) => { 
    res.send("It's Working!"); 
}); 

app.listen(PORT, () => { 
    console.log(`API is listening on port ${PORT}`); 
});

在package.json中添加 "dev" 脚本：

{
  "name": "crossfit-wod-api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "nodemon src/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "nodemon": "^2.0.15"
  },
  "dependencies": {
    "express": "^4.17.3"
  }
}

nodemon 可以确保每次你保存更改的时候，重新启动开发服务器。

启动开发服务器：

npm run dev

查看控制台，会收到消息 "API is listening on port 3000"。

在浏览器中打开 localhost:3000。如果一切设置正确，你会看到下面内容：

太好了！我们已经设置好应用最佳实践的环境。

REST API 最佳实践

图片作者Constantin Wenning，来自Unsplash

很好！我们已经完成了 Express 的基础设置，现在我们可以根据最佳实践来扩展 API 了。

我们从最简单的基础 CRUD 端点开始，之后我们将使用最佳实践来扩展 API。

版本

稍等一下，在我们编写具体的 API 代码之前，我们要关注一下版本。和其他所有应用一样，我们的 API 也需要迭代、更新功能，所以给我们的 API 制定版本十分重要。

这样做最大的优势是当我们在创建新功能的时候并不影响客户端继续运行旧版本。

我们并不强迫用户直接使用我们的新版本，用户可以继续使用旧的版本，直到新版本稳定后再迁移到新版本。

当下版本和新版本并行运行，互不干扰。

那我们如何区分不同的版本呢？一种不错的做法是在 URL 添加 v1、v2 这样的路径段。

// 版本1 
"/api/v1/workouts" 

// 版本2 
"/api/v2/workouts" 

// ...

这就是我们暴露给外部，其他开发者也可以使用的部分。同时，我们也需要调整项目结构来区分不同的版本。

管理 Express API 版本的方法各式各样。本教程中我将在 src 目录下创建一个版本目录，如 v1：

mkdir src/v1

现在我们将路由目录移动到新的 v1 目录下：

# 获取当前路径（复制）
pwd 

# 将 “routes” 添加到 “v1” （使用 {pwd} 插入新的路径）
mv {pwd}/src/routes {pwd}/src/v1

新目录 /src/v1/routes 将存储版本 1 的所有路由。之后我们会在里面添加“真实”的内容，但现在我们简单添加一个 index.js 文件来简单测试一下。

# 在 /src/v1/routes 中
touch index.js

我们开启一个简单的路由：

// 在 src/v1/routes/index.js 中
const express = require("express");
const router = express.Router();

router.route("/").get((req, res) => {
  res.send(`Hello from ${req.baseUrl}`);
});

module.exports = router;

现在我们将在 v1 内部的根入口点 src/index.js 接上路由：

// 在src/index.js
const express = require("express");
// *** 添加 ***
const v1Router = require("./v1/routes");

const app = express();
const PORT = process.env.PORT || 3000;

// *** 删除 ***
app.get("/", (req, res) => {
  res.send("It's Working!");
});

// *** 添加 ***
app.use("/api/v1", v1Router);

app.listen(PORT, () => {
  console.log(`API is listening on port ${PORT}`);
});

再登陆浏览器浏览 localhost:3000/api/v1，你会看到以下画面：

祝贺你！你已经调整好了项目结构以适应不同版本。现在我们通过版本 1 的路由来传入请求，之后每一个请求会连接相应的控制器方式。

再继续下一步之前，我想强调一些内容。

我们把路由目录迁移到了 v1 目录下，其他目录如控制器和服务器仍在 src 目录下。因为我们搭建的 API 比较小，所以这么做没有问题，每一个版本我们使用相同的控制器和服务器。

当 API 逐渐壮大，比方说 2 版本需要使用不同的控制方法的话，最好还是把控制器目录放在 v2 目录下，这样就打包了这个版本所有的特定逻辑。

另一个这样做的原因是，我们可能在其他版本中想要改变某个服务器，但我们并不想要中断除此之外的版本。所以推荐把服务器目录也迁移到特定版本目录。

在我们的例子当中仅区分路由的版本是可行的。尽管如此。切记当 API 壮大需要改变的时候，拥有一个清晰的目录结构十分重要。

用复数形式命名资源

设置完结构后我们就进入了真正的 API 搭建了。我希望从基础的 CRUD 端点开始。

也就是说，我们从实现创建、读取、更新和删除交叉训练端点开始。

首先，让我们为训练连接控制器、服务器和路由。

touch src/controllers/workoutController.js 

touch src/services/workoutService.js 

touch src/v1/routes/workoutRoutes.js

我通常喜欢从编写路由开始。让我们思考一下如何给端点命名。这里就会运用到最佳实践。

我们可以将端点命名为 /api/v1/workout，因为我们只添加一个交叉训练，对不对？虽说这样做基本上没什么问题，但是这样可能会造成误解。

谨记：你的 API 会被其他的人类使用，所以必须精准。这一规则也适用于给资源命名。

我通常会把资源看作一个盒子。在我们的例子中，这个盒子存储了训练集合。

将资源以复数形式命名最大的好处是这对于其他人类来说也清晰易懂，复数意味着这是一个包含了各种各样训练的合集。

所以，让我们定义一下路由中端点：

// 在 src/v1/routes/workoutRoutes.js
const express = require("express");
const router = express.Router();

router.get("/", (req, res) => {
  res.send("Get all workouts");
});

router.get("/:workoutId", (req, res) => {
  res.send("Get an existing workout");
});

router.post("/", (req, res) => {
  res.send("Create a new workout");
});

router.patch("/:workoutId", (req, res) => {
  res.send("Update an existing workout");
});

router.delete("/:workoutId", (req, res) => {
  res.send("Delete an existing workout");
});

module.exports = router;

我们可以删除 src/v1/routes 中的测试文件 index.js 文件。

现在让我们回到入口接点连接版本 1.0 的路由。

// 在 src/index.js
const express = require("express");
// *** 删除 ***
const v1Router = require("./v1/routes");
// *** 添加 ***
const v1WorkoutRouter = require("./v1/routes/workoutRoutes");

const app = express();
const PORT = process.env.PORT || 3000;

// *** 删除 ***
app.use("/api/v1", v1Router);

// *** 添加 ***
app.use("/api/v1/workouts", v1WorkoutRouter);

app.listen(PORT, () => {
  console.log(`API is listening on port ${PORT}`);
});

进展的很顺利！现在我们就可以通过版本 1 的训练路由捕捉到来自 /api/v1/workouts 的所有请求。

在路由当中，我们将调用控制器的方法来处理不同的端点。

让我们为每一个端点创建一个方法。现阶段只需要返回一个信息。

// 在 src/controllers/workoutController.js
const getAllWorkouts = (req, res) => {
  res.send("Get all workouts");
};

const getOneWorkout = (req, res) => {
  res.send("Get an existing workout");
};

const createNewWorkout = (req, res) => {
  res.send("Create a new workout");
};

const updateOneWorkout = (req, res) => {
  res.send("Update an existing workout");
};

const deleteOneWorkout = (req, res) => {
  res.send("Delete an existing workout");
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

现在可以修改一下训练的路由，调用控制器方法：

// In src/v1/routes/workoutRoutes.js
const express = require("express");
const workoutController = require("../../controllers/workoutController");

const router = express.Router();

router.get("/", workoutController.getAllWorkouts);

router.get("/:workoutId", workoutController.getOneWorkout);

router.post("/", workoutController.createNewWorkout);

router.patch("/:workoutId", workoutController.updateOneWorkout);

router.delete("/:workoutId", workoutController.deleteOneWorkout);

module.exports = router;

现在可以测试 GET /api/v1/workouts/:workoutId 端点，在浏览器输入 localhost:3000/api/v1/workouts/2342，你会看到以下信息：

我们成功了！API 结构的第一层就搭建完毕。让我们用另个最佳实践来创建服务层。

以 JSON 格式接受和响应数据

和 API 交互的时候，我们会通过请求发送特定数据，或者通过响应接受数据。市面上有各种各样的数据格式，但是 JSON（JavaScript Object Notation）是一个标准格式。

虽然在 JSON 的全称中有 JavaScript ，但两者并没有绑定。你也可以使用 Java 或者 Python 来编写你的 API，它们也可以处理 JSON。

由于这样的标准化，API 应该接受和响应 JSON 格式的数据。

让我们回到我们的代码，看看如何把这一点融入到我们的最佳实践。

首先，我们创建服务层。

// 在src/services/workoutService.js
const getAllWorkouts = () => {
  return;
};

const getOneWorkout = () => {
  return;
};

const createNewWorkout = () => {
  return;
};

const updateOneWorkout = () => {
  return;
};

const deleteOneWorkout = () => {
  return;
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

将服务方法和控制器方法命名为一样的名字也是一种最佳实践，这样可以让两者保持关联。让我们先不返回任何东西。

在训练的控制器中，调用服务层的这些方法：

// 在src/controllers/workoutController.js
// *** 添加 ***
const workoutService = require("../services/workoutService");

const getAllWorkouts = (req, res) => {
  // *** 添加 ***
  const allWorkouts = workoutService.getAllWorkouts();
  res.send("Get all workouts");
};

const getOneWorkout = (req, res) => {
  // *** 添加 ***
  const workout = workoutService.getOneWorkout();
  res.send("Get an existing workout");
};

const createNewWorkout = (req, res) => {
  // *** 添加 ***
  const createdWorkout = workoutService.createNewWorkout();
  res.send("Create a new workout");
};

const updateOneWorkout = (req, res) => {
  // *** 添加 ***
  const updatedWorkout = workoutService.updateOneWorkout();
  res.send("Update an existing workout");
};

const deleteOneWorkout = (req, res) => {
  // *** 添加 ***
  workoutService.deleteOneWorkout();
  res.send("Delete an existing workout");
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

我们暂且不需要改变控制器响应中的任何内容，但是控制器已经可以和服务层联通了。

在服务的方法中，我们处理了业务逻辑，如改变数据结构以及和数据层交互。

为此我们需要创建一个数据层和一组处理与数据库交互的方法。我们的数据库将为简单的训练 JSON 文件。

# 在src/database中创建一个新的名为 db.json的文件
touch src/database/db.json 

# 在/src/database中创建一个存储所有训练相关方法的文件
touch src/database/Workout.js

将这些内容复制粘贴到 db.json：

{
  "workouts": [
    {
      "id": "61dbae02-c147-4e28-863c-db7bd402b2d6",
      "name": "Tommy V",
      "mode": "For Time",
      "equipment": [
        "barbell",
        "rope"
      ],
      "exercises": [
        "21 thrusters",
        "12 rope climbs, 15 ft",
        "15 thrusters",
        "9 rope climbs, 15 ft",
        "9 thrusters",
        "6 rope climbs, 15 ft"
      ],
      "createdAt": "4/20/2022, 2:21:56 PM",
      "updatedAt": "4/20/2022, 2:21:56 PM",
      "trainerTips": [
        "Split the 21 thrusters as needed",
        "Try to do the 9 and 6 thrusters unbroken",
        "RX Weights: 115lb/75lb"
      ]
    },
    {
      "id": "4a3d9aaa-608c-49a7-a004-66305ad4ab50",
      "name": "Dead Push-Ups",
      "mode": "AMRAP 10",
      "equipment": [
        "barbell"
      ],
      "exercises": [
        "15 deadlifts",
        "15 hand-release push-ups"
      ],
      "createdAt": "1/25/2022, 1:15:44 PM",
      "updatedAt": "3/10/2022, 8:21:56 AM",
      "trainerTips": [
        "Deadlifts are meant to be light and fast",
        "Try to aim for unbroken sets",
        "RX Weights: 135lb/95lb"
      ]
    },
    {
      "id": "d8be2362-7b68-4ea4-a1f6-03f8bc4eede7",
      "name": "Heavy DT",
      "mode": "5 Rounds For Time",
      "equipment": [
        "barbell",
        "rope"
      ],
      "exercises": [
        "12 deadlifts",
        "9 hang power cleans",
        "6 push jerks"
      ],
      "createdAt": "11/20/2021, 5:39:07 PM",
      "updatedAt": "11/20/2021, 5:39:07 PM",
      "trainerTips": [
        "Aim for unbroken push jerks",
        "The first three rounds might feel terrible, but stick to it",
        "RX Weights: 205lb/145lb"
      ]
    }
  ]
}

可以看到上面添加了三组训练数据。每组训练包含 id、name、mode、equipment、exercises、createdAt、updatedAt 和 trainerTips。

我们从最简单的开始，返回所有存储的训练，在访问数据层建立对应的方法（src/database/Workout.js）。

在这里我也使用和服务层、控制器的相同的命名，不过是否这样命名完全取决于你的选择。

// 在src/database/Workout.js
const DB = require("./db.json");

const getAllWorkouts = () => {
  return DB.workouts;
};

module.exports = { getAllWorkouts };

回到训练计划服务层，实现 getAllWorkouts 的逻辑。

// 在src/database/workoutService.js
// *** 添加 ***
const Workout = require("../database/Workout");
const getAllWorkouts = () => {
  // *** 添加 ***
  const allWorkouts = Workout.getAllWorkouts();
  // *** 添加 ***
  return allWorkouts;
};

const getOneWorkout = () => {
  return;
};

const createNewWorkout = () => {
  return;
};

const updateOneWorkout = () => {
  return;
};

const deleteOneWorkout = () => {
  return;
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

返回所有的训练十分简单，我们不需要改变数据格式，因为数据已经是一个 JSON 文件了。我们暂时也不需要传入参数，现在做的事情非常简单直白，待会儿我们会重新回到这里。

在我们的训练控制器中，已经接受到了 workoutService.getAllWorkouts() 的返回值，并作为响应发送给客户端。我们完成了数据库从服务层到控制器的响应循环。

// 在src/controllers/workoutControllers.js
const workoutService = require("../services/workoutService");

const getAllWorkouts = (req, res) => {
  const allWorkouts = workoutService.getAllWorkouts();
  // *** 添加 ***
  res.send({ status: "OK", data: allWorkouts });
};

const getOneWorkout = (req, res) => {
  const workout = workoutService.getOneWorkout();
  res.send("Get an existing workout");
};

const createNewWorkout = (req, res) => {
  const createdWorkout = workoutService.createNewWorkout();
  res.send("Create a new workout");
};

const updateOneWorkout = (req, res) => {
  const updatedWorkout = workoutService.updateOneWorkout();
  res.send("Update an existing workout");
};

const deleteOneWorkout = (req, res) => {
  workoutService.deleteOneWorkout();
  res.send("Delete an existing workout");
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

在浏览器访问 localhost:3000/api/v1/workouts，你将看到响应的 JSON。

一切都进展得很顺利，我们将数据以 JSON 的形式返回。但如何接受来自客户端的数据呢？假设我们需要一个端点来接受来自客户端的 JSON，在这个端点客户端创建和更新训练数据。

在控制器中，我们提取了请求体来创建一个新的训练，并传入训练服务层。在训练服务层，我们插入了 DB.json 并且将新创建的训练返回到客户端。

要想在请求体中解析 JSON，我们需要首先安装 body-parser 并配置。

npm i body-parser

// 在src/index.js中
const express = require("express");
// *** 添加 ***
const bodyParser = require("body-parser");
const v1WorkoutRouter = require("./v1/routes/workoutRoutes");

const app = express();
const PORT = process.env.PORT || 3000;

// *** 添加 ***
app.use(bodyParser.json());
app.use("/api/v1/workouts", v1WorkoutRouter);

app.listen(PORT, () => {
  console.log(`API is listening on port ${PORT}`);
});

现在我们就可以在控制器的 req.body 中接受 JSON 格式的数据。

可以打开你最喜欢的 HTTP 服务器（我使用的是 Postman）来进行测试，创建一个路由为 localhost:3000/api/v1/workouts的POST请求，并且将请求体设置为 JSON 格式：

{
  "name": "Core Buster",
  "mode": "AMRAP 20",
  "equipment": [
    "rack",
    "barbell",
    "abmat"
  ],
  "exercises": [
    "15 toes to bars",
    "10 thrusters",
    "30 abmat sit-ups"
  ],
  "trainerTips": [
    "Split your toes to bars into two sets maximum",
    "Go unbroken on the thrusters",
    "Take the abmat sit-ups as a chance to normalize your breath"
  ]
}

你可能注意到了 “id”、“createdAt”、“updatedAt” 这些属性不存在。添加这些属性是我们 API 的工作，我们会在训练服务层中处理相关内容。

在训练控制器的 createNewWorkout 方法中，我们可以在请求体中提取 body，并做一些验证，并作为参数传入训练服务层。

// 在src/controllers/workoutController.js
...

const createNewWorkout = (req, res) => {
  const { body } = req;
  // *** 添加 ***
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    return;
  }
  // *** 添加 ***
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  // *** 添加 ***
  const createdWorkout = workoutService.createNewWorkout(newWorkout);
  // *** 添加 ***
  res.status(201).send({ status: "OK", data: createdWorkout });
};

...

通常会使用第三方包来来提升请求验证性能，如：express-validator。

训练服务层接受来自 createdNewWorkout 方法传入的数据。

之后我们将缺失的属性传入对象，并将这个对象作为新的方法传入数据访问层，再存入 DB 中。

首先我们要创建一个简单的 Util 函数，来覆盖 JSON 文件以实时更新数据：

# 在 data 目录下创建 util 文件
touch src/database/utils.js

// 在 src/database/utils.js
const fs = require("fs");

const saveToDatabase = (DB) => {
  fs.writeFileSync("./src/database/db.json", JSON.stringify(DB, null, 2), {
    encoding: "utf-8",
  });
};

module.exports = { saveToDatabase };

我们可以在 Workout.js 文件中使用这个函数：

// 在src/database/Workout.js
const DB = require("./db.json");
// *** 添加 ***
const { saveToDatabase } = require("./utils");


const getAllWorkouts = () => {
  return DB.workouts;
};

// *** 添加 ***
const createNewWorkout = (newWorkout) => {
  const isAlreadyAdded =
    DB.workouts.findIndex((workout) => workout.name === newWorkout.name) > -1;
  if (isAlreadyAdded) {
    return;
  }
  DB.workouts.push(newWorkout);
  saveToDatabase(DB);
  return newWorkout;
};

module.exports = {
  getAllWorkouts,
  // *** 添加 ***
  createNewWorkout,
};

一切进展得很顺利。下一步是调用训练服务层中的数据库方法。

# 安装 uuid 包
npm i uuid

// 在src/services/workoutService.js
// *** 添加 ***
const { v4: uuid } = require("uuid");
// *** 添加 ***
const Workout = require("../database/Workout");

const getAllWorkouts = () => {
  const allWorkouts = Workout.getAllWorkouts()
  return allWorkouts;
};

const getOneWorkout = () => {
  return;
};

const createNewWorkout = (newWorkout) => {
  // *** 添加 ***
  const workoutToInsert = {
    ...newWorkout,
    id: uuid(),
    createdAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  // *** 添加 ***
  const createdWorkout = Workout.createNewWorkout(workoutToInsert);
  return createdWorkout;
};

const updateOneWorkout = () => {
  return;
};

const deleteOneWorkout = () => {
  return;
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

一切还不错，对不对？现在你可以去 HTTP 客户端，重新发送 POST 请求，就会接受到新的 JSON 格式的训练。

如果你尝试再次添加同样的训练，你仍会得到 201 状态码，但是不会插入新的内容。

也就是说我们的数据库方法取消了插入，什么都不返回。这是因为 if 声明检查了是否已经存在同样名称的内容，暂时这么处理，我们会在下一个最佳实践中讲解如何优化。

现在向 localhost:3000/api/v1/workouts 发出 GET 请求，读取所有的训练。我选择使用浏览器来操作，你会看到我们的训练成功地插入了：

你可以选择自行编写其他的方法，或者直接复制我的。

首先是训练控制器（你可以直接复制所有内容）。

// 在src/controllers/workoutController.js
const workoutService = require("../services/workoutService");

const getAllWorkouts = (req, res) => {
  const allWorkouts = workoutService.getAllWorkouts();
  res.send({ status: "OK", data: allWorkouts });
};

const getOneWorkout = (req, res) => {
  const {
    params: { workoutId },
  } = req;
  if (!workoutId) {
    return;
  }
  const workout = workoutService.getOneWorkout(workoutId);
  res.send({ status: "OK", data: workout });
};

const createNewWorkout = (req, res) => {
  const { body } = req;
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    return;
  }
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  const createdWorkout = workoutService.createNewWorkout(newWorkout);
  res.status(201).send({ status: "OK", data: createdWorkout });
};

const updateOneWorkout = (req, res) => {
  const {
    body,
    params: { workoutId },
  } = req;
  if (!workoutId) {
    return;
  }
  const updatedWorkout = workoutService.updateOneWorkout(workoutId, body);
  res.send({ status: "OK", data: updatedWorkout });
};

const deleteOneWorkout = (req, res) => {
  const {
    params: { workoutId },
  } = req;
  if (!workoutId) {
    return;
  }
  workoutService.deleteOneWorkout(workoutId);
  res.status(204).send({ status: "OK" });
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

然后是训练服务层（你可以直接复制所有内容）。

// 在 src/services/workoutServices.js
const { v4: uuid } = require("uuid");
const Workout = require("../database/Workout");

const getAllWorkouts = () => {
  const allWorkouts = Workout.getAllWorkouts();
  return allWorkouts;
};

const getOneWorkout = (workoutId) => {
  const workout = Workout.getOneWorkout(workoutId);
  return workout;
};

const createNewWorkout = (newWorkout) => {
  const workoutToInsert = {
    ...newWorkout,
    id: uuid(),
    createdAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  const createdWorkout = Workout.createNewWorkout(workoutToInsert);
  return createdWorkout;
};

const updateOneWorkout = (workoutId, changes) => {
  const updatedWorkout = Workout.updateOneWorkout(workoutId, changes);
  return updatedWorkout;
};

const deleteOneWorkout = (workoutId) => {
  Workout.deleteOneWorkout(workoutId);
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

最后是数据访问层的数据库方法（你可以直接复制所有内容）。

// 在src/database/Workout.js
const DB = require("./db.json");
const { saveToDatabase } = require("./utils");

const getAllWorkouts = () => {
  return DB.workouts;
};

const getOneWorkout = (workoutId) => {
  const workout = DB.workouts.find((workout) => workout.id === workoutId);
  if (!workout) {
    return;
  }
  return workout;
};

const createNewWorkout = (newWorkout) => {
  const isAlreadyAdded =
    DB.workouts.findIndex((workout) => workout.name === newWorkout.name) > -1;
  if (isAlreadyAdded) {
    return;
  }
  DB.workouts.push(newWorkout);
  saveToDatabase(DB);
  return newWorkout;
};

const updateOneWorkout = (workoutId, changes) => {
  const indexForUpdate = DB.workouts.findIndex(
    (workout) => workout.id === workoutId
  );
  if (indexForUpdate === -1) {
    return;
  }
  const updatedWorkout = {
    ...DB.workouts[indexForUpdate],
    ...changes,
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  DB.workouts[indexForUpdate] = updatedWorkout;
  saveToDatabase(DB);
  return updatedWorkout;
};

const deleteOneWorkout = (workoutId) => {
  const indexForDeletion = DB.workouts.findIndex(
    (workout) => workout.id === workoutId
  );
  if (indexForDeletion === -1) {
    return;
  }
  DB.workouts.splice(indexForDeletion, 1);
  saveToDatabase(DB);
};

module.exports = {
  getAllWorkouts,
  createNewWorkout,
  getOneWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

太棒了！让我们进入下一个最佳实践，来看看怎么处理报错。

响应标准 HTTP 错误代码

我们已经完成了不少内容的搭建，但还没结束呢。现在我们的 API 已经可以处理 CRUD 并且存储数据，这样很棒！但还不够。

为什么？让我来解释。

在一个完美的世界里，所有事情都会运行顺利，没有错误。但是你可能知道，在现实中会出现很多错误——无论这个错误是人为的还是是技术角度。

你或许也认为从一开始就没有任何错误是一种奇怪的感觉，这样确实很棒也让人享受，但作为一个开发者，我们应该更习惯与错误共处。😁

API 也是这样，我们需要处理出现问题或者报错的情况。这也可以使我门的 API 更强大。

出现问题时（不论是在请求中还是在我们 API 内部），我们返回 HTTP 错误代码。我见过并使用过一些 API 始终返回 400 错误代码，并且不附带任何具体的信息说明为什么错误会出现，错误是什么。这样调试起来就很痛苦。

这就是为什么针对不同的情况返回合适的 HTTP 代码是一种最佳实践。这能够使正在使用或者构建 API 的工程师更轻松地识别问题。

为了提升体验，我们还可以在返回错误的同时快速发送一个错误信息。但正如在文章开头说的那样，这一做法并不是万精油，还需要工程师自己来权衡。

例如，是否应该向用户返回 “该用户名已经注册” 这类信息是需要深思熟虑的，因为或许这样就给用户提供了本该隐藏的数据。

可以浏览一遍交叉训练 API 中的创建（CRUD 中的 C）端点，看看会出现什么问题，我们能怎么解决。在这一部分最后部分有其他端点的完整实现。

我们先从训练控制器的 createNewWorkout 方法开始：

// 在src/controllers/workoutController.js
...

const createNewWorkout = (req, res) => {
  const { body } = req;
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    return;
  }
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  const createdWorkout = workoutService.createNewWorkout(newWorkout);
  res.status(201).send({ status: "OK", data: createdWorkout });
};

...

我们的代码已经可以捕获请求体属性不完整的情况。

在返回 400 时，附带一条返回错误信息是一个不错的选择。

// 在src/controllers/workoutController.js
...

const createNewWorkout = (req, res) => {
  const { body } = req;
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: {
          error:
            "One of the following keys is missing or is empty in request body: 'name', 'mode', 'equipment', 'exercises', 'trainerTips'",
        },
      });
    return;
  }
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  const createdWorkout = workoutService.createNewWorkout(newWorkout);
  res.status(201).send({ status: "OK", data: createdWorkout });
};

...

如果我们想要添加一个新的训练，但是忘记在请求体提供 “mode” 属性，我们会在 400 报错的同时看到错误信息。

这样的话，使用这个 API 的开发者就更知道自己需要什么。他们马上就知道应该在请求体中找答案，并且看看他们缺失了哪一个必须的属性。

在我们的例子中使用通用的错误信息没有问题。一般情况下可以使用一个模式验证器来处理这个问题。

让我们再深入一层看看服务层有什么潜在的错误：

// 在src/services/workoutService.js
...

const createNewWorkout = (newWorkout) => {
  const workoutToInsert = {
    ...newWorkout,
    id: uuid(),
    createdAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  const createdWorkout = Workout.createNewWorkout(workoutToInsert);
  return createdWorkout;
};

...

在 Workout.createNewWorkout() 中的插入数据可能出现问题，我想将它们打包在 try/catch 代码块中，来捕获错误。

// 在src/services/workoutService.js
...

const createNewWorkout = (newWorkout) => {
  const workoutToInsert = {
    ...newWorkout,
    id: uuid(),
    createdAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  try {
    const createdWorkout = Workout.createNewWorkout(workoutToInsert);
    return createdWorkout;
  } catch (error) {
    throw error;
  }
};

...

Workout.createNewWorkout() 方法中的所有错误都会被 catch 代码块捕获。我们抛出这个错误之后就可以在控制器中调整响应。

让我们在 Workout.js 中定义错误：

// 在src/database/Workout.js
...

const createNewWorkout = (newWorkout) => {
  const isAlreadyAdded =
    DB.workouts.findIndex((workout) => workout.name === newWorkout.name) > -1;
  if (isAlreadyAdded) {
    throw {
      status: 400,
      message: `Workout with the name '${newWorkout.name}' already exists`,
    };
  }
  try {
    DB.workouts.push(newWorkout);
    saveToDatabase(DB);
    return newWorkout;
  } catch (error) {
    throw { status: 500, message: error?.message || error };
  }
};

...

如你所见，一个错误包含了状态和信息两个内容。此处我使用了 throw 关键字来抛出一个数据结构而不是一条字符串，throw new Error() 必须这么写。

使用 throw 的缺点是无法得到栈追踪。但基本上抛出错误由第三方库来处理（如果你使用 MongoDB 数据库的话就是 Mongoose），在本教程中，我们现在做的就足够了。

现在我们就可以在服务和数据访问层来抛出和捕获错误了。我们现在进入训练控制层，来编写抛出错误和对应的消息。

// 在src/controllers/workoutController.js
...

const createNewWorkout = (req, res) => {
  const { body } = req;
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: {
          error:
            "One of the following keys is missing or is empty in request body: 'name', 'mode', 'equipment', 'exercises', 'trainerTips'",
        },
      });
    return;
  }
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  // *** 添加 ***
  try {
    const createdWorkout = workoutService.createNewWorkout(newWorkout);
    res.status(201).send({ status: "OK", data: createdWorkout });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

...

你可以通过添加同样名字的训练，或者不在请求体中提供必需的属性来测试。你会接受对应的 HTTP 错误代码以及错误信息。

在结束这一篇并且进入下一个最佳实践之前，让我们复制其他的实现代码，或者你可以尝试自己编写：

// 在src/controllers/workoutController.js
const workoutService = require("../services/workoutService");

const getAllWorkouts = (req, res) => {
  try {
    const allWorkouts = workoutService.getAllWorkouts();
    res.send({ status: "OK", data: allWorkouts });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

const getOneWorkout = (req, res) => {
  const {
    params: { workoutId },
  } = req;
  if (!workoutId) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: { error: "Parameter ':workoutId' can not be empty" },
      });
  }
  try {
    const workout = workoutService.getOneWorkout(workoutId);
    res.send({ status: "OK", data: workout });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

const createNewWorkout = (req, res) => {
  const { body } = req;
  if (
    !body.name ||
    !body.mode ||
    !body.equipment ||
    !body.exercises ||
    !body.trainerTips
  ) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: {
          error:
            "One of the following keys is missing or is empty in request body: 'name', 'mode', 'equipment', 'exercises', 'trainerTips'",
        },
      });
    return;
  }
  const newWorkout = {
    name: body.name,
    mode: body.mode,
    equipment: body.equipment,
    exercises: body.exercises,
    trainerTips: body.trainerTips,
  };
  try {
    const createdWorkout = workoutService.createNewWorkout(newWorkout);
    res.status(201).send({ status: "OK", data: createdWorkout });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

const updateOneWorkout = (req, res) => {
  const {
    body,
    params: { workoutId },
  } = req;
  if (!workoutId) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: { error: "Parameter ':workoutId' can not be empty" },
      });
  }
  try {
    const updatedWorkout = workoutService.updateOneWorkout(workoutId, body);
    res.send({ status: "OK", data: updatedWorkout });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

const deleteOneWorkout = (req, res) => {
  const {
    params: { workoutId },
  } = req;
  if (!workoutId) {
    res
      .status(400)
      .send({
        status: "FAILED",
        data: { error: "Parameter ':workoutId' can not be empty" },
      });
  }
  try {
    workoutService.deleteOneWorkout(workoutId);
    res.status(204).send({ status: "OK" });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
  getRecordsForWorkout,
};

// In src/services/workoutService.js
const { v4: uuid } = require("uuid");
const Workout = require("../database/Workout");

const getAllWorkouts = () => {
  try {
    const allWorkouts = Workout.getAllWorkouts();
    return allWorkouts;
  } catch (error) {
    throw error;
  }
};

const getOneWorkout = (workoutId) => {
  try {
    const workout = Workout.getOneWorkout(workoutId);
    return workout;
  } catch (error) {
    throw error;
  }
};

const createNewWorkout = (newWorkout) => {
  const workoutToInsert = {
    ...newWorkout,
    id: uuid(),
    createdAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
  };
  try {
    const createdWorkout = Workout.createNewWorkout(workoutToInsert);
    return createdWorkout;
  } catch (error) {
    throw error;
  }
};

const updateOneWorkout = (workoutId, changes) => {
  try {
    const updatedWorkout = Workout.updateOneWorkout(workoutId, changes);
    return updatedWorkout;
  } catch (error) {
    throw error;
  }
};

const deleteOneWorkout = (workoutId) => {
  try {
    Workout.deleteOneWorkout(workoutId);
  } catch (error) {
    throw error;
  }
};

module.exports = {
  getAllWorkouts,
  getOneWorkout,
  createNewWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

// 在src/database/Workout.js
const DB = require("./db.json");
const { saveToDatabase } = require("./utils");

const getAllWorkouts = () => {
  try {
    return DB.workouts;
  } catch (error) {
    throw { status: 500, message: error };
  }
};

const getOneWorkout = (workoutId) => {
  try {
    const workout = DB.workouts.find((workout) => workout.id === workoutId);
    if (!workout) {
      throw {
        status: 400,
        message: `Can't find workout with the id '${workoutId}'`,
      };
    }
    return workout;
  } catch (error) {
    throw { status: error?.status || 500, message: error?.message || error };
  }
};

const createNewWorkout = (newWorkout) => {
  try {
    const isAlreadyAdded =
      DB.workouts.findIndex((workout) => workout.name === newWorkout.name) > -1;
    if (isAlreadyAdded) {
      throw {
        status: 400,
        message: `Workout with the name '${newWorkout.name}' already exists`,
      };
    }
    DB.workouts.push(newWorkout);
    saveToDatabase(DB);
    return newWorkout;
  } catch (error) {
    throw { status: error?.status || 500, message: error?.message || error };
  }
};

const updateOneWorkout = (workoutId, changes) => {
  try {
    const isAlreadyAdded =
      DB.workouts.findIndex((workout) => workout.name === changes.name) > -1;
    if (isAlreadyAdded) {
      throw {
        status: 400,
        message: `Workout with the name '${changes.name}' already exists`,
      };
    }
    const indexForUpdate = DB.workouts.findIndex(
      (workout) => workout.id === workoutId
    );
    if (indexForUpdate === -1) {
      throw {
        status: 400,
        message: `Can't find workout with the id '${workoutId}'`,
      };
    }
    const updatedWorkout = {
      ...DB.workouts[indexForUpdate],
      ...changes,
      updatedAt: new Date().toLocaleString("en-US", { timeZone: "UTC" }),
    };
    DB.workouts[indexForUpdate] = updatedWorkout;
    saveToDatabase(DB);
    return updatedWorkout;
  } catch (error) {
    throw { status: error?.status || 500, message: error?.message || error };
  }
};

const deleteOneWorkout = (workoutId) => {
  try {
    const indexForDeletion = DB.workouts.findIndex(
      (workout) => workout.id === workoutId
    );
    if (indexForDeletion === -1) {
      throw {
        status: 400,
        message: `Can't find workout with the id '${workoutId}'`,
      };
    }
    DB.workouts.splice(indexForDeletion, 1);
    saveToDatabase(DB);
  } catch (error) {
    throw { status: error?.status || 500, message: error?.message || error };
  }
};

module.exports = {
  getAllWorkouts,
  createNewWorkout,
  getOneWorkout,
  updateOneWorkout,
  deleteOneWorkout,
};

避免在端点使用动词

在端点中使用动词实际上没有任何作用。大体上 URL 和资源（想想我们前文提到的“盒子”）是一一对应的。

在 URL 中使用动词，相当于展示了资源本身并没有的行为。

我们已经在不使用动词的情况下正确地编写好了 URL，但让我们看看，如果使用动词，URL 会是什么样。

// 现在的样子（没有动词）
GET "/api/v1/workouts" 
GET "/api/v1/workouts/:workoutId" 
POST "/api/v1/workouts" 
PATCH "/api/v1/workouts/:workoutId" 
DELETE "/api/v1/workouts/:workoutId"  

// 使用动词
GET "/api/v1/getAllWorkouts" 
GET "/api/v1/getWorkoutById/:workoutId" 
CREATE "/api/v1/createWorkout" 
PATCH "/api/v1/updateWorkout/:workoutId" 
DELETE "/api/v1/deleteWorkout/:workoutId"

你看到区别了吗？给每一个行为分配不同的 URL，会让人困惑并且十分复杂。

假设我们有 300 个不同的端点。为每个端点分配单独的 URL 可能造成开销（和文档）地狱。

另一个我不推荐在 URL 中使用动词的原因是，HTTP 动词已经表明了响应的动作。

如 “GET /api/v1/getAllWorkouts” 和 “DELETE api/v1/deleteWorkout/workoutId” 就很没有必要。

你会发现我们的实现非常清晰，因为我们只使用两个不同的 URL，而实际的行为是通过 HTTP 动词以及对应的请求有效载荷来实现。

我认为 HTTP 动词是来定义行为的（我们也希望这样），而 URL（指向资源）是目标。“GET /api/v1/workouts” 这句话即便是人类的语言中也更通顺。

把相关的资源放在一起（逻辑嵌套）

当你在设计 API 的时候，会出现资源之间相互关联的情况。一个好的实践方式是将资源整合和嵌套到一个端点。

在我们的 API 中，有一系列的会员注册了交叉训练盒子（此处的“盒子”是交叉训练健身房的名字），为了鼓励会员，我们记录了每一次训练的所有记录。

假设有一组训练包含一定顺序的练习，你想要尽快做完。我们记录了所有会员完成这项训练的时间。

这时，前端就需要一个端点来响应一个特定训练的所有时间记录，并且在 UI 上呈现。

训练、会员还有训练记录存储在不同的数据库里。所以在这里我们需要使用盒中盒（训练中的记录），对不对？

这个端点的 URI 会是 /api/v1/workouts/:workoutId/records。这便是一个在 URL 中实现逻辑嵌套的好实践。URL 本身不需要反应数据结构。

让我们来实现这个端点。

首先我们要在 db.json 中添加一组叫 “memebers” 的数据，放在 “workouts” 下面。

{
  "workouts": [ ...
  ],
  "members": [
    {
      "id": "12a410bc-849f-4e7e-bfc8-4ef283ee4b19",
      "name": "Jason Miller",
      "gender": "male",
      "dateOfBirth": "23/04/1990",
      "email": "jason@mail.com",
      "password": "666349420ec497c1dc890c45179d44fb13220239325172af02d1fb6635922956"
    },
    {
      "id": "2b9130d4-47a7-4085-800e-0144f6a46059",
      "name": "Tiffany Brookston",
      "gender": "female",
      "dateOfBirth": "09/06/1996",
      "email": "tiffy@mail.com",
      "password": "8a1ea5669b749354110dcba3fac5546c16e6d0f73a37f35a84f6b0d7b3c22fcc"
    },
    {
      "id": "11817fb1-03a1-4b4a-8d27-854ac893cf41",
      "name": "Catrin Stevenson",
      "gender": "female",
      "dateOfBirth": "17/08/2001",
      "email": "catrin@mail.com",
      "password": "18eb2d6c5373c94c6d5d707650d02c3c06f33fac557c9cfb8cb1ee625a649ff3"
    },
    {
      "id": "6a89217b-7c28-4219-bd7f-af119c314159",
      "name": "Greg Bronson",
      "gender": "male",
      "dateOfBirth": "08/04/1993",
      "email": "greg@mail.com",
      "password": "a6dcde7eceb689142f21a1e30b5fdb868ec4cd25d5537d67ac7e8c7816b0e862"
    }
  ]
}

在你问之前，我先回答——是的，密码是哈希加密的。😉

然后我们在 “records” 下面添加 “members”：

{
  "workouts": [ ...
  ],
  "members": [ ...
  ],
  "records": [
    {
      "id": "ad75d475-ac57-44f4-a02a-8f6def58ff56",
      "workout": "4a3d9aaa-608c-49a7-a004-66305ad4ab50",
      "record": "160 reps"
    },
    {
      "id": "0bff586f-2017-4526-9e52-fe3ea46d55ab",
      "workout": "d8be2362-7b68-4ea4-a1f6-03f8bc4eede7",
      "record": "7:23 minutes"
    },
    {
      "id": "365cc0bb-ba8f-41d3-bf82-83d041d38b82",
      "workout": "a24d2618-01d1-4682-9288-8de1343e53c7",
      "record": "358 reps"
    },
    {
      "id": "62251cfe-fdb6-4fa6-9a2d-c21be93ac78d",
      "workout": "4a3d9aaa-608c-49a7-a004-66305ad4ab50",
      "record": "145 reps"
    }
  ],
}

为了确保同一 id 下的训练相同，我也复制了一些训练到 workouts 中：

{
  "workouts": [
    {
      "id": "61dbae02-c147-4e28-863c-db7bd402b2d6",
      "name": "Tommy V",
      "mode": "For Time",
      "equipment": [
        "barbell",
        "rope"
      ],
      "exercises": [
        "21 thrusters",
        "12 rope climbs, 15 ft",
        "15 thrusters",
        "9 rope climbs, 15 ft",
        "9 thrusters",
        "6 rope climbs, 15 ft"
      ],
      "createdAt": "4/20/2022, 2:21:56 PM",
      "updatedAt": "4/20/2022, 2:21:56 PM",
      "trainerTips": [
        "Split the 21 thrusters as needed",
        "Try to do the 9 and 6 thrusters unbroken",
        "RX Weights: 115lb/75lb"
      ]
    },
    {
      "id": "4a3d9aaa-608c-49a7-a004-66305ad4ab50",
      "name": "Dead Push-Ups",
      "mode": "AMRAP 10",
      "equipment": [
        "barbell"
      ],
      "exercises": [
        "15 deadlifts",
        "15 hand-release push-ups"
      ],
      "createdAt": "1/25/2022, 1:15:44 PM",
      "updatedAt": "3/10/2022, 8:21:56 AM",
      "trainerTips": [
        "Deadlifts are meant to be light and fast",
        "Try to aim for unbroken sets",
        "RX Weights: 135lb/95lb"
      ]
    },
    {
      "id": "d8be2362-7b68-4ea4-a1f6-03f8bc4eede7",
      "name": "Heavy DT",
      "mode": "5 Rounds For Time",
      "equipment": [
        "barbell",
        "rope"
      ],
      "exercises": [
        "12 deadlifts",
        "9 hang power cleans",
        "6 push jerks"
      ],
      "createdAt": "11/20/2021, 5:39:07 PM",
      "updatedAt": "4/22/2022, 5:49:18 PM",
      "trainerTips": [
        "Aim for unbroken push jerks",
        "The first three rounds might feel terrible, but stick to it",
        "RX Weights: 205lb/145lb"
      ]
    },
    {
      "name": "Core Buster",
      "mode": "AMRAP 20",
      "equipment": [
        "rack",
        "barbell",
        "abmat"
      ],
      "exercises": [
        "15 toes to bars",
        "10 thrusters",
        "30 abmat sit-ups"
      ],
      "trainerTips": [
        "Split your toes to bars in two sets maximum",
        "Go unbroken on the thrusters",
        "Take the abmat sit-ups as a chance to normalize your breath"
      ],
      "id": "a24d2618-01d1-4682-9288-8de1343e53c7",
      "createdAt": "4/22/2022, 5:50:17 PM",
      "updatedAt": "4/22/2022, 5:50:17 PM"
    }
  ],
  "members": [ ...
  ],
  "records": [ ...
  ]
}

让我们花点时间来想想如何实现。

我们有一组叫做 “workouts” 的资源，还有另一组叫做 “records” 的资源。

在创建交叉内容的结构之前，建议先创建另一个控制器、服务层和数据组合方法来负责训练记录。

我们很有可能需要为训练记录实现 CRUD 端点，因为在未来我们也会添加、更新和删除记录。但这不是现在的首要任务。

我们也需要一个记录的路由来捕获对应的请求。这是你练习自己实现 CRUD 的绝好机会。

# 创建记录控制器
touch src/controllers/recordController.js 

# 创建记录服务层
touch src/services/recordService.js 

# 创建记录数据处理方法 
touch src/database/Record.js

很简单！让我们从后往前，从实现数据方法开始编写。

// 在src/database/Record.js
const DB = require("./db.json");

const getRecordForWorkout = (workoutId) => {
  try {
    const record = DB.records.filter((record) => record.workout === workoutId);
    if (!record) {
      throw {
        status: 400,
        message: `Can't find workout with the id '${workoutId}'`,
      };
    }
    return record;
  } catch (error) {
    throw { status: error?.status || 500, message: error?.message || error };
  }
};
module.exports = { getRecordForWorkout };

很直接对不对，我们通过查询参数过滤出和训练 id 相关的记录数据

接下来是记录的服务层：

// 在src/services/recordService.js
const Record = require("../database/Record");

const getRecordForWorkout = (workoutId) => {
  try {
    const record = Record.getRecordForWorkout(workoutId);
    return record;
  } catch (error) {
    throw error;
  }
};
module.exports = { getRecordForWorkout };

这里也没有新的知识点。

现在就可以在训练路由创建新的路由，并且导向记录服务请求。

// 在src/v1/routes/workoutRoutes.js
const express = require("express");
const workoutController = require("../../controllers/workoutController");
// *** 添加 ***
const recordController = require("../../controllers/recordController");

const router = express.Router();

router.get("/", workoutController.getAllWorkouts);

router.get("/:workoutId", workoutController.getOneWorkout);

// *** 添加 ***
router.get("/:workoutId/records", recordController.getRecordForWorkout);

router.post("/", workoutController.createNewWorkout);

router.patch("/:workoutId", workoutController.updateOneWorkout);

router.delete("/:workoutId", workoutController.deleteOneWorkout);

module.exports = router;

真棒！让我们在浏览器中测试一下。

首先我们抓取所有训练记录，来获得一个训练 id。

让我们来看看能不能获得这个 id 下的所有记录。

如你所见，逻辑嵌套可以使资源捆绑在一起。理论上你可以想嵌套多少层就嵌套多少层，但建议至多使用三层嵌套。

如果你想嵌套得更深，可以稍微调整一下数据库的记录。我给你看一个小例子。

想象一下，前端还需要一个端点来获取到底是哪个会员持有当前记录的信息，并希望接受这个会员的所有原始信息。

你当然可以使用下面的 URI：

GET /api/v1/workouts/:workoutId/records/members/:memberId

嵌套越多，端点就越不容易管理。因此，将接受会员信息的 URI 直接存储在记录中是一个好的做法。

可以这样修改数据库：

{
  "workouts": [ ...
  ],
  "members": [ ...
  ],
  "records": [ ... {
      "id": "ad75d475-ac57-44f4-a02a-8f6def58ff56",
      "workout": "4a3d9aaa-608c-49a7-a004-66305ad4ab50",
      "record": "160 reps",
      "memberId": "11817fb1-03a1-4b4a-8d27-854ac893cf41",
      "member": "/members/:memberId"
    },
  ]
}

我们在数据库中添加了 “memberId” 和 “member” 这两个属性，这样我们就不需要在端点嵌套得更深。

前端只需要调用 GET /api/v1/workouts/:workoutId/records 便可以获得所有和训练相关的数据。

除此之外，我们可以由会员 id 来获取会员的信息，就可以避免更深入的嵌套。

当然，这一切实现的前提是处理 “/members/:memberId” 请求。😁 这听上去是锻炼你自己实现能力的好机会！

集成过滤、排序和分页功能

现在我们的 API 已经可以完成很多工作，取得了相当大的进展，但是这还不够。

在上一部分我们聚焦在如何提高开发者的体验，以及我们的 API 如何交互。但是 API 的整体性能也是一个关键部分，需要我们努力提高。

这就是为什么在我的待办清单中集成过滤、排序和分页功能也是非常关键的。

假设我们的 DB 中有 2000 个训练，450 条记录和 500 个会员。当我们调用端点来获取训练的时候，我们不希望一次性获得所有 2000 个训练。这样的响应速度会比较慢，导致系统崩溃（崩溃可能需要 200000 条记录😁 ）。

这就是为什么过滤和分页十分重要。过滤正如这个名称一样，可以帮助我们在整个数据集中获取我们需要的数据。例如所有具备“时间”模式的训练。

分页是另一种可以拆分数据集的机制，比方说我们可以把数据分成每页二十个训练的“页面”。这个技术确保我们一次返回不超过 20 个训练。

排序可以变得非常复杂，所以直接在我们的 API 排序后，再向用户发送数据更高效。

我们首先在 API 中整合一些过滤机制。我们将发送所有训练的这个端点升级，让这个端点接受过滤参数。通常在 GET 请求中，我们使用查询参数来添加过滤条件。

当我们只获取训练状态（mode）为 “AMRAP”（尽可能多地训练 As Many Rounds As Possible）时，我们新的 URI 会是这样：/api/v1/workouts?mode=amrap。

为了让实现更有趣，我们可以添加更多的训练。请在 db.json 中的 “workouts” 数据集中添加以下代码：

{
  "name": "Jumping (Not) Made Easy",
  "mode": "AMRAP 12",
  "equipment": [
    "jump rope"
  ],
  "exercises": [
    "10 burpees",
    "25 double-unders"
  ],
  "trainerTips": [
    "Scale to do 50 single-unders, if double-unders are too difficult"
  ],
  "id": "8f8318f8-b869-4e9d-bb78-88010193563a",
  "createdAt": "4/25/2022, 2:45:28 PM",
  "updatedAt": "4/25/2022, 2:45:28 PM"
},
{
  "name": "Burpee Meters",
  "mode": "3 Rounds For Time",
  "equipment": [
    "Row Erg"
  ],
  "exercises": [
    "Row 500 meters",
    "21 burpees",
    "Run 400 meters",
    "Rest 3 minutes"
  ],
  "trainerTips": [
    "Go hard",
    "Note your time after the first run",
    "Try to hold your pace"
  ],
  "id": "0a5948af-5185-4266-8c4b-818889657e9d",
  "createdAt": "4/25/2022, 2:48:53 PM",
  "updatedAt": "4/25/2022, 2:48:53 PM"
},
{
  "name": "Dumbbell Rower",
  "mode": "AMRAP 15",
  "equipment": [
    "Dumbbell"
  ],
  "exercises": [
    "15 dumbbell rows, left arm",
    "15 dumbbell rows, right arm",
    "50-ft handstand walk"
  ],
  "trainerTips": [
    "RX weights for women: 35-lb",
    "RX weights for men: 50-lb"
  ],
  "id": "3dc53bc8-27b8-4773-b85d-89f0a354d437",
  "createdAt": "4/25/2022, 2:56:03 PM",
  "updatedAt": "4/25/2022, 2:56:03 PM"
}

当我们处理好接受和处理查询参数后，就可以编写训练的控制层：

// 在src/controllers/workoutController.js
...

const getAllWorkouts = (req, res) => {
  // *** 添加 ***
  const { mode } = req.query;
  try {
    // *** 添加 ***
    const allWorkouts = workoutService.getAllWorkouts({ mode });
    res.send({ status: "OK", data: allWorkouts });
  } catch (error) {
    res
      .status(error?.status || 500)
      .send({ status: "FAILED", data: { error: error?.message || error } });
  }
};

...

我们在 req.query 对象中提取 “mode”，并用作 workoutService.getAllWorkouts 的参数。这个对象包含了所有过滤参数。

这里我使用了简写语法，来创建一个名为 “mode” 的新键，这个键位于对象内部，其值可以是任意 “req.query.mode” 的值。可以为一个真值或者如果没有一个参数为 “mode” 的参数则为 undefined。我们可以在对象内扩充更多过滤参数。

在workoutService中传入数据处理方法：

// 在src/services/workoutService.js
...

const getAllWorkouts = (filterParams) => {
  try {
    // *** 添加 ***
    const allWorkouts = Workout.getAllWorkouts(filterParams);
    return allWorkouts;
  } catch (error) {
    throw error;
  }
};

...

现在我们可以使用数据库方法，并且应用过滤：

// 在src/database/Workout.js
...

const getAllWorkouts = (filterParams) => {
  try {
    let workouts = DB.workouts;
    if (filterParams.mode) {
      return DB.workouts.filter((workout) =>
        workout.mode.toLowerCase().includes(filterParams.mode)
      );
    }
    // 如果有其他的参数，可以在这里编写其他的 if 表达式
    return workouts;
  } catch (error) {
    throw { status: 500, message: error };
  }
};

...

简单明了！我们在这里做的工作就是检查 “filterParams” 中是否存在键 “mode” 的真值，如果存在，则过滤出所有包含同样 “mode” 的训练，如果不存在，则返回所有训练，

此处我们使用 “let” 来定义 “workouts” 变量是因为如果我们使用 if 表达式来添加更多过滤器的话，会覆盖掉 “workouts” 并且串联过滤器。

在浏览器中可以登陆 3000/api/v1/workouts?mode=amrap，会接受到所有包含 “AMRAP” 的训练：

如果不填写查询参数的话，就会重新获得所有训练。你可以尝试添加 “for%20time” 作为 “mode” 的参数（记住：“%20” 代表“空格”），你就会获得所有包含 “For Time” 的训练，

如果输入一个不存在的值，则会接受到空数组。

排序和分页的参数页遵行同样的原理，我们来看看我们需要实现的一些功能：

接受所有需要杠铃的训练：/api/v1/workouts?equipment=barbell
接受 5 组训练：/api/v1/workouts?length=5
使用分页时，返回第二页：/api/v1/workouts?page=2
给训练排序，并且以创建时间为标准降序来响应训练：/api/v1/workouts?sort=-createdAt
你也可以合并参数，获取最近更新的 10 个训练：/api/v1/workouts?sort=-updatedAt&length=10

使用数据缓存提升性能

使用数据缓存也是一个提升 API 整体使用体验和性能的优秀实践。

当一段数据经常被请求，或者这个数据太大了需要比较长的时间加载的时候，可以使用缓存来提供数据。

你可以将这些数据存储到缓存，这样就可以避免每一次都重新提交数据请求。

但必须记住的是，使用缓存来提供数据的话，这段数据很有可能过期。所以必须确保缓存中的数据保持更新。

有各种实现来实现缓存的方式，一种是使用 redis 或者 express 的中间件 apicache。

我准备使用 apicache，但如果你想使用 Redis，我强烈推荐你阅读他们的文档。

我们思考一下在 API 中使用缓存的场景。我认为使用缓存来返回所有训练会更加有效。

首先，让我们安装中间件：

npm i apicache

我们在训练的路由中引用这个插件并配置好：

// 在src/v1/routes/workoutRoutes.js
const express = require("express");
// *** 添加 ***
const apicache = require("apicache");
const workoutController = require("../../controllers/workoutController");
const recordController = require("../../controllers/recordController");

const router = express.Router();
// *** 添加 ***
const cache = apicache.middleware;

// *** 添加 ***
router.get("/", cache("2 minutes"), workoutController.getAllWorkouts);

router.get("/:workoutId", workoutController.getOneWorkout);

router.get("/:workoutId/records", recordController.getRecordForWorkout);

router.post("/", workoutController.createNewWorkout);

router.patch("/:workoutId", workoutController.updateOneWorkout);

router.delete("/:workoutId", workoutController.deleteOneWorkout);

module.exports = router;

很简单！我们可以将新的缓存命名为 apicache.middleware，并在路由中当作中间件来使用。仅需在实际的路径和训练控制器之间放置这个参数。

你可以在中间件内部定义你需要保存缓存多久。在这篇教程中我选择 2 分钟。保存时间一般取决于你存储的数据多久更新一次。

让我们测试一下！

在 Postman 或者另外的 HTTP 客户端中，定义一个新的请求，获取所有的训练。之前我都是在浏览器中操作，但是这次我想给你更直观的感受，所以使用 Postman。

让我们第一次请求数据：

你可以看到我们的 API 花了 22.93 毫秒来响应。一旦缓存被清空（2 分钟后），又回重新抓取数据保存到缓存，我们第一次获取数据的时候就将数据存储到了缓存。

在上述例子中，数据并不是有由缓存提供。而是通过“普通”方式来抓去数据库保存到缓存。

现在我们第二次请求数据，响应时间变短，因为我们直接从缓存中返回数据。

比起第一次请求，我们快了三倍，这完全归功于缓存。

在我们的例子中，我们只缓存了一个路由，你可以在所有路由中应用：

// 在src/index.js
const express = require("express");
const bodyParser = require("body-parser");
// *** 添加 ***
const apicache = require("apicache");
const v1WorkoutRouter = require("./v1/routes/workoutRoutes");

const app = express();
// *** 添加 ***
const cache = apicache.middleware;
const PORT = process.env.PORT || 3000;

app.use(bodyParser.json());
// *** 添加 ***
app.use(cache("2 minutes"));
app.use("/api/v1/workouts", v1WorkoutRouter);

app.listen(PORT, () => {
  console.log(`API is listening on port ${PORT}`);
});

还有一件关于缓存的重要的事情，虽然在这个例子中，缓存给你节省了不少时间，但是缓存也可以给应用造成不小的麻烦：

当使用缓存时，你需要注意的事：

必须保证缓存中的数据是更新的，你可不想提供过期的数据
当第一个请求在执行的过程中，数据被保存到缓存，也有更多地请求进来，你必须决定是延迟其他的请求，从缓存中提供数据，还是其他的请求也如第一次请求一样从数据库来获取数据
如果使用分布式缓存如 Redis，缓存会是你的结构中的一个组件，所以你必须考虑一下是否有必要使用缓存

我常常这么做：

当我在搭建的时候我希望一切从简，API 同理。

首次搭建 API 的时候没有特别的原因使用缓存，我会等使用了一段时间之后，有理由使用缓存后再使用缓存。

好的安全实践

这是一段不错的旅行，我们讲了许多 API 相关的重要观点，并且扩充了我们的 API。

我们已经讲了提升 API 使用和性能的最佳实践。安全也是 API 重要的一环。如果你创建出一个绝佳的 API，但是在服务器上运行的时候却十分脆弱，那这个 API 就变得无用且危险。

首先必须使用的是 SSL/TLS，因为这是当今互联网通讯的一个标准。特别是当 API 需要在客户端和服务器之间传输私人数据的时候。

如果你需要给验证客户提供数据，必须使用验证手段来保护数据。

在 Express 中，我们可以像在缓存中那样在路由中插入特定的中间件来检查请求的真实性再获取资源。

API 中的一些资源和交互是你可能不希望所有用户都可以请求的。这是就需要一个角色系统。在路由中添加一个检查逻辑来验证用户是否有权利来获取这些数据。

用户角色在我们的用例中也同样适用。比方说我们需要特定用户（教练）来使用创建、更新和删除训练和记录的功能。所有用户可以读取（同样可成为“普通”用户）。

这可以通过在路由中插入中间件来实现。如在我们的 /api/v1/workouts 的 POST 请求中插入。

在第一个中间件中我们检查用户是不是真实的，如果为真，就进入下一个中间件来检查用户角色，如果用户符合获取资源的角色，就移交到对应的控制器。

路由处理器如下：

// 在src/v1/routes/workoutRoutes.js
...

// 定制中间件
const authenticate = require("../../middlewares/authenticate");
const authorize = require("../../middlewares/authorize");

router.post("/", authenticate, authorize, workoutController.createNewWorkout);

...

这个话题相关的最佳实践，我推荐阅读这篇文章。

给 API 编写合适的文档

对于开发者来说编写文档确实不是一件让他们乐意干的活儿，但是是必须要做的事，特别是API的文档。

有人说过：

“API 得和文档一样优秀”

我认为这句话挺有道理，因为如果 API 的文档不好，这个 API 就不好使用。文档帮助开发者更方便地使用 API。

永远记住文档是 API 使用者和 API 交互的第一环节。用户能够更快读懂文档，就能够更快使用 API。

所以我们必须编写良好精确的文档。有一些比较好用的工具可以帮助我们实现。

和其他计算机科学领域一样，API 文档也有标准，查看 OpenAPI 细则。

让我们来看看如何遵循这份规则来创建文档。我们将使用 swagger-ui-express 和 swagger-jsdoc 工具包。你马上就会为这两个工具包能够做到的事感到惊奇。

首先我们设置好文档的基础结构。因为我们会有不同版本的 API，所以文档会有些许不同，这就是为什么我会创建 swagger 文件，来处理不同版本的文档。

# 安装必须的 NPM 包
npm i swagger-jsdoc swagger-ui-express 

# 创建新的文件来设置 swagger 文档
touch src/v1/swagger.js

// 在 src/v1/swagger.js 中
const swaggerJSDoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");

// API的基础信息
const options = {
  definition: {
    openapi: "3.0.0",
    info: { title: "Crossfit WOD API", version: "1.0.0" },
  },
  apis: ["./src/v1/routes/workoutRoutes.js", "./src/database/Workout.js"],
};

// 使用 JSON 格式的文档
const swaggerSpec = swaggerJSDoc(options);

// 设置文档的函数
const swaggerDocs = (app, port) => {
  // 处理文档路由
  app.use("/api/v1/docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  // 使得允许使用 JSON 格式文档
  app.get("/api/v1/docs.json", (req, res) => {
    res.setHeader("Content-Type", "application/json");
    res.send(swaggerSpec);
  });
  console.log(
    `Version 1 Docs are available on http://localhost:${port}/api/v1/docs`
  );
};

module.exports = { swaggerDocs };

设置很简单，我们定义了 API 的基本数据，创建了 JSON 格式的文档，并创建了函数使文档可用。

为了检查一切可以运行，我们在控制台打印一个简单的信息。

这是我们在根文件中会使用到的函数，在根文件中我们也创建了 Express 服务器，确保文档也被启动。

// 在src/index.js
const express = require("express");
const bodyParser = require("body-parser");
const v1WorkoutRouter = require("./v1/routes/workoutRoutes");
// *** 添加 ***
const { swaggerDocs: V1SwaggerDocs } = require("./v1/swagger");

const app = express();
const PORT = process.env.PORT || 3000;

app.use(bodyParser.json());
app.use("/api/v1/workouts", v1WorkoutRouter);

app.listen(PORT, () => {
  console.log(`API is listening on port ${PORT}`);
  /// *** 添加 ***
  V1SwaggerDocs(app, PORT);
});

现在你可以在你的控制台查看服务器是否在运行。

当你登陆 localhost:3000/api/v1/docs，你会看到我们的文档已经准备好了：

每次我都会感叹运作得如此顺畅。现在基本结构已经设置好，我们可以来实现文档的端点了，让我们开始吧！

当你查看 swagger.js 文件中的 options.apis，你会发现我们已经预留了处理训练路由和数据库中训练文件的路径。这就是让魔法实现最重要的环节。

在 swagger 中有这些选项使得我们可以使用评论来引用 OpenAPI，并且使用类似 yaml 的语法来编写文档，这就是设置文档的所有必须条件了。

现在我们就可以开始来创建我们文档的第一个端点了，让我们开始吧！

// 在src/v1/routes/workoutRoutes.js
...

/**
 * @openapi
 * /api/v1/workouts:
 *   get:
 *     tags:
 *       - Workouts
 *     responses:
 *       200:
 *         description: OK
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 status:
 *                   type: string
 *                   example: OK
 *                 data:
 *                   type: array 
 *                   items: 
 *                     type: object
 */
router.get("/", cache("2 minutes"), workoutController.getAllWorkouts);

...

这基本上就是使用 swagger 文档来添加端点的所有魔法了，你可以在他们的文档中查看所有细则。

当你重新加载文档页面，你会看到如下：

如果你熟悉 OpenAPI 文档的话，这个画面对于你来说就不陌生。在这个页面中我们会看到所有端点，并且包含每一个端点的信息。

但你仔细看会发现我们还没有定义正确的返回值，因为我们的 “data” 属性仅设定为一个空对象。

这时模式（schema）就发挥了作用。

// 在src/databse/Workout.js
...

/**
 * @openapi
 * components:
 *   schemas:
 *     Workout:
 *       type: object
 *       properties:
 *         id: 
 *           type: string
 *           example: 61dbae02-c147-4e28-863c-db7bd402b2d6
 *         name: 
 *           type: string
 *           example: Tommy V  
 *         mode:
 *           type: string
 *           example: For Time
 *         equipment:
 *           type: array
 *           items:
 *             type: string
 *           example: ["barbell", "rope"]
 *         exercises:
 *           type: array
 *           items:
 *             type: string
 *           example: ["21 thrusters", "12 rope climbs, 15 ft", "15 thrusters", "9 rope climbs, 15 ft", "9 thrusters", "6 rope climbs, 15 ft"]
 *         createdAt:
 *           type: string
 *           example: 4/20/2022, 2:21:56 PM
 *         updatedAt: 
 *           type: string
 *           example: 4/20/2022, 2:21:56 PM
 *         trainerTips:
 *           type: array
 *           items:
 *             type: string
 *           example: ["Split the 21 thrusters as needed", "Try to do the 9 and 6 thrusters unbroken", "RX Weights: 115lb/75lb"]
 */

...

在上面的示例中，我们创建了第一个模式，通常在你的模式或者模型文件（model file）中的定义的是数据模型。

这也很简单明了。我们定义了所有训练的属性，包括种类和例子。

再次浏览文档页面，你会看到另一个由模式主导的板块。

我们可以在端点的响应中引用这个模式。

// 在src/v1/routes/workoutRoutes.js
...

/**
 * @openapi
 * /api/v1/workouts:
 *   get:
 *     tags:
 *       - Workouts
 *     responses:
 *       200:
 *         description: OK
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 status:
 *                   type: string
 *                   example: OK
 *                 data:
 *                   type: array 
 *                   items: 
 *                     $ref: "#/components/schemas/Workout"
 */
router.get("/", cache("2 minutes"), workoutController.getAllWorkouts);

...

仔细看最底部的评论，在 “item” 内部，我们使用了 “$ref” 来创建引用，引用我们在训练文件中定义的模式。

现在我们就可以完整地展示训练的响应了。

很不错！你可能会认为“编写这些评论很繁琐”。

这或许是真的，但是可以这样想，写在代码中的评论里可以帮助你作为一个 API 开发者更好地了解你的 API。当你想要了解某一个端点的时候，你不要阅读所有文档，你可以直接在代码中找到。

为端点写文档也可以帮助你更好的了解这些端点，“逼迫”自己去思考在实现的过程当中缺失了什么。

你看我确实忘记了一些东西，我忘记写可能出现的错误响应，查询参数也缺少了。

让我们调整一下：

// 在src/v1/routes/workoutRoutes.js
...

/**
 * @openapi
 * /api/v1/workouts:
 *   get:
 *     tags:
 *       - Workouts
 *     parameters:
 *       - in: query
 *         name: mode
 *         schema:
 *           type: string
 *         description: The mode of a workout
 *     responses:
 *       200:
 *         description: OK
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 status:
 *                   type: string
 *                   example: OK
 *                 data:
 *                   type: array 
 *                   items: 
 *                     $ref: "#/components/schemas/Workout"
 *       5XX:
 *         description: FAILED
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 status: 
 *                   type: string
 *                   example: FAILED
 *                 data:
 *                   type: object
 *                   properties:
 *                     error:
 *                       type: string 
 *                       example: "Some error message"
 */
router.get("/", cache("2 minutes"),  workoutController.getAllWorkouts);

...

当你查看评论最上方 “tag” 内部，会发现我添加了另一个键叫做 “parameters”，这里可以定义我们过滤所需的查询参数。

我们的文档也会展示出来：

现阶段展示可能出现的错误，我们只用抛出 5XX 报错就行。所以在 “responses” 内部，我们可以定义另一个文档。

现在我们的文档页面如下：

很棒！我们已经给一个端点创建了完整的文档，我强烈建议你为剩下的端点创建对应的文档，在这个过程中你会学到很多东西。

你或许也体会到了为 API 写文档并不总是一件头疼的事，使用我介绍给你的工具可以减轻你不少负担，搭建过程也十分简单明了。

这样你就可以把注意力集中在重要的事情上，编写文档内容。swagger 和 OpenAPI 的文档非常不错，在网络上你也可以找到其他的优秀例子。

那么因为太多“额外”工作而不写文档这个理由现在就不成立了。

总结

呼！这是一趟有趣的旅程！我非常享受写这篇文章也从中学习了很多。

这些最佳实践中有一些可能很重要。另一些可能不适用于你现在的情况。没关系，正如我一开始说的那样，对于开发者来说最重要的是能够根据情况挑选出最适合自己的方法。

我尽力把所有最佳实践融汇到这个 API 项目中，我从中获得非常多的乐趣。

我十分乐意接受各种反馈，任何你想要告诉我的事情（好的或坏的），别迟疑，请告诉我：

这是我的Instagram（你也可以关注我在软件工程师的成长道路上的见闻）。

下篇文章见！

如何使用 REST API

PapayaHUANG — Fri, 29 Apr 2022 02:23:00 +0000

原文：How to Use REST APIs – A Complete Beginner's Guide，作者：Alex Husar

应用程序编程接口（API）是一个需要掌握的重要编程概念。如果花时间学习这些接口，你就可以更轻松地管理任务。

最常见的API之一就是REST API。如果你曾经尝试过从另一个网站（如：Twitter或Github）上获取数据，你可能已经使用过这个API。

那为什么理解REST API对你有帮助？REST API是如何确保现代业务的连通性的？

在创建或者运行一个API（这里特指REST API）之前，你得先学习什么是API。这篇文章会带着你一步一步理解REST API的基本原则，以及这些原则如何使得REST API成为强大的应用。

API是如何工作的，我们为什么需要它？

API代表一组定义和协议。你需要使用API来开发和集成应用，因为API可以协调两个软件之间的数据交换，如信息供应商（服务器）和用户之间。

客户向生产商发出调用，生产商返回响应。API规定了返回的可访问内容。

程序使用API进行通信、检索信息或执行功能。API允许用户通过这一系统返回想要的结果。

简言之，API就是用户（客户）和资源（服务器）之间的中间人。

当用户发出API请求或者浏览一个在线商城，会期望快速得到反馈，所以作为开发者你需要优化加载时间（参考——优化麦进斗TTFB (Time To First Byte)）或者使用其他更适合你的内容管理系统（CMS）的性能提升策略。

集成API的原因包括：

精简资源、信息共享
通过验证和定义权利的手段来控制特定人群访问特定内容
安全性和控制权
无需了解软件细节
即便使用不同的技术，服务间也可以保持持续通信

REST API概览

RESTful指的是一种软件架构，即“表现层状态转移”（Representational State Transfer)。你可能在有关制定信息交换系统（web服务）标准的内容中听到过这个表达。

web服务通过无状态协议使得在线资源由文本的方式呈现，并且可以读取和处理这些在线资源。客户端通过著名的HTTP协议进行数据获取、更新和删除。

REST于2000年被首次提出，目的是通过对API采取特定的规范来提升API的性能、可扩展性并简化API。

由于可以广泛兼容各种设备和应用，REST API变得越来越受欢迎。下图列举了使用REST API的一些场景：

1. Web使用

REST并没有限制客户端技术，因此适用于各种各样的项目，如：

web开发
iOS应用
IoT设备
Windows手机应用

因为不必拘泥于某一种客户端技术栈，所以你可以使用REST为公司搭建任意基础设施。

2. 云应用

由于无状态特性，调用REST API对于云应用来说是理想的解决方案。一旦出现问题，你可以重新部署无状态组件，组件会管理流量转移。

3. 云计算

与服务连接的API需要控制URL的解码方式，所以REST在云服务中作用巨大。

云计算和微服务的发展使得RESTful API架构在将来会成为一种常态。

REST API是如何运作的?

数据（如：图像、视频和文本）实体化了REST的资源。客户浏览一个特定的URL，并向服务器发送请求以获得响应。

REST API背后的概念

一个请求（你访问的URL）包含以下四个方面：

终点（路径），即以 root-endpoint/?为结构的URL
请求方式，有五种请求方式： GET、POST、PUT、PATCH、DELETE
请求头，包含各种功能，如信息验证以及请求体的内容(可以使用 -H或--header来发送HTTP请求头)
数据（请求体），是你通过 -d或--data向服务器发送的POST, PUT, PATCH或DELETE请求。

HTTP请求允许你使用以下方式处理数据，如：

POST请求创建记录
GET请求从服务器读取或获取资源（如图像文件或者其他资源合集）
PUT和PATCH请求更新记录
DELETE请求服务器删除某个资源

这四种方式可以总结为CRUD（增删查改）：建立（Create）、读取（Read）、改正（Update）和删除（Delete）。

服务器使用以下格式向客服端发送数据：

HTML
JSON (由于其独立于计算机语言以及人机都可以访问的特性，这是目前最常用的格式)
XLT
PHP
Python
纯文本

为什么使用REST API?

选择REST而不是其他的API，如SOA是出于一系列原因，比如：REST易于扩展、操作灵活、可移植性和独立性。

不依赖项目架构

独立运行的客户端和服务器意味着开发者不受任何项目部分的约束。由于REST API的自适应，开发者可以分别开发各个部分，互不打扰。

可移植性和适应性

REST API仅当某个请求的数据发送成功时运作。你可以从一个服务器迁移到另一个服务器，并且随时更新数据。

可在未来扩展项目

由于客户端和服务器相互独立，开发者可以迅速开发产品。

RESTful架构的风格特征

若使用SOAP、XML-RPC这类API，开发者必须构思出严谨的架构。但是REST API与众不同，REST广泛支持数据类型，也可以使用几乎任何编程语言编写。

六种REST架构限制是设计解决方案的原则，具体如下：

1. 统一接口（一致的用户接口）

这个概念规定不论源头是哪里，所有请求同一个资源的API必须一致，即使用同一种语言。统一标识符（URI）和关联数据一一对应，如用户名或者电子邮件地址。

统一接口原则的另一个要求是信息必须是自我描述的。即信息必须是服务器可以理解并决定如何处理的（如，请求类型、MIME类型等）。

2. 客户端和服务器分离

REST架构风格采取了特殊的方式实现客户端和服务器。也就是说，客户端和服务器可以在不知道彼此的情况下实现。

例如，客户端仅使用统一标识符（URI）请求资源，并不能使用其他方式和服务器通信。同时，服务器无法影响客户端，仅通过HTTP协议传输必要的数据。

这意味着你可以随时修改客户端代码，完全不影响服务器的运行。

这同样适用于服务器：改变服务端的代码不会影响客户端的运行。

你可以保持客户端和服务器程序的模块化和独立性，只要两边都知道向对方发送什么格式的信息就行。

将用户接口问题和数据存储限制分离的好处是什么呢？我们提高了接口的灵活性，可以跨不同平台使用，并且提高了扩展的可能。

另外，每一个组件从分离受益，因为组件可以独立进化。一个REST接口可以帮助不同的客户端：

访问相同的REST终点
执行相同的活动
获得相同的响应

3. 客户端和服务器之间的无状态通信

基于REST的系统是无状态的，意味着客户端状态对于服务器来说未知，反之亦然。这样的限制可以确保服务器和客户端之间理解每条信息，即便是上一条信息不知情的情况下。

为了加强对无状态的限制，你必须使用资源而非命令。资源是网络的名词。使用名词的目的是描述你想要从其他服务获取或者通信的对象。

你可以在不影响这个系统的情况下控制、改变以及复用组件，所以限制的好处包括：

稳定性
速度
RESTful应用的可扩展性

注意每一个请求必须包括你想要的所有信息，这个请求才得以完成。客户端必须保存会话状态，因为服务端不会存储和请求相关的任何数据。

4. 可缓存数据

REST要求在可能的情况下缓存服务端和客户端的资源。网络发展到今天，数据和响应的缓存对于客户端性能提升至关重要。

这对用户有什么影响？一个管理良好的缓存可以减少客户端的通信。

缓存也增加了服务器扩展的可能性，因为这样减轻了服务器的任务压力。缓存提高了页面加载的速度，同时也使得用户可以在不需要网络连接的情况下浏览之前浏览过的内容。

5. 分层系统架构

RESTful分层架构也是我们要讨论的一个限制。这个原则是将特定功能的层分到一组。

REST API的层各司其职，并且按层次顺序排列。例如，第一层是负责从服务器存储数据的，第二层就负责从另一个服务器部署API，第三层就负责从再一个服务器验证请求。

这些分层像中间人一样防止服务器和客户端直接通信。所以，客户端并不知道他们的请求发送给了哪一个服务器或者组件。

在传输信息前每一层各司其职意味着什么？这样可以提高API整体的安全性和灵活性，因为增加、修改或者删除API都不会影响其他接口组件。

6. 按需编码（非强制性）

使用REST API最常见的场景是传输如XML或者JSON格式的静态资源。

这样的架构风格方便用户以Java小程序或脚本（JavaScript）的形式来下载并运行代码。例如，客户端可以调用API来检索和渲染UI插件的代码。

使用REST API面临的挑战

了解REST API的设计和架构限制后，你需要了解使用这种架构风格将迎接的问题：

REST终点的一致性

无论URL如何构造，API都应该保持一致。但随着可用组合方法数量的增加，保持大型代码库的一致性变得越来越难。

REST API的特性版本

API需要定期更新或控制版本以防止兼容性问题。旧版本的终点保持运行常常会增加工作量。

大量认证方式

你可以限制特定用户访问特定资源。比方说，你可以决定哪一个第三方服务器可以访问顾客的电子邮箱地址或者其他的敏感信息，以及服务器可以对这个信息做什么。

但20个各不相同的认证方式会导致初始化API调用变得十分复杂。这一初始化难题使得开发者不愿意推进项目进展。

REST API的安全弱点

尽管RESTful API是分层结构，仍存在安全隐患。例如一个应用因为缺乏加密而不够安全，就会泄露敏感数据。

又比如黑客每秒发送成千上万的API请求，导致DDoS攻击，或者采用其他滥用API服务的行为，使服务器崩溃。

过量的数据收集和请求

服务器可能会返回一个请求的所有信息，有时是没有必要的。或者你需要运行多个请求来获取有用的信息。

总结

毫不意外API会在未来简化web通信。API的目的就是助力web应用的通信和数据的共享。

通过开发强大且富有创造性的系统，API帮助在线业务的发展。随着API架构的进化，会出现更加轻量、更灵活的变体，这对于手机应用和分散网络的发展至关重要。

在这篇文章中你学习了REST API的基础。

如何使用 Node、Express 和 MongoDB 构建一个 RESTful API

luojiyin — Mon, 14 Mar 2022 09:00:00 +0000

原文：How to Build a RESTful API Using Node, Express, and MongoDB，作者：Nishant Kumar

在这篇文章中，我们将使用 Node、Express 和 MongoDB 构建一个 RESTful API。我们将为创建数据、读取数据、更新数据和删除数据（基本 CRUD 操作）创建端点（endpoints）。

但在我们开始之前，请确保你的系统中已经安装了 Node。如果没有，请到 https://nodejs.org/en/download/ 下载并安装它。

让我们先做一下基本设置

在一个空文件夹中，运行以下命令：

npm init

这个命令会问你各种细节，比如你的项目名称、作者、存储库等等。然后它将在该文件夹中生成一个 package.json 文件。

{
  "name": "rest-api-express-mongo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Package.json file

这个 Package.json 文件将包含所有的脚本，如如何运行应用程序，或如何测试应用程序，以及所有的依赖。

我们现在需要安装一些依赖项。

npm i express mongoose nodemon dotenv

这里，

Express 将被用于中间件，以创建各种 CRUD 端点
Mongoose 用于使用各种查询来管理 MongoDB 中的数据
Nodemon 用于在我们每次保存文件时重新启动我们的服务器
Dotenv 管理 .env 文件

因此，请继续安装它们。

在它们完成安装后，创建一个名为 index.js. 的文件，这将是我们应用程序的入口。

而在这个文件中，让我们添加 Express 和 Mongoose，并运行该文件。

const express = require('express');
const mongoose = require('mongoose');

现在，将 Express 的内容转移到一个名为 app 的新常量中。

const express = require('express');
const mongoose = require('mongoose');

const app = express();

现在，让我们修改这个文件，在 3000 端口监听。

const express = require('express');
const mongoose = require('mongoose');

const app = express();

app.use(express.json());

app.listen(3000, () => {
    console.log(`Server Started at ${3000}`)
})

现在，服务器被设置在 端口3000。让我们写脚本来启动我们的服务器。我们还添加了 app.use。在这里面，我们有一个代码片段，允许我们接受 JSON 格式的数据。

在package.json文件中，添加一个脚本，内容如下：

"scripts": {
    "start": "nodemon index.js"
},

这意味着我们可以使用 npm start 启动我们的服务器，它将使用我们之前安装的 Nodemon 包运行。

在终端中输入 npm start，我们将在终端中看到以下输出:

如何配置 MongoDB 数据库

现在，让我们来配置 mongoDB 数据库。前往 https://account.mongodb.com/account/login 并创建你的账户，如果你已经有一个账户，则可以登录。

登录后，我们要创建一个数据库。

因此，创建一个 Free Shared Cluster。

它将会要求你输入用户名和密码，输入它们。

然后，添加你的 IP 地址。

点击完成并关闭。

我们的集群将需要一些时间来完成，所以让我们等待吧。同时，在项目文件夹中创建一个名为 .env 的文件。

并在集群主页中，点击连接按钮。

将出现以下窗口：

点击 MongoDB Compass，它将返回以下字符串。同时，下载并安装 MongoDB Compass。

将你的用户名和密码添加到这个你以前使用过的字符串中。最后的连接字符串将看起来像这样:

mongodb+srv://nishant:********@cluster0.xduyh.mongodb.net/testDatabase

这里，nishant 是用户名，其次是密码，最后是数据库名称。

所以，把这个字符串粘贴到 .env 文件中。

DATABASE_URL = mongodb+srv://nishant:*******@cluster0.xduyh.mongodb.net/testDatabase

现在在 MongoDB Compass 中，也添加这个字符串。

然后，点击 Connect。

在这里，我们将得到两个数据库，这是默认的。第三个将在以后自动创建。

现在，让我们在脚本文件 index.js 中导入我们的 .env 文件的内容。

require('dotenv').config();

const mongoString = process.env.DATABASE_URL

在这里，我们将字符串存储到一个名为 mongoString. 的变量中。

现在，让我们使用 Mongoose 将数据库连接到我们的服务器。

mongoose.connect(mongoString);
const database = mongoose.connection

现在，我们必须根据我们的数据库连接是成功还是失败，抛出一个成功或错误信息。

database.on('error', (error) => {
    console.log(error)
})

database.once('connected', () => {
    console.log('Database Connected');
})

这里，database.on 意味着它将连接到数据库，如果连接失败，将抛出任何错误。而 database.once 意味着它将只运行一次。如果它成功了，它将显示一条信息：数据库已连接。

以下是到此为止的全部代码：

require('dotenv').config();

const express = require('express');
const mongoose = require('mongoose');
const mongoString = process.env.DATABASE_URL;

mongoose.connect(mongoString);
const database = mongoose.connection;

database.on('error', (error) => {
    console.log(error)
})

database.once('connected', () => {
    console.log('Database Connected');
})
const app = express();

app.use(express.json());

app.listen(3000, () => {
    console.log(`Server Started at ${3000}`)
})

如何为端点（Endpoints）创建我们的路由

创建一个名为 routes 的文件夹，并在里面制作一个名为 routes.js 的文件。

将此文件导入我们的主脚本文件 index.js 中。

const routes = require('./routes/routes');

另外，让我们使用这个路由文件（routes.js）。

const routes = require('./routes/routes');

app.use('/api', routes)

这里，这个 app.use 需要两样东西。一个是基础端点（base endpoint），另一个是路由的内容。现在，我们所有的端点将从'/api'开始。

我们会得到一个错误，因为我们在路由文件里面没有任何东西。所以，让我们添加它们。

const express = require('express');

const router = express.Router()

module.exports = router;

在这里，我们使用 Express 中的 Router，并且我们也使用 module.exports 导出了它。现在，我们的应用程序可以正常工作了。

如何编写我们的端点（Endpoints）

现在，让我们在这个路由文件中写入我们的端点。我们将有五条路由用于以下 actions：

将数据发布到数据库
从数据库中获取所有数据
获取基于 ID 的数据
基于 ID 更新数据
根据 ID 删除数据

因此，让我们为这些 actions 创建路由：

//Post Method
router.post('/post', (req, res) => {
    res.send('Post API')
})

//Get all Method
router.get('/getAll', (req, res) => {
    res.send('Get All API')
})

//Get by ID Method
router.get('/getOne/:id', (req, res) => {
    res.send('Get by ID API')
})

//Update by ID Method
router.patch('/update/:id', (req, res) => {
    res.send('Update by ID API')
})

//Delete by ID Method
router.delete('/delete/:id', (req, res) => {
    res.send('Delete by ID API')
})

我们有五个方法，使用 REST 方法的 Post、Get、Patch 和 Delete。

这个路由器把路由作为第一个参数。然后，在第二个参数中，它正在接受一个回调。

在回调中，我们有一个 res 和一个 req。res 表示响应，req 表示请求。我们使用 res 来向我们的客户端，如 Postman，或任何前端客户端发送响应。而我们使用 req 来接收来自客户端应用程序（如 Postman）或任何前端客户端的请求。

然后在回调 body 中，我们要打印一条消息，说明是响应 API 消息。

保存这个，然后打开 Postman 来检查端点（endpoints）。如果你没有，请下载 Postman。它是测试 API 端点的一个好工具。

在地址栏中添加这个地址，然后点击发送，或按回车键。

我们将在 Postman 的正文中得到这个消息，因为我们只是使用 res.send. 发送一个消息。

现在，让我们从一个客户应用中获取一个响应。让我们简单地打印一个 ID。

我们必须首先改变 getOne 函数。我们使用 req.params.id 获取 ID，然后使用 res.send. 将其发送到客户端应用程序。

//Get by ID Method
router.get('/getOne/:id', (req, res) => {
    res.send(req.params.id)
})

localhost:3000/api/getOne/1000

在地址栏中添加这个端点（endpoint）。这里，我们使用 getOne 端点，后面是 ID。然后，点击发送。

我们将在 Postman 的响应 body 中获得 ID。

如何创建模型

现在，让我们创建一个模型，它将定义我们的数据库结构。

创建一个名为 model 的文件夹，里面有一个名为 model.js 的文件。

const mongoose = require('mongoose');

const dataSchema = new mongoose.Schema({
    name: {
        required: true,
        type: String
    },
    age: {
        required: true,
        type: Number
    }
})

module.exports = mongoose.model('Data', dataSchema)

在这里，我们有一个定义数据库结构的模式，它有一个 name 和一个 age 属性。这两个字段都有类型，而且都是必填的。

然后，我们简单地导出模式模型。

现在，在 routes.js 文件中导入这个模型。

const Model = require('../models/model');

如何向数据库 post 数据

让我们使用刚刚创建的模型创建要发布（post）的数据体。

router.post('/post', (req, res) => {
    const data = new Model({
        name: req.body.name,
        age: req.body.age
    })
})

我们的 name 和 agg 是接受来自 req body 的 name 和 age。我们从客户端应用如Postman，或任何前端客户端如 React 或 Angular. 获得这些数据。

我们还将创建一个try-catch块来处理成功信息和错误。

//Post Method
router.post('/post', (req, res) => {
    const data = new Model({
        name: req.body.name,
        age: req.body.age
    })

    try{

    }
    catch(error){
        
    }
})

在尝试块中，我们使用 data.save() 来保存 data。然后，我们将数据存储在一个叫做 dataToSave 的常量中。

我们还将成功的消息与数据一起发送到响应体中（response body）。

在 catch 块中，我们将接收任何错误，如果我们得到任何错误。

//Post Method
router.post('/post', (req, res) => {
    const data = new Model({
        name: req.body.name,
        age: req.body.age
    })

    try {
        const dataToSave = data.save();
        res.status(200).json(dataToSave)
    }
    catch (error) {
        res.status(400).json({message: error.message})
    }
})

现在，让我们从 Postman 添加一些数据。但在这之前，这个函数需要异步工作。所以，我们将使用 async-await。

router.post('/post', async (req, res) => {
    const data = new Model({
        name: req.body.name,
        age: req.body.age
    })

    try {
        const dataToSave = await data.save();
        res.status(200).json(dataToSave)
    }
    catch (error) {
        res.status(400).json({message: error.message})
    }
})

如果我们在正文中添加数据并点击发送，我们将得到以下结果：

它也在生成一个唯一的 ID。打开 MongoDB Compass 应用程序，你会看到数据库和你刚刚创建的这条记录。

如何获得所有数据

获取数据也很简单，只需几行代码：

router.get('/getAll', async (req, res) => {
    try{
        const data = await Model.find();
        res.json(data)
    }
    catch(error){
        res.status(500).json({message: error.message})
    }
})

这里，我们使用 Model.find 方法从数据库中获取所有数据。然后，我们将其以 JSON 格式返回。如果我们有一个错误，我们也会得到它。

如果我们在 Postman 中调用这个端点（endpoint），我们将在 Postman 主体中得到一个对象的数组。

如何根据 ID 获取数据

这个方法也很简单。我们只需要在一个叫做 findById 的方法中传递文档的 ID，也就是 req.params.id。

//Get by ID Method
router.get('/getOne/:id', async (req, res) => {
    try{
        const data = await Model.findById(req.params.id);
        res.json(data)
    }
    catch(error){
        res.status(500).json({message: error.message})
    }
})

如果我们点击发送，我们将根据 ID 获得数据。

如何根据 ID 来更新和删除数据

首先，让我们使用 补丁（patch） 方法来针对更新方法。

//Update by ID Method
router.patch('/update/:id', async (req, res) => {
    try {
        const id = req.params.id;
        const updatedData = req.body;
        const options = { new: true };

        const result = await Model.findByIdAndUpdate(
            id, updatedData, options
        )

        res.send(result)
    }
    catch (error) {
        res.status(400).json({ message: error.message })
    }
})

在这里，我们有三个参数传递给 findByIdAndUpdate 方法，我们用它来通过 ID 找到一个文档并更新它。

其中 req.params.id 是常量 id，updatedData 包含 req.body，还有 options，它指定了是否在 body 中返回更新的数据。

现在我们来测试一下。只要粘贴一个特定文件的 ID，然后点击发送，也要改变端点（endpoints）。

我们正在使用一个 ID 进行更新，而且它正在被更新。

删除也很简单，让我们来实现它：

//Delete by ID Method
router.delete('/delete/:id', async (req, res) => {
    try {
        const id = req.params.id;
        const data = await Model.findByIdAndDelete(id)
        res.send(`Document with ${data.name} has been deleted..`)
    }
    catch (error) {
        res.status(400).json({ message: error.message })
    }
})

我们在这里获取 ID，然后使用 Model.findByIdAndDelete 来删除该字段，同时传递 ID。

我们将更新的数据存储在一个常量 data 中。

在响应中，我们将得到这样的消息：具有特定名称的文档已经被删除。

如果我们测试一下，我们会得到以下结果：

所以，所有五个方法都完成了。我们可以发布数据和获取所有的数据（也基于 ID）。我们还可以更新它们和删除它们。

谢谢你阅读本文

在这篇文章中，你了解了如何使用 Node、Express 和 MongoDB 设计和开发一个 RESTful API。

现在你可以使用这些端点来构建一个全栈应用程序，使用 Vanilla JavaScript、React、Angular、Next 或 Vue.js。

你也可以看看我关于同一主题的视频，RESTful APIs - 使用 Node、Express 和 MongoDB 构建 RESTful API

欢迎从 GitHub 下载代码并进行实验。

祝你学习愉快！

做轮子·实现路由的两种思路

开发者小蓝 — Sat, 13 Feb 2021 09:00:00 +0000

本文指的路由，不是路由器，也不是PS4（5？），是特指后端API框架里的router，前端路由也有可以有借鉴的部分，但本文不承诺正确性。

今天不妨讨论个不那么大的话题，restful路由的实现。

我们眼中的路由是什么样子的？

我们常见的路由是这个样子的

router.get('/what/i/want', ... );

router.get('/what/i/hate', ... );

router.get('/what/u/want', ... );

我们今天就来讨论一下，当我们想访问 /what/i/want时，都有些什么玄机。

路由是怎么工作的

首先明确路由的目的，就是根据接收到的路径字符串，找到对应的业务处理逻辑。

为了弄明白业界常用框架对这一块，我专门查阅了若干开发框架的源码（express, koa, Gin, kratos, Lumen），最终概括成两种实现手段。

Key - Value 型路由
Tree 型路由

现在来分析一下两种路由的特性和适用场景。

Key - Value 型路由

这个模式，形如我们熟悉的hash table、字典，通过键值对维护这uri与函数的对应关系。

我们理所当然地认为，只要确定的访问地址，如/what/i/want, 就能立即找到对应的业务方法functionA，是个铁骨铮铮的 O(1)操作。

当一个操作的复杂度与规模无关，就是一个O(1)的操作。比如无论我的 uri 地址有多少个，只要确定 uri 的值，总是能立即确定与之对应的方法。

然而遗憾的是，我就没见到有这么实现路由的。

真实的情况是，

Key - Value 型路由会从前到后一个一个比较，直到找到一个能匹配当前 uri 的key，再确定它对应的 function

所以实际上它是一个 O(n) 操作，平均情况下需要比较 N/2 次才能定位。

一个 O(n) 操作，其复杂度会随着数据规模的增大而线性增长，而我们普遍认为，在经过多次测量观察后，平均情况下会在 N/2 的位置上找到答案。

疑惑归疑惑，正如本文的作者一样，做轮子人并不是疯了。

之所以采用这种逐个匹配的模式，是因为我们的uri通过是不能确定的。

比如，一些uri里甚至包含了变量

GET /staff/9527

GET /staff/709394

所以，我们通常是吧 Key - Value里面的Key，设计成正则表达式。

相应的，在理论研究中的Hash Table也会被顺序表替代。

总结起来就是，

当我们访问一个确定的uri时，路由会尝试按顺序逐个匹配注册好的正则表达式，直到match到一个结果。

否则，返回 404

升华一下

如何压榨这种路由的性能？既然是按顺序逐个匹配，那我们就根据自己的业务特点，把可能访问量最大的接口注册到前面去。

也有一些框架是会动态调整顺序的，这就是题外话。

Tree 型路由

这个模式相对来说思路要骚一些。

它把uri按照/分割一个，在之前构建好的路由树里，一个节点一个几点的检索，直到成功走到一个叶子节点。

与上面提到的N/2次比较相比，这个模式的比较次数比较稳定，就是uri的层数。

对于 /what/i/want，我们认为它是一个 3 层的地址，如果这个地址是存在的，那么在比较3次以后，就能找到对应的答案。

真是 “遇事不决，数据结构” 啊

这种树形的路由特别适合restful风格的API，因为我们设计restful接口的时候，通常每一层都有它自己的类聚含义，所以它会构建出一棵非常标致的树。

问(gang)题(jing)来了

Q1: 请问 Tree 型路由怎么解决uri里有变量的情况呢？

很巧妙。当你注册的路由包含了变量，比如 /staff/:id这样的，它会在这个树staff的子节点里，也就第二层，创建一个通配节点（可能是*）。

它认为，不管staff后面跟什么内容，都能匹配这个*

Q2: 如果我同时注册了/staff/:id和/staff/list呢？会匹配错吗？

考虑到这种情况，Tree 型路由的一般实现是，优先匹配确定值list，次要匹配*。

有这种情况是要复杂一些，不过并不影响它的整体复杂度。

最后，作者喜欢哪一种？

尽管我在最近开发的一个框架里使用了Tree 型路由，这并不代表我的倾向。

实际上应该根据上文提到两种模式各自的特点，选择最好的实现方式。

当然

我期待读者自己做轮子的时候，能做出一个根据开发者注册的路由的特点，自动选择路由模型的智能路由。

好了，今天先到这里，下次再会。