我将在这篇文章中分享在 Express 中构建强大的 REST API 的方法。首先，我会介绍构建 REST API 的一些挑战，然后提出一个使用开放标准的解决方案。

本文并非一篇关于 Node.js、Express.js 或 REST API 的介绍。如果你需要复习，请在深入研究本文内容之前查看这些链接。🤿

我喜欢 Node.js 那极具灵活性和易用性的生态。这个社区充满活力，并且你可以用你已经掌握的语言在几分钟内设置一个 REST API。

在应用的前后端使用相同的编程语言是一件很有价值的事。这使我们在浏览代码库时可以减少上下文切换，从而变得更轻松。全栈开发者可以快速切换技术栈，共享代码也变得轻而易举。

尽管如此，随着 MVP 成长为成熟的生产环境应用程序和开发团队规模的扩大，这种灵活性也带来了挑战。

使用 REST API 的挑战

无论你使用哪种技术栈，当代码库和团队规模增长时，都会面临许多挑战。

在本文中，我将描述通过 REST API 暴露业务逻辑的 Express.js 应用程序所带来的挑战，以小见大。

无论 API 消费者的性质如何（网页、移动应用、第三方后端），随着他们的成长，他们都可能面临以下一个（或多个）挑战：

1. ⚠️ 更难做出改变

在文档不够明确时，在 REST API 的任何一方进行修改都变得更加困难。

举个例子，假设你有一个 REST 端点，可以返回一个特定的用户的名字。在即将新增的功能中，你可能需要修改这个 API 使其返回年龄。这可能会潜在地破坏网络应用和移动应用。

你可以设置集成测试来一定程度上避免这个问题，但你仍然会严重依赖开发人员来手动覆盖所有的边界情况。这需要大量的时间和精力，而且你永远无法 100% 确定这些变化不会破坏应用程序。

2. 📜 缺少（及时更新的）文档

文档是构建 REST API 时的另一个敏感话题。我坚信在大多数情况下，代码本身应该足以代替一部分文档。

也就是说，REST API 在开发中会变得越来越复杂，检查代码中每个端点的安全性、参数和可能的响应也随之变得繁琐且耗时。这就减慢了开发的速度，也给 bug 进入系统留下了隐患。

即使团队致力于在一个独立于代码的文档中手动保持文档的更新，也很难 100% 确保它反映了代码的情况。

3. 📢 公共 API

这并不适用于所有的应用程序，但在某些情况下，一个应用程序可能需要向第三方暴露一系列的功能。对于这种情况，第三方有可能会在我们暴露的 API 之上构建核心功能。

这意味着我们不能以更新我们的私有 API 的同样速度来修改这些公共 API。一旦修改了公共 API，第三方应用程序可能会因此崩溃，而这正是我们应该不惜一切代价避免的事情。

公共 API 所暴露的内容应该是明确的，并且可以简单地进行开发，以限制内部和外部开发团队之间所需的来回沟通的数量。

4. ✍️ 手动集成测试

当应用程序的开发没有与之匹配的周密计划时，很有可能 API 所提供的内容和 API 消费者期望的内容被深埋在代码中。

对于仅有少量的内部端点的系统来说，这并不是一个大问题。但随着 API 接口数量的增长，修改现有的端点需要在整个系统中遵循面包屑，以确保消费者期望得到的东西与提供的东西是相等的。

这个问题可以通过对系统的不同部分之间进行集成测试来缓解。但是人工完成这件事的工作量非常巨大的，并且如果没做好的话，可能会在系统实际上不能正常工作的时候让开发人员误以为系统状态良好。

提出的解决方案

我们已经看到了构建 REST API 所带来的固有挑战。在下一节中，我们将使用开放标准构建一个示例 Express 项目，以解决这些挑战。

API 标准规范

前面部分描述的挑战已经存在很长时间了，所以面对这个问题，我们最好查看现有的解决方案，而不是重新发明轮子。

许多标准尝试对 REST API 进行规范化定义（RAML、JsonAPI、OpenAPI......）。这些项目的共同目标是使开发人员更容易定义他们的 API 行为，以便跨多种语言的服务器和客户端能够“共说一种语言”。

有了某种形式的 API 规范，可以解决许多挑战，因为在许多情况下，可以从这些规范自动生成客户端 SDK、测试、模拟服务器和文档。

一种我最喜欢的规范是 OpenAPI（原名 Swagger）。它有一个很大的社区，并且有很多用于 Express 的工具。这可能不是所有 REST API 项目中的最佳工具，因此请在为你自己的项目选择规范之前进行额外的研究，以确保该规范的工具和支持对你的项目有帮助。

示例的背景

在这个示例中，假设我们正在构建一个待办事项列表管理应用。用户可以通过访问一个 web 应用来获取、创建、编辑和删除待办事项，这些待办事项被保存在后端。

在这个例子中，后端使用一个 Express.js 应用程序，它将通过 REST API 暴露以下功能：

• 获取待办事项: [GET] /todos
• 创建待办事项：[POST] /todos
• 编辑待办事项：[PUT] /todos/:id
• 删除待办事项：[DELETE] /todos/:id

对于一个真实的待办事项管理应用来说，上面的功能有点过度简化，但这有助于展示我们如何在实际情况下克服上面提出的挑战。

实现

很好，现在我们已经介绍了 API 定义的开放标准和背景，让我们来实现一个 Express 待办事项应用，演示怎么解决前面的挑战。

我们将使用 Express 库 express-openapi 的 OpenAPI。请注意，这个库提供的高级功能（响应验证、认证、中间件设置......）超出了本文的范围。

你可以在这个仓库中找到演示的完整代码。

1. 初始化一个 Express 框架，并初始化一个 Git 仓库：

npx express-generator --no-view --git todo-app
cd ./todo-app
git init
git add .; git commit -m "Initial commit";

2. 将 express-openapi 引入我们的程序：

npm i express-openapi -s

// ./app.js

...

app.listen(3030);

...

// OpenAPI routes
initialize({
  app,
  apiDoc: require("./api/api-doc"),
  paths: "./api/paths",
});

module.exports = app;

3. 添加 OpenAPI 基础模型。

请注意，模型中定义了 Todo 的类型，将在路由处理程序中引用。

// ./api/api-doc.js

const apiDoc = {
  swagger: "2.0",
  basePath: "/",
  info: {
    title: "Todo app API.",
    version: "1.0.0",
  },
  definitions: {
    Todo: {
      type: "object",
      properties: {
        id: {
          type: "number",
        },
        message: {
          type: "string",
        },
      },
      required: ["id", "message"],
    },
  },
  paths: {},
};

module.exports = apiDoc;

4. 添加路由处理程序。

每个处理程序都声明它支持哪些操作（GET、POST ...），对每个操作的回调，以及该处理程序的 apiDoc OpenAPI 模型。

// ./api/paths/todos/index.js
module.exports = function () {
  let operations = {
    GET,
    POST,
    PUT,
    DELETE,
  };

  function GET(req, res, next) {
    res.status(200).json([
      { id: 0, message: "First todo" },
      { id: 1, message: "Second todo" },
    ]);
  }

  function POST(req, res, next) {
    console.log(`About to create todo: ${JSON.stringify(req.body)}`);
    res.status(201).send();
  }

  function PUT(req, res, next) {
    console.log(`About to update todo id: ${req.query.id}`);
    res.status(200).send();
  }

  function DELETE(req, res, next) {
    console.log(`About to delete todo id: ${req.query.id}`);
    res.status(200).send();
  }

  GET.apiDoc = {
    summary: "Fetch todos.",
    operationId: "getTodos",
    responses: {
      200: {
        description: "List of todos.",
        schema: {
          type: "array",
          items: {
            $ref: "#/definitions/Todo",
          },
        },
      },
    },
  };

  POST.apiDoc = {
    summary: "Create todo.",
    operationId: "createTodo",
    consumes: ["application/json"],
    parameters: [
      {
        in: "body",
        name: "todo",
        schema: {
          $ref: "#/definitions/Todo",
        },
      },
    ],
    responses: {
      201: {
        description: "Created",
      },
    },
  };

  PUT.apiDoc = {
    summary: "Update todo.",
    operationId: "updateTodo",
    parameters: [
      {
        in: "query",
        name: "id",
        required: true,
        type: "string",
      },
      {
        in: "body",
        name: "todo",
        schema: {
          $ref: "#/definitions/Todo",
        },
      },
    ],
    responses: {
      200: {
        description: "Updated ok",
      },
    },
  };

  DELETE.apiDoc = {
    summary: "Delete todo.",
    operationId: "deleteTodo",
    consumes: ["application/json"],
    parameters: [
      {
        in: "query",
        name: "id",
        required: true,
        type: "string",
      },
    ],
    responses: {
      200: {
        description: "Delete",
      },
    },
  };

  return operations;
};

5. 添加自动生成的文档，swagger-ui-express：

npm i swagger-ui-express -s

// ./app.js

...

// OpenAPI UI
app.use(
  "/api-documentation",
  swaggerUi.serve,
  swaggerUi.setup(null, {
    swaggerOptions: {
      url: "http://localhost:3030/api-docs",
    },
  })
);

module.exports = app;

这就是我们最终获得的效果：

这个 SwaggerUi 是自动生成的，你可以在 http://localhost:3030/api-documentation 访问它。

🎉 恭喜！

当你进行到文章的这里时，你应该创建好了一个完全可运行的 Express 应用程序，其与 OpenAPI 完全集成。

现在，通过使用在 http://localhost:3030/api-docs 中定义的模型，我们可以轻松生成测试、模拟服务器、类型，甚至客户端！

总结

我们只是浅浅涉猎了 OpenAPI 所能做到的事情。但是我希望这篇文章能够让你了解标准 API 定义模式是如何在可见性、测试、文档和整体置信度方面帮助构建 REST API 的。

谢谢你看到最后！

我目前正在构建 taggr，这是一个跨平台的桌面应用程序，它在帮助用户重新发现他们的数字记忆的同时保持他们的隐私。

Linux、Windows 和 macOS 平台上的 alpha 版本即将推出。请查看网页并登记，以免错过！

什么是 Express？

Express 是一个基于 Node.js 的 Web 框架。

Node.js 是一种搭建网络服务和应用的实用工具。

Express 搭建在 Node.js 之上，提供易于使用的功能来满足 Web 服务器的用例需求。它开源、免费、易于扩展并且非常高效。

可以使用各种各样的预构建的包来处理应用中的各项内容。

点击获取 Express 手册的 PDF 和 ePub 版本。

目录

• 如何安装 Express
• 第一个 "Hello, World"
• 请求参数
• 如何向客户端发送响应
• 如何发送一个 JSON 响应
• 如何管理 Cookies
• 如何处理 HTTP 标头
• 如何处理重定向
• Express 中的路由
• Express 中的模版
• Express 中间件
• 如何使用 Express 提供静态资源
• 如何向客户端发送文件
• Express 中的会话
• 如何在 Express 中验证输入
• 如何在 Express 中清理输入
• 如何在 Express 中处理表单
• 如何在 Express 中处理表单中的文件上传

如何安装 Express

你可以使用 npm 在任何项目中安装 Express。

如果是一个空文件夹，首先使用命令创建一个新的 Node.js 项目：

npm init -y

然后执行：

npm install express

在项目中安装 Express。

第一个 "Hello World"

我们要创建的第一个示例是一个简单的 Express Web 服务器：

请复制以下代码：

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

app.get('/', (req, res) => res.send('Hello World!'));
app.listen(3000, () => console.log('Server ready'));

并将其保存在项目根文件夹的 index.js 文件中，然后通过以下命令启动服务器：

node index.js

你可以打开浏览器并通过 localhost 导航到 port 3000，就会看到 Hello World! 信息。

上面四行代码在幕后做了很多工作：

首先我们通过 express 变量引用 express 包。

通过调用 express() 方法来实例化一个应用。

一旦创建了应用对象，就使用 get() 方法监听来自 / 路径的 GET 请求。

每一种 HTTP 方法都有一个对应的动词：get()、post()、put()、delete()和 patch()：

app.get('/', (req, res) => {
  /* */
});
app.post('/', (req, res) => {
  /* */
});
app.put('/', (req, res) => {
  /* */
});
app.delete('/', (req, res) => {
  /* */
});
app.patch('/', (req, res) => {
  /* */
});

这些方法接受一个回调函数（当请求开始时调用），我们需要处理回调函数。

可以在回调中传入一个箭头函数：

(req, res) => res.send('Hello World!');

Express 在回调中发送两个对象：req 和res，分别代表了请求（Request）和响应（Response）对象。

更多标准可以参考这里和这里。

请求是一个 HTTP 请求，它包含了所有请求信息：包括请求参数、标头、请求体等。

响应是 HTTP 响应对象，会返回给客户端。

在这个回调示例中，我们通过Response.send()方法发送 "Hello World!" 字符串给客户端。

这个方法将字符串作为请求体，传输完毕后关闭连接。

Hello World 示例中最后一行代码启动服务器，并且告诉它在 port3000监听。我们传入一个回调，当服务器准备好接受新请求时调用该回调。

请求参数

我介绍了 Request 对象是如何持有 HTTP 请求信息的。

以下是主要的属性：

如何向客户端发送响应

在 Hello World 示例中， 我们使用响应对象的send()方法来将一个简单的字符串作为响应，之后关闭连接。

(req, res) => res.send('Hello World!');

如果你传入一个字符串，它将Content-Type标头设置为text/html。

如果你传入的是对象或者数组，它将Content-Type标头设置为application/json，并将传入的对象或数组解析为JSON。

之后send()关闭连接。

send()自动设置 Content-Length HTTP 响应标头，不像 end() 需要你手动设置。

如何使用 end() 发送空响应

另一个发送响应的方式，是使用Response.end()方法，这种方法不发送任何响应体：

res.end();

如何设置 HTTP 响应状态

在响应对象使用 status() 方法：

res.status(404).end();

或者

res.status(404).send('File not found');

sendStatus() 是快捷方式。

res.sendStatus(200);
// === res.status(200).send('OK')

res.sendStatus(403);
// === res.status(403).send('Forbidden')

res.sendStatus(404);
// === res.status(404).send('Not Found')

res.sendStatus(500);
// === res.status(500).send('Internal Server Error')

如何发送一个 JSON 响应

当你在 Express 中监听路由上的连接时，回调函数将在每次网络调用时被调用，并带有一个 Request 对象实例和一个 Response 对象实例。

示例：

app.get('/', (req, res) => res.send('Hello World!'));

我们在这里使用 Response.send() 方法，接受任意字符串。

你可以使用JSON，即使用 Response.json()发送到客户端。

它接受一个对象或者数组，并在发送前将其转换为 JSON 格式：

res.json({ username: 'Flavio' });

如何管理 cookies

使用Response.cookie()方法来控制 cookies。

示例：

res.cookie('username', 'Flavio');

这个方法还接受第三个参数，这个参数包含各种选项：

res.cookie('username', 'Flavio', {
  domain: '.flaviocopes.com',
  path: '/administrator',
  secure: true
});

res.cookie('username', 'Flavio', {
  expires: new Date(Date.now() + 900000),
  httpOnly: true
});

一些你可以设置的有用的参数包括：

清除 cookie 可以使用：

res.clearCookie('username');

如何处理 HTTP 标头

如何通过请求获取 HTTP 标头值

可以使用 Request.headers 属性访问所有 HTTP 标头的值：

app.get('/', (req, res) => {
  console.log(req.headers);
});

使用Request.header() 方法获取单个请求标头的值：

app.get('/', (req, res) => {
  req.header('User-Agent');
});

如何为响应改变 HTTP 标头

可以使用 Response.set()改变 HTTP 标头值：

res.set('Content-Type', 'text/html');

Content-Type 标头的便捷方式是：

res.type('html');
// => 'text/html'

res.type('json');
// => 'application/json'

res.type('application/json');
// => 'application/json'

res.type('png');
// => image/png:

如何处理重定向

在 Web 开发中重定向很常见，可以使用 Response.redirect()实现：

res.redirect('/go-there');

这样就创建了一个 302 重定向。

可以使用以下方法创建一个 301 重定向：

res.redirect(301, '/go-there');

你可以指定绝对路径（/go-there）、绝对 URL（https://anothersite.com）、相对路径（go-there）或者 .. 返回上一层：

res.redirect('../go-there');
res.redirect('..');

你还可以重定向回 Referrer HTTP 标头值（如果未设置默认值为 /）：

res.redirect('back');

Express 中的路由

路由是确定调用 URL 时应该发生什么的过程，或者应用程序的哪些部分应该处理特定的传入请求。

在 Hello World 示例中，我们使用了这段代码：

app.get('/', (req, res) => {
  /* */
});

这里创建一个路由，访问根域 URL/，并使用 HTTP GET 方法映射到我们需要的响应。

命名参数

如果想监听自定义请求怎么办？也许我们想创建一个接受字符串并将其作为大写字母返回的服务——我们不希望参数作为查询字符串发送，而是作为 URL 的一部分发送。在这种情况下，我们使用命名参数：

app.get('/uppercase/:theValue', (req, res) =>
  res.send(req.params.theValue.toUpperCase())
);

如果发送请求到 /uppercase/test，我们会在响应体中得到 TEST。

你可以在同一个 URL 中使用多个命名参数，它们都将存储在 req.params.

如何使用正则表达式匹配路径

可以通过一条正则表达式 来匹配多个路径：

app.get(/post/, (req, res) => {
  /* */
});

以上代码将匹配 /post, /post/first, /thepost, /posting/something等路径。

Express 中的模版

Express 能够处理服务器端模板引擎。

模板引擎允许我们向视图添加数据，并动态生成 HTML。

Express 默认使用 Jade。Jade 是 Pug 的旧版本，特指 Pug 1.0。

请注意，由于商标问题，该项目在 2016 年发布第二版时，名称从 Jade 改为 Pug。你仍然可以使用 Jade，又称 Pug 1.0，但往后最好使用 Pug 2.0。

尽管 Jade 的最后一个版本已经陈旧了，但出于向后兼容的原因，它仍然是 Express 中的默认版本。

你可以在任何新项目中使用 Pug 或你选择的引擎。Pug 的官方网站是https://pugjs.org/。

可以使用许多不同的模板引擎，包括 Pug、Handlebars、Mustache、EJS 等。

要使用 Pug，我们必须先安装它：

npm install pug

在初始化 Express 应用程序时，我们需要设置它：

const express = require('express');
const app = express();
app.set('view engine', 'pug');

然后就可以在 .pug 文件中编写模板。

创建一个 about 视图：

app.get('/about', (req, res) => {
  res.render('about');
});

模板路径为views/about.pug:

p Hello from Flavio

该模板创建一个 p 标签，内容为 Hello from Flavio。

你也可以使用以下代码插入变量：

app.get('/about', (req, res) => {
  res.render('about', { name: 'Flavio' });
});

p Hello from #{name}

更多使用 Pug 的信息，可以查看 Pug 指南。

推荐你使用这个在线 HTML 到 Pug 转换器 https://html-to-pug.com/。

Express 中间件

中间件是一个挂钩到路由过程中的函数，在链中的某个点执行任意操作（取决于我们想要它做什么）。

它通常用于编辑请求或响应对象，或者在请求到达路由处理程序代码之前终止请求。

可以通过如下方法将中间件添加到执行栈：

app.use((req, res, next) => {
  /* */
});

这和定义路由类似，但是在 Request 和 Response 实例之后，我们还引用了 next 中间件函数，并分配给了next变量。

我们总是在中间件函数末尾调用next()以便将执行传递给下一个处理程序。除非我们想提前结束响应并将其发送回客户端。

通常我们通过 npm 包来使用预制的中间件。你可以在这里找到中间件列表。

其中一个预制中间件示例就是 cookie-parser，它可以将 cookie 解析为 req.cookies对象。 你可以使用 npm install cookie-parser 命令安装并使用：

const express = require('express');
const app = express();
const cookieParser = require('cookie-parser');

app.get('/', (req, res) => res.send('Hello World!'));

app.use(cookieParser());
app.listen(3000, () => console.log('Server ready'));

我们还可以将中间件函数设置为仅针对特定路由运行（而不是针对所有路由），方法是将其作为路由定义的第二个参数：

const myMiddleware = (req, res, next) => {
  /* ... */
  next();
};

app.get('/', myMiddleware, (req, res) => res.send('Hello World!'));

如果需要存储中间件生成的数据，并传递给后续中间件函数或请求处理程序，你可以使用Request.locals对象。它将该数据附加到当前请求：

req.locals.name = 'Flavio';

如何使用 Express 提供静态资源

通常图片、CSS 被存储在 public子文件夹，并暴露给根目录：

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

app.use(express.static('public'));

/* ... */

app.listen(3000, () => console.log('Server ready'));

如果在 public/有一个index.html文件，当你访问根域 URL（http://localhost:3000）时，就会提供静态资源。

如何向客户端发送文件

Express 提供了一个简便的方法将文件转换为附件传输： Response.download()。

一旦用户点击使用此方法发送文件的路由，浏览器将提示用户下载。

Response.download() 方法允许发送附加到请求的文件，浏览器不会在页面中显示它，而是将其保存到磁盘。

app.get('/', (req, res) => res.download('./file.pdf'));

在应用上下文中的示例：

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

app.get('/', (req, res) => res.download('./file.pdf'));
app.listen(3000, () => console.log('Server ready'));

你可以将文件设置为使用自定义文件名发送：

res.download('./file.pdf', 'user-facing-filename.pdf');

此方法提供了一个回调函数，你可以使用它在文件发送后执行代码：

res.download('./file.pdf', 'user-facing-filename.pdf', (err) => {
  if (err) {
    //handle error
    return;
  } else {
    //do something
  }
});

Express 中的会话

默认情况下，Express 请求是有顺序的，但请求之间没有相互链接，所以没有办法知道这个请求是否来自之前已经执行过请求的客户端。

除非使用某种识别机制，否则用户无法识别请求。

会话就应运而生。

使用会话后，你的 API 或网站的每个用户都将被分配一个唯一的会话，就可以存储用户的状态。

我们将使用 express-session 模块来演示，它由 Express 团队维护。

可以使用以下命令安装：

npm install express-session

安装完毕后，可以通过以下代码实例化：

const session = require('express-session');

它是一个中间件，所以你使用以下代码在 Express 中 安装 它：

const express = require('express');
const session = require('express-session');

const app = express();
app.use(
  session({
    secret: '343ji43j4n3jn4jk3n'
  })
);

编写完毕后，所有应用路由都使用会话。

secret是唯一的必填参数，还有许多可选参数。secret必须为一个唯一的随机字符串。

会话被添加到请求，所以可以通过 req.session访问：

app.get('/', (req, res, next) => {
  // req.session
}

该对象可用于从会话中获取数据，也可用于设置数据：

req.session.name = 'Flavio';
console.log(req.session.name); // 'Flavio'

此数据在存储时被序列化为 JSON，所以可以安全使用嵌套对象。

你可以使用会话将数据传递给稍后执行的中间件，或者稍后根据后续请求检索数据。

会话数据存储在哪里？这取决于你如何设置express-session模块。

会话数据可被存储在：

• 内存，不适用于生产
• 数据库，如 MySQL 或者 Mongo
• 内存缓存，如 Redis 或者 Memcached

在 https://github.com/expressjs/session 中有一个巨大的第三方包列表，可以实现不同兼容性的缓存存储。

所有解决方案都将会话 ID 存储在 cookie 中，并将数据保存在服务器端。客户端将在 cookie 中接收会话 ID，并将它与每个 HTTP 请求一起发送。

我们将引用该服务器端以将会话 ID 与本地存储的数据相关联。

内存是默认设置，不需要你进行特殊操作。这样很便捷，但它仅用于开发目的。

最好是选择 Redis 之类的内存缓存，需要为其设置自己的基础架构。

另一个常用管理会话的包是cookie-session，与 Redis 巨大的不同是将数据存储在客户端的 cookie。

我不建议这样做，因为将数据存储在 cookie 中意味着它存储在客户端，并在用户发出的每个请求中来回发送。它的大小也有限制，因为它只能存储 4 KB 的数据。

Cookie 也需要受到保护，但默认情况它不受保护，安全 Cookie 可以在 HTTPS 站点上使用，如果你使用代理上网，则需要配置它。

如何在 Express 中验证输入

让我们看看如何验证作为输入进入 Express 端点的任何数据。

假设你有一个接受 name、email 和 age 参数的 POST 端点：

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

app.use(express.json());

app.post('/form', (req, res) => {
  const name = req.body.name;
  const email = req.body.email;
  const age = req.body.age;
});

如何对这些结果执行服务器端验证以确保：

• name 是包含至少 3 个字符的字符串？
• email 是真正的邮箱地址？
• age 为 0 到 110 之间的数字？

在 Express 中处理来自外部的任何输入的验证的最佳方法是使用 express-validator 包：

npm install express-validator

引用包中的check和validationResult对象：

const { check, validationResult } = require('express-validator');

在post()调用中，我们将包含check()调用的数组作为第二个参数传入。每一个 check() 都接受参数名作为实参。最后调用validationResult()来验证是否有验证报错，如果有就告知客户端：

app.post(
  '/form',
  [
    check('name').isLength({ min: 3 }),
    check('email').isEmail(),
    check('age').isNumeric()
  ],
  (req, res) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(422).json({ errors: errors.array() });
    }

    const name = req.body.name;
    const email = req.body.email;
    const age = req.body.age;
  }
);

注意我使用了：

• isLength()
• isEmail()
• isNumeric()

还有更多方法，都来自 validator.js，包括：

• contains(), 检查是否包含指定值
• equals(), 检查是否与指定值相等
• isAlpha()
• isAlphanumeric()
• isAscii()
• isBase64()
• isBoolean()
• isCurrency()
• isDecimal()
• isEmpty()
• isFQDN(), 检查是否为完全合格的域名
• isFloat()
• isHash()
• isHexColor()
• isIP()
• isIn(), 检查值是否属于允许值数组
• isInt()
• isJSON()
• isLatLong()
• isLength()
• isLowercase()
• isMobilePhone()
• isNumeric()
• isPostalCode()
• isURL()
• isUppercase()
• isWhitelisted(), 检查输入是否在白名单内

你也可以使用matches()来进行正则表达式验证。

日期可以通过以下方式验证：

• isAfter(), 检查输入的日期是否在你传入的日期之后
• isBefore(), 检查输入的日期是否在你传入的日期之前
• isISO8601()
• isRFC3339()

更多如何使用验证器的方法，可以参考这份文档。

所有上述验证都可以串联起来：

check('name').isAlpha().isLength({ min: 10 });

如果有任何错误，服务器会自动发送一个响应来传达错误。例如，如果电子邮件无效，将返回以下内容：

{
  "errors": [{
    "location": "body",
    "msg": "Invalid value",
    "param": "email"
  }]
}

可以使用 withMessage()覆盖默认报错：

check('name')
  .isAlpha()
  .withMessage('Must be only alphabetical chars')
  .isLength({ min: 10 })
  .withMessage('Must be at least 10 chars long');

如果你想要编写自定义验证器，可以使用 custom 验证器。

在回调函数中，你可以通过抛出异常或返回被拒绝的 promise 来拒绝验证：

app.post(
  '/form',
  [
    check('name').isLength({ min: 3 }),
    check('email').custom((email) => {
      if (alreadyHaveEmail(email)) {
        throw new Error('Email already registered');
      }
    }),
    check('age').isNumeric()
  ],
  (req, res) => {
    const name = req.body.name;
    const email = req.body.email;
    const age = req.body.age;
  }
);

自定义验证器：

check('email').custom((email) => {
  if (alreadyHaveEmail(email)) {
    throw new Error('Email already registered');
  }
});

也可改写为：

check('email').custom((email) => {
  if (alreadyHaveEmail(email)) {
    return Promise.reject('Email already registered');
  }
});

如何在 Express 清理输入

你已经了解了如何验证从外部世界到 Express 应用程序的输入。

当运行面向公众的服务器时，你很快就会学到一件事：永远不要相信输入。

即使在客户端你已经预做了一遍清理，确保人们不会输入奇怪的内容，你仍然会受到人们使用工具（甚至只是浏览器开发工具）直接 POST 到端点的影响。

或者机器人尝试人类已知的每一种可能的攻击组合。

需要做的是在服务器端清理输入。

express-validator 包除了可以验证输入以外也可以清理输入。

假设你有一个接受 name、email 和 age 参数的 POST 端点：

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

app.use(express.json());

app.post('/form', (req, res) => {
  const name = req.body.name;
  const email = req.body.email;
  const age = req.body.age;
});

你可以这样验证输入：

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

app.use(express.json());

app.post(
  '/form',
  [
    check('name').isLength({ min: 3 }),
    check('email').isEmail(),
    check('age').isNumeric()
  ],
  (req, res) => {
    const name = req.body.name;
    const email = req.body.email;
    const age = req.body.age;
  }
);

你可以通过在验证方法之后串联清理方法来添加清理：

app.post(
  '/form',
  [
    check('name').isLength({ min: 3 }).trim().escape(),
    check('email').isEmail().normalizeEmail(),
    check('age').isNumeric().trim().escape()
  ],
  (req, res) => {
    //...
  }
);

在代码中我使用的清理方法包括：

• trim()修剪字符串开头和结尾的字符（默认为空格）
• escape()将 <, >, &, ', "和 /替换成它们对应的 HTML 实体
• normalizeEmail()规范化电子邮件地址，它接受小写邮件地址或者子地址的选项。（如 flavio+newsletters@gmail.com）

其他的清理方法包括：

• blacklist() 删除出现在黑名单中的字符
• whitelist() 删除未出现在白名单中的字符
• unescape() 将 HTML 编码的实体替换为<, >, &, ', " 和 /
• ltrim() 类似于 trim()，但只修剪字符串开头的字符
• rtrim() 类似于 trim()， 但只修剪字符串末尾的字符
• stripLow()删除通常不可见的 ASCII 控制字符

强制转换格式：

• toBoolean() 将输入字符串转换为布尔值。除了 '0'、'false' 和 '' 之外的所有内容都返回 true。在严格模式下，只有 '1' 和 'true' 返回 true。
• toDate() 将输入字符串转换为日期，如果输入不是日期，则为 null。
• toFloat() 将输入字符串转换为浮点数，如果输入不是浮点数，则转换为 NaN。
• toInt()将输入字符串转换为整数，如果输入不是整数，则转换为 NaN。

与自定义验证器一样，你可以创建自定义清理器。

在回调函数中，你只需返回清理后的值：

const sanitizeValue = (value) => {
  //sanitize...
};

app.post(
  '/form',
  [
    check('value').customSanitizer((value) => {
      return sanitizeValue(value);
    })
  ],
  (req, res) => {
    const value = req.body.value;
  }
);

如何在 Express 中处理表单

以下是一个 HTML 表单示例：

<form method="POST" action="/submit-form">
  <input type="text" name="username" />
  <input type="submit" />
</form>

当用户按下提交按钮时，浏览器会自动向页面同源的/submit-form URL 发出 POST请求。浏览器发送表单包含的数据，编码为 application/x-www-form-urlencoded。在此特定示例中，表单数据包含username输入字段值。

表单也可以通过 GET 方法发送数据，但是大多数情况为POST。

表单数据将在 POST 请求体中发送。

可以使用express.urlencoded()中间件提取：

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

app.use(
  express.urlencoded({
    extended: true
  })
);

现在，需要在/submit-form 路由上创建一个 POST 端点，任何数据都可以在 Request.body 访问：

app.post('/submit-form', (req, res) => {
  const username = req.body.username;
  //...
  res.end();
});

别忘记提前使用express-validator验证数据。

如何在 Express 中处理表单中的文件上传

以下代码是允许用户上传文件的 HTML 表单示例：

<form method="POST" action="/submit-form" enctype="multipart/form-data">
  <input type="file" name="document" />
  <input type="submit" />
</form>

别忘记在表单添加enctype="multipart/form-data"，否则表单不会被上传。

当用户按下提交按钮时，浏览器会自动向页面同源的/submit-form URL 发出 POST 请求。浏览器发送表单包含的数据，但表单未编码为普通表单 application/x-www-form-urlencoded，而是 multipart/form-data。

在服务器端，处理多部分数据可能很棘手且容易出错，因此我们将使用一个名为 formidable 的库。这里是它的 GitHub 仓库 – 拥有超过 4000 颗星，并且维护良好。

可以通过以下命令安装：

npm install formidable

然后引用到 Node.js 文件：

const express = require('express');
const app = express();
const formidable = require('formidable');

现在，在 /submit-form 路由的 POST 端点中，我们使用 formidable.IncomingForm() 实例化一个新的 Formidable 表单：

app.post('/submit-form', (req, res) => {
  new formidable.IncomingForm();
});

这样做之后，我们需要解析表单。我们可以通过回调来同步执行此操作，这意味着所有文件都已处理。一旦 formidable 完成，文件就可以被访问：

app.post('/submit-form', (req, res) => {
  new formidable.IncomingForm().parse(req, (err, fields, files) => {
    if (err) {
      console.error('Error', err);
      throw err;
    }
    console.log('Fields', fields);
    console.log('Files', files);
    for (const file of Object.entries(files)) {
      console.log(file);
    }
  });
});

或者可以使用事件而不是回调。例如，当每个文件被解析时，或其他事件（例如文件处理完成、接收非文件字段或发生错误）时，都会收到通知：

app.post('/submit-form', (req, res) => {
  new formidable.IncomingForm()
    .parse(req)
    .on('field', (name, field) => {
      console.log('Field', name, field);
    })
    .on('file', (name, file) => {
      console.log('Uploaded file', name, file);
    })
    .on('aborted', () => {
      console.error('Request aborted by the user');
    })
    .on('error', (err) => {
      console.error('Error', err);
      throw err;
    })
    .on('end', () => {
      res.end();
    });
});

无论选择哪种方式，你都将获得一个或多个 Formidable.File 对象，这些对象为你提供有关已上传文件的信息。这些是可以调用的一些方法：

• file.size, 以字节为单位的文件大小
• file.path, 文件写入的路径
• file.name, 文件名
• file.type, 文件的 MIME 类型

路径默认为临时文件夹，如果监听 fileBegin 事件可以修改：

app.post('/submit-form', (req, res) => {
  new formidable.IncomingForm()
    .parse(req)
    .on('fileBegin', (name, file) => {
      file.path = __dirname + '/uploads/' + file.name;
    })
    .on('file', (name, file) => {
      console.log('Uploaded file', name, file);
    });
  //...
});

感谢阅读！

这就是手册的全部内容。别忘了，如果需要的话，你可以下载该手册的 PDF 或者 ePub 版本。

这篇教程中提到的各种技术，我不会详细介绍如何使用它们。但是我会留下链接，你可以了解更多信息，

你可以在我为教程制作的仓库中找到所有代码。

教程的目的是为你提供有关如何设置和连接前端 client 和后端 API 的实用指南。
在开始之前，请确保你的电脑正在运行 Node.js。

创建主项目目录

在你的终端中，导航到你要保存项目的目录。现在为你的项目创建一个新目录，并导航到其中：

mkdir my_awesome_project
cd my_awesome_project

创建一个 React App

这个过程真的很简单。

我将使用 Facebook 的 create-react-app 来……你猜对了，轻松创建一个名为 client 的 react 应用：

npx create-react-app client
cd client
npm start

让我们看看我做了什么：

• 使用 npm 的 npx 来创建 react 应用并将其命名为 client。
• cd（change directory 更改目录）进入 client 目录。
• 启动应用程序。

在浏览器中，导航到 http://localhost:3000/。

如果一切正常，你将看到 react 欢迎页面。恭喜你！这意味着你现在已经在本地计算机上运行了一个基本的 react 应用程序。容易吧？

要停止运行你的 react 应用，只需在终端中按 Ctrl + c。

创建一个 Express App

好的，这将与前面的示例一样简单。不要忘记导航到你的项目顶部文件夹。

我将使用 Express 应用生成器快速创建应用程序框架，并将其命名为 api：

npx express-generator api
cd api
npm install
npm start

让我们看看我做了什么：

• 使用 npm 的 npx 来全局安装 express-generator。
• 使用 express-generator 创建一个 Express 应用并将其命名为 api。
• cd 进入 API 目录。
• 安装所有依赖项。
• 启动应用程序。

在浏览器中，导航到 http://localhost:3000/。

如果一切正常，你将看到 Express 欢迎页面。恭喜你！ 这意味着你现在已经在本地计算机上运行了基本的 Express 应用程序。容易吧？

要停止运行你的 react 应用，只需在终端中按 Ctrl + c。

在 Express API 中配置新 route

我们开始吧。打开你喜欢的代码编辑器（我正在使用 VS Code），导航到你的项目文件夹。

如果你将 react app 命名为 client，将 express app 命名为 api，则会找到两个主文件夹：client 和 api。

1、在 API 目录中，转到 bin/www，然后将第 15 行的端口号从 3000 更改为 9000。稍后我们将同时运行两个应用程序，因此这样做可以避免出现问题。结果应该是这样的：

2、在 api/routes 上，创建一个 testAPI.js 文件，粘贴以下代码：

var express = require(“express”);
var router = express.Router();

router.get(“/”, function(req, res, next) {
    res.send(“API is working properly”);
});

module.exports = router;

3、在 api/app.js 文件中，在第 24 行插入新的 route：

app.use("/testAPI", testAPIRouter);

4、你正在“告诉” express 使用该 rout。但是，你仍然要求它。让我们在第 9 行进行操作：

var testAPIRouter = require("./routes/testAPI");

唯一的变化是在第 9 行和第 25 行。它应该是这样的：

5、恭喜你！你已经创建了一个新的 route。

如果你启动 API 应用程序（在终端中，导航到 API 目录并运行 “npm start”），然后在浏览器中访问 http://localhost:9000/testAPI，你将看到以下消息：API is working properly（API 正常运行中）。

将 React Client 连接到 Express API

• 在你的代码编辑器上，找到 client 目录，打开位于 my_awesome_project/client/app.js 中的 app.js 文件。
• 在这里，我将使用 Fetch API 从 API 检索数据。只需在 Class 声明之后和 render 方法之前粘贴以下代码：

constructor(props) {
    super(props);
    this.state = { apiResponse: "" };
}

callAPI() {
    fetch("http://localhost:9000/testAPI")
        .then(res => res.text())
        .then(res => this.setState({ apiResponse: res }));
}

componentWillMount() {
    this.callAPI();
}

• 在 render 方法内部，你将找到一个 <; p> 标记。让我们对其进行更改，以使其渲染 apiResponse：

<p className="App-intro">;{this.state.apiResponse}</p>

最后，这个文件应该是这样的：

我知道内容有点多！你可以复制粘贴代码，但是你必须了解自己在做什么。让我们看看我在这里做了什么：

• 在第 6 至 9 行中，我们插入了一个构造函数，用于初始化默认状态。
• 在第 11 至 16 行，我们插入了方法 callAPI()，该方法将从 API 中获取数据并将响应存储在 this.state.apiResponse 上。
• 在第 18 至 20 行，我们插入了一个 react 生命周期方法 componentDidMount()，该方法将在组件安装后执行 callAPI() 方法。
• 最后，在第 29 行，我使用<; p>标记在 client 页面上显示了一个段落，其中包含我们从 API 中检索到的文本。

什么？CORS？

我们快完成了！ 但是，如果我们同时启动应用程序（client 和 API），并导航至http：// localhost：3000 /，页面仍然不会显示预期结果。如果你打开 chrome 开发工具，就会找到原因。在控制台中，你将看到此错误：

Failed to load http://localhost:9000/testAPI: No ‘Access-Control-Allow-Origin’ header is present on the requested resource. Origin ‘http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request’s mode to ‘no-cors’ to fetch the resource with CORS disabled.

这很容易解决。我们只需将 CORS 添加到我们的 API 中，即可允许跨域请求。你可以在此处查看有关 CORS 的更多信息。

• 在你的终端中，导航到 API 目录，并安装 CORS 软件包：

npm install --save cors

• 在你的代码编辑器中，访问 API 目录，打开 my_awesome_project/api/app.js 文件。
• 在第 6 行，require CORS：

var cors = require("cors");

• 在第 8 行，“告诉” express 使用 CORS：

app.use(cors());

现在，API app.js 文件应该是这样：

很棒，我们完成了！

现在，使用 npm start 命令在两个不同的终端中启动你的应用程序（client 和 API）。

如果你在浏览器中导航到 http://localhost:3000/，则应该看到类似的内容：

当然，这个项目没有实现很多，但它是全栈应用的开始。你可以在这个仓库中找到我为教程创建的所有代码。

接下来，我将研究一些补充教程，例如如何将其连接到 MongoDB 数据库，甚至如何在 Docker 容器中运行它们。

正如我的一个好朋友说的：

Be Strong and Code On!!!

每天都要变得更好哦;)

原文：How to create a React frontend and a Node/Express backend and connect them，作者：João Henrique