前言
对于前端开发人员而言，了解如何使用 npm 包对于开发过程中大有裨益。在本篇文章中，我们将会介绍一个非常实用的 npm 包：swagger-express-validator-formats，以及它如何帮助我们更方便地进行 API 数据格式校验。
什么是 swagger-express-validator-formats？
swagger-express-validator-formats 是一个基于 Swagger 规范的数据格式校验 npm 包。它可以与 express 应用程序一起使用，方便我们对来自于 API 的数据进行校验，以确保数据格式的正确性。
安装
在使用 swagger-express-validator-formats 之前，需要先安装该 npm 包。可以通过以下命令进行安装：
npm install swagger-express-validator-formats --save-dev
该命令会在项目的 package.json 文件中添加一个依赖，并将该 npm 包下载到本地。
基本用法
1. 定义 Swagger 规范
在使用 swagger-express-validator-formats 进行数据格式校验之前，需要使用 swagger 编写 API 规范。我们可以将 swagger 规范写在一个 .yaml 或 .json 文件中，并使用 swagger-editor 进行编辑。
下面是一个 swagger 规范的示例：
-- -------------------- ---- -------
-------- -----
-----
-------- -------
------ -----
------
----------
-----
-----------
- ----- ----
--- ----
--------- ----
-------
----- ------
-----------
-----
----- ------
-------- ----
----
----- -------
-------- --
----------
----
------------ --2. 使用 swagger-express-validator-formats 进行数据格式校验
接下来，我们需要在 express 应用程序中引入 swagger-express-validator-formats，并将 swagger 规范传入其中，以验证请求的数据格式。
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ---------------- - --------------------------------------------- ----- ----------- - -------------------------- ----- --- - ---------- ------------------------ --------------------------------------- --------------------- ----- ---- -- - ----- - ----- --- - - --------- ---------------- -------- ---- --- -- ---------- --- ---------------- -- -- - ------------------- -- ------- -- ---- -------- ---
在上述示例中，我们使用 express.json() 中间件来解析请求的 JSON 数据。然后，我们使用 swaggerValidator 函数传入 swagger 规范，该函数将返回一个中间件函数，该函数会验证请求的数据格式是否符合规范。最后，我们实现了一个简单的 API 接口，接收来自客户端的请求，并返回一个包含请求中传输数据的回复。
3. 发送请求
完成了 express 应用程序以及数据格式校验的设置后，我们可以使用任何一种 HTTP 客户端工具（如 Postman 或 cURL）来向我们写的 API 发送请求。
下面是一个使用 cURL 发送 POST 请求的示例：
curl --location --request POST 'http://localhost:3000/api/user' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "John",
"age": 25
}'发送该请求后，服务端会将请求中传输的数据返回给客户端，客户端将会收到类似以下内容的响应：
Hello, John! Your age is 25.
深入了解
格式校验
Swagger-express-validator-formats 主要用于格式校验。校验数据格式时，该 npm 包会将请求中传输的数据项与 swagger 规范中定义的 schema 进行对比，以确保传输的数据格式是正确的。
对于数据中的各种格式（如数字、字符串、日期、时间、电话号码等等），Swagger-express-validator-formats 提供了内置格式校验。此外，我们还可以在 swagger 规范中自定义格式校验的正则表达式。例如，我们可以在 swagger 规范中添加以下内容：
-- -------------------- ---- -------
-------- -----
-----
-------- -------
------ -----
-----------
------------
----- -----------
--- --------
--------- ----
----- ------
-------- -------------------在这个示例中，我们自定义了一个格式校验的正则表达式，该表达式验证了数据中是否包含一个合法的电话号码。在数据格式校验时，Swagger-express-validator-formats 将会根据传输的数据以及规范中定义的 phoneNumber 参数来验证数据是否符合要求。
API 接口自动文档
使用 swagger-express-validator-formats 不仅可以帮助我们对 API 数据格式进行校验，同时还可以生成接口自动文档。我们可以在项目中添加 swagger-ui-express 包，从而在浏览器中查看接口文档。
下面是一个基本的实例：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --------- - ------------------------------ ----- ---------------- - --------------------------------------------- ----- ----------- - -------------------------- ----- --- - ---------- ------------------------ ---------------- ---------------- ------------------------------ --------------------------------------- --------------------- ----- ---- -- - ----- - ----- --- - - --------- ---------------- -------- ---- --- -- ---------- --- ---------------- -- -- - ------------------- -- ------- -- ---- -------- ---
在此示例中，我们添加了 swagger-ui-express 包，将接口文档提供给浏览器查看。请注意，我们使用了 serve 和 setup 方法，将 swagger 规范传给 swagger-ui-express 中间件，并将中间件绑定到了 /docs 路径，以便在浏览器中浏览 API 文档。
状态码校验
在 swagger 规范中，我们可以定义每个 API 方法的期望响应。我们可以指定每个响应需要的状态码以及响应内容格式。在进行 API 数据格式校验同时，Swagger-express-validator-formats 也会帮助我们验证 HTTP 响应的状态码是否符合要求，并且，如果响应的状态码不在规范中的期望列表中时，Swagger-express-validator-formats 将会抛出相关的错误信息。
下面是一个状态码校验的示例：
-- -------------------- ---- -------
-------- -----
-----
-------- -------
------ -----
------
----------
-----
-----------
- ----- ----
--- ----
--------- ----
-------
----- ------
-----------
-----
----- ------
-------- ----
----
----- -------
-------- --
----------
----
------------ -------
----
------------ --- -------
----
------------ ------------
----
------------ -------- ------ -----在这个示例中，我们指定了 /api/user 路径下 POST 方法的期望响应状态码，分别为 201、400、401 和 500。这意味着，当客户端使用我们的 API 时，如果 API 响应的状态码不在上述四个状态码中，则会引发 Swagger-express-validator-formats 中间件抛出的错误。
统一 API 返回格式
在许多项目中，我们希望能够给 API 提供一致的、规范的响应格式。Swagger-express-validator-formats 通过简单的配置选项，可以让我们在应用程序中自定义一个中间件函数，用于包装每个 API 的响应，以达到统一 API 返回格式的目的。
下面是一个自定义 API 返回格式的中间件的示例：
-- -------------------- ---- -------
----- ------- - -------------------
----- ---------------- - ---------------------------------------------
----- ----------- - --------------------------
----- --- - ----------
------------------------
------------------------------------- - ---------------- ----
---------------------------------
-- ------ --------
-------- --------------------- ---- ----- -
----- ------------ - ---------
-------- - ---- -- -
----- ------------- - -
-----
------ -----
--
---------------------- ---------------
--
-------
-
-- ----- -------- ----------
-------- ---------------------------- ---- ---- ----- -
----- ------------- - -
----- -----
------ -
-------- ------------
--
--
--------------------- -- -------------------------
-
-- ----
--------------------- ----- ---- -- -
----- - ----- --- - - ---------
---------------- -------- ---- --- -- ----------
---
---------------- -- -- -
------------------- -- ------- -- ---- --------
---在这个示例中，我们使用了 formatResponseFn 函数来包装每个 API 的响应内容。该函数会在 Swagger-express-validator-formats 中间件之后被调用，并对答复内容进行重新格式化，以满足我们的期望格式。在 formatResponseFn 函数中，我们定义了一个函数 originalSend，该函数保留了 res.send 的原始实现，并使用它来向客户端发送格式化数据。
在上述示例中，我们还添加了一个错误处理中间件 errorHandlingMiddleware，该中间件会捕捉到所有对应用程序抛出的错误，并将错误信息以统一格式返回给客户端。这样，我们就可以轻松地为我们的 API 设计一致的错误信息返回格式。
结论
在本文中，我们介绍了 swagger-express-validator-formats 这个非常有用的 npm 包。我们讲述了如何安装、配置和使用这个 npm 包，以及如何深入了解和发挥它的实用功能。通过了解 swagger-express-validator-formats，我们可以在开发 API 时更加高效和准确。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005663b81e8991b448e23ae