Inso CLI 如何用 lint spec 命令检查 API 规范并指定 Spectral 规则集

Inso CLI 如何用 lint spec 命令检查 API 规范并指定 Spectral 规则集【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomniaInsomnia 仓库中的 Inso CLI命令名inso定义见 packages/insomnia-inso/src/cli.ts提供了inso lint spec子命令用于对 OpenAPI 规范文件做 Spectral 规则检查并在发现 error 级别问题时以非零退出码结束方便接入 CI。本文说明如何用该命令检查一份 API 规范、通过三种方式指定 Spectral 规则集以及如何根据输出和退出码判断检查结果。运行 inso 命令命令名是insopackages/insomnia-inso/package.json 中通过bin: { inso: bin/inso }声明。在本仓库源码内开发时packages/insomnia-inso/README.md 给出的用法是先执行npm run inso-start然后用仓库内的入口脚本$PWD/packages/insomnia-inso/bin/inso lint spec如果 inso 已安装为独立命令则直接使用inso lint spec。下文命令以inso简写仓库内执行时替换为$PWD/packages/insomnia-inso/bin/inso即可。lint spec 找到待检查规范的三种方式lint spec的签名是inso lint spec [identifier]描述为 “Lint an API Specification, identifier can be an API Spec id or a file path”。identifier 可以是文件路径也可以是 Insomnia 数据库中的 API Spec id三种入口在 packages/insomnia-inso/src/cli.test.ts 中都有真实用例# 方式 1identifier 直接是规范文件路径 inso lint spec packages/insomnia-inso/src/commands/fixtures/openapi-spec.yaml # 方式 2-w 指定规范文件所在目录identifier 写文件名 inso lint spec -w packages/insomnia-inso/src/commands/fixtures/with-ruleset path-plugin.yaml # 方式 3-w 指向 Insomnia 数据目录.insomnia 目录、*.db.json 或 export.yaml # identifier 写 API Spec id规范内容从数据库中取出 inso lint spec -w packages/insomnia-inso/src/db/fixtures/nedb spc_46c5a4-w, --workingDir dir的全局说明是 “set working directory/file: .insomnia folder, *.db.json, export.yaml”。不传-w时 inso 会警告 “No working directory provided, using local app data directory.” 并回退到本地 Insomnia 应用数据目录identifier 在数据库中找不到对应规范时会报错 “Specification content not found using API spec id”。方式 1 下 identifier 还会被解析为相对workingDir的绝对路径因此相对路径的解析基准是-w的值而不是当前 shell 目录。指定 Spectral 规则集的三种途径规则集的选择逻辑在 packages/insomnia-inso/src/commands/lint-specification.ts优先级从高到低-r, --ruleset path显式指定帮助文本为 “path to a Spectral ruleset file, overrides default OAS ruleset and any ruleset in the API Spec folder”。路径相对workingDir解析例如inso lint spec openapi-spec.yaml -r ./spectral/custom-ruleset.yaml规范文件同目录下的.spectral*文件自动发现当 identifier 是文件路径且未传-r时inso 会在规范文件所在目录中查找以.spectral开头的文件名getRuleSetFileFromFolderByFilename找到则加载并输出Loading ruleset from ...trace 级别。仓库中现成的例子是 packages/insomnia-inso/src/commands/fixtures/with-ruleset/.spectral.yml内容只有两行extends: - spectral:oas把它放在 path-plugin.yaml 旁边执行inso lint spec -w packages/insomnia-inso/src/commands/fixtures/with-ruleset path-plugin.yaml即可生效。内置 OAS 规则集兜底以上都没有时默认使用 Spectral 的oas规则集并在日志中输出Using ruleset: oas。注意自动发现只作用于“identifier 是文件路径”这一种入口从数据库按 id 取规范时不会扫描目录中的.spectral*文件此时只能靠-r指定自定义规则集。规则集文件的格式约束自定义规则集会被 packages/insomnia/src/main/bundle-spectral-ruleset.ts 和 packages/insomnia/src/common/spectral-ruleset-validator.ts 处理与校验写文件前先对照这些硬约束文件必须是 YAML/JSON 对象顶层不能是数组或标量且至少声明rules或extends之一。顶层只允许rules和extends两个键出现其他顶层键会报Ruleset contains unsupported top-level keys. Only rules and extends are allowed.。extends的每个条目必须是普通字符串不支持元组格式如[path, severity]内置标识符只允许spectral:oas、spectral:asyncapi、spectral:arazzo三个。extends引用本地文件时只允许.yaml/.yml扩展名路径必须保持在规则集自身所在目录内禁止../穿越嵌套深度上限 5 层且不允许出现循环引用。extends引用远程 URL 时必须为 https、目标主机不得是私有/环回地址含 DNS 解析结果检查、拒绝重定向、超时 10 秒。rules中每条规则可以是布尔值、严重级字符串或含given/then的对象then.function只允许 Spectral 内置函数alphabetical、casing、defined、enumeration、falsy、length、pattern、schema、truthy、typedEnum、undefined、unreferencedReusableObject、or、xor不支持自定义functions键。then.field必须是普通属性名不能包含.、[、]或__proto__等保留词documentationUrl必须是 https 链接。以上任一校验失败时lintSpecification会打印 fatal 错误并直接返回无效结果进程以退出码 1 结束不会继续执行 lint。执行检查并判断结果对合法规范例如仓库中的 openapi-spec.yaml执行后无问题时的输出为No linting errors or warnings.进程以退出码 0 结束。存在结果时会先打印汇总行再逐条输出N lint errors found. N lint warnings found. 行:列 - Error|Warning - 规则码 - 消息 - 规则匹配的路径用 . 连接的 JSON path Errors found, failing lint.判定规则很明确只要存在DiagnosticSeverity.Error级别的结果就会打印Errors found, failing lint.并以退出码 1 结束process.exit(isValid ? 0 : 1)只有 warning 时不算失败退出码仍为 0。cli.test.ts中的shouldReturnErrorCode列表把两条命令作为失败用例# 规范内容本身有问题含重复键的 YAMLlint 失败 inso lint spec packages/insomnia-inso/src/db/fixtures/insomnia-v4/malformed.yaml inso lint spec -w packages/insomnia-inso/src/db/fixtures/git-repo-malformed-spec spc_46c5a4在 CI 中可以用退出码直接判断0 表示通过1 表示存在 error 级问题。其他全局选项对排查有帮助--ci禁用所有交互提示--verbose输出额外日志命令异常退出时 inso 会提示 “To view tracing information, re-runinsowith--verbose”。边界与已知限制规则集校验发生在 lint 之前校验失败与“规范有 error”表现不同前者是规则集加载阶段的 fatal 信息后者会先列出具体错误条目。远程extends与规范中$ref的远程解析使用同一套安全策略只允许 https 公共主机、拒绝重定向、超时 10 秒见 lint-specification.ts 中safeRefResolver的注释内网主机引用会直接抛错。.spectral*自动发现只匹配规范文件所在目录不会向上级目录查找需要覆盖默认 OAS 规则集的其他场景请显式使用-r。规则集不支持自定义 JS 函数functions键会被拒绝只能使用上述内置函数列表这与 Spectral 原生 CLI 的能力不同。参考文件命令定义packages/insomnia-inso/src/cli.tslint 实现与$ref安全解析packages/insomnia-inso/src/commands/lint-specification.ts规则集打包与校验packages/insomnia/src/main/bundle-spectral-ruleset.ts、packages/insomnia/src/common/spectral-ruleset-validator.ts规则集示例packages/insomnia-inso/src/commands/fixtures/with-ruleset/.spectral.yml命令真实用例与退出码约定packages/insomnia-inso/src/cli.test.ts【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomnia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考