在前端开发中，我们经常需要使用 API 或者编写 API。但是，编写 API 需要遵循很多的规范，如参数个数、参数类型、API 返回值等等。如何保障 API 符合规范呢？今天我们来介绍一种 NPM 包，即 Spectral，用于规范 API。
什么是 Spectral？
Spectral 是 OpenAPI 指南中所确定的语义验证器。它使用 Json Schema 范式，并提供基于规范的验证程序。随着 OpenAPI 的日益流行，Spectral 可以验证 OpenAPI 和其他 API 规范，并确保规范执行顺利。此外， Spectral 是社区 OpenAPI 规范中追求一致性和可靠性的一部分。
安装和使用
- 安装 Spectral
npm i spectral
- 规则文件
Spectral 使用规则文件来指定测试以及规则。我们根据个人需求编写规则文件。比如我们要测试一个 API，要求这个 API 返回的是一个对象，其中必须包含 name 和 age 两个字段。
我们可以创建一个名为 myRuleset.yaml 的文件，并编写以下内容。
-- -------------------- ---- -------
------
--------
------------ ------ --- -------- --- - ------ --- ----- ------
------ --------------
-----
------ ----
--------- ------
--------- ----
-------- ---- -- ------
---------
------ --------------
-----
------ ---
--------- ------上述内容是一组基本规则，以 name 和 age 字段为例。每个规则有一个独特的名称，并且包含描述和回调函数。给定是 JavaScript 表达式，控制要关注什么。在这个例子中，$response.body 是给定的表达式，这意味着规则会依次检查 API 响应的 body 部分。
然后，我们将规则文件的位置传递给 Spectral。
-- -------------------- ---- -------
----- -- - --------------
----- ---- - ----------------
----- - -------- - - -------------------------------
----- -------- - --- -----------
----- --------- - ------------------------------------ -------------------
------------------------------------------
----- ------- - ----- --------------
----- -
----- -----
---- ---
--
---
---------------------通过 fs 和 path 模块读取规则文件，并将文件的内容传递给 Spectral 实例的 setRuleset 方法。最后使用 run 方法传入 API 的响应，就可以得到 API 是否符合规范。
常用规则
Spectral 支持开箱即用的规则，同时支持自定义规则。这里我们介绍几个常用的规则。
OpenAPI 规则
- oas2-schema: 使用 JSON Schema 为谁创建 OpenAPI 规范，以确保它们格式正确
- operation-tags: 每个捆绑到操作数组的操作必须有一个
tags字段。该字段必须是一个非空字符串数组，其中包含有关操作的标记。 - operation-operationId-unique: 必须为每个操作分配唯一的
operationId。
Node.js 规则
- no-eval-in-markdown: markdown 中不能使用
eval - no-new-date-without-argument: 不应该使用无参数调用
Date，它将创建一个日期对象，其时间戳与安装 Node.js 的时间戳相同。 - no-return-await: 不应该在必须使用
await的地方返回一个无需await的值，可以直接返回一个 promise。
总结
Spectral 通过 Json Schema 范式和规则文件，为我们的开发和 API 编写提供了强力的支持。在使用时，我们可以根据业务需求编写对应的规则，并对 API 返回进行统一的格式要求。同样，也可以使用 Spectral 开箱即用的规则，方便快捷。
希望本文能够给你带来帮助，谢谢！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6006709c8ccae46eb111efc5