使用vacuum进行API代码规范检查 - Bump.sh

无论是刚开始构建 API 并寻求反馈，还是改进对旧 API 的审计以确保其安全性、一致性和符合标准，API linting 都是一种有效的解决方案。通过 API linting，可以快速检测 JSON 或 YAML 文件是否符合预设规则，从而确保 API 的质量和规范性。

什么是 API linting？

API linting 的概念类似于代码 linting 或文档拼写/语法检查。它通过设定规则来验证 API 是否符合以下要求：

YAML/JSON 文件是否有效。
OpenAPI 或 AsyncAPI 是否符合各自的规范。
API 是否遵循行业标准和最佳实践。
API 是否符合相关的安全规范。
是否遵循组织内部的 API 样式指南。

手动检查这些内容非常耗时，尤其是在团队规模较大、开发人员众多的情况下。通过自动化的 linting 工具，可以显著提高效率，确保 API 在编码前就达到标准，从而节省时间和成本。

API linting 的发展背景

多年来，API 质量控制的主要方式是编写“API 样式指南”，通常以 Wiki、PDF 或 Word 文档的形式存在。这些文档详细列出了 API 的命名约定、身份验证方法、数据结构等内容。然而，这种方式存在以下问题：

内容庞大且难以记忆。
开发人员可能不会阅读或遵守指南。
指南内容可能过时，导致开发人员基于错误信息进行操作。

为了解决这些问题，自动化的 linting 工具应运而生。

什么是 Vacuum？

Vacuum 是一个用于 API linting 的命令行工具，它可以帮助开发者自动检查 API 的规范性和一致性。通过 Vacuum，可以在拉取请求中快速获得 API 的反馈，确保所有更改都是有效且符合标准的。

使用 Vacuum 改进 Bump.sh API 文档

以下是使用 Vacuum 进行 API linting 的具体步骤：

步骤 1：安装 Vacuum CLI

Vacuum 支持多种安装方式，包括 Brew、NPM、Curl 和 Docker。本指南以 NPM 为例，展示如何安装 Vacuum 并将其应用于火车旅行 API：

cd ~/src/train-travel-api
npm install @quobix/vacuum --include=dev

安装完成后，可以通过以下命令验证安装是否成功：

npx vacuum --help

步骤 2：在本地运行 Vacuum

在进一步集成之前，可以先在本地运行 Vacuum，检查 API 的工作情况。例如，可以在 OpenAPI 文件上运行以下命令：

npx vacuum lint -d openapi.yaml

运行后，Vacuum 会根据内置规则生成详细的输出报告，帮助开发者快速定位问题。

步骤 3：配置规则和规则集

如果某些规则不适用于当前项目，可以通过配置文件进行调整。在工作目录中创建 .vacuum.conf.yaml 文件，并定义规则集。例如：

ruleset: ./.vacuum/ruleset.yaml

然后，在 .vacuum/ruleset.yaml 文件中关闭不需要的规则：

extends:
  - spectral:oas
rules:
  oas3-missing-example: off

再次运行 lint 命令后，输出结果会更加简洁。

如果发现错误，可以根据输出中的 Location 信息快速定位问题。例如，openapi.yaml:1049:5 表示问题位于 openapi.yaml 文件的第 1049 行。

步骤 4：保持满分状态

为了确保 API 的持续规范性，可以将 Vacuum 集成到 GitHub Actions 中。以下是一个示例工作流配置文件：

# .github/workflows/lint.yml
name: Lint
on:
  pull_request:
  push:
    branches:
      - main
    paths-ignore:
      - 'README.md'
      - 'src/**'
jobs:
  build:
    name: API Linting
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Lint API
        run: npm exec vacuum report --junit openapi.yaml lint-results
      - name: Publish Lint Results

        if: success() || failure()        uses: mikepenz/action-junit-report@v5
        with:
          check_name: API Lint Results
          report_paths: lint-results-*.xml

此工作流会在拉取请求时自动运行 Vacuum，并生成 JUnit 格式的报告。开发者可以根据报告中的警告和错误修复问题，从而避免不规范的更改被合并。

总结

通过 Vacuum，可以显著提升 API 的质量和一致性。它不仅能够帮助开发者快速发现问题，还能通过与 CI/CD 工具的集成，确保 API 的持续规范性。无论是初学者还是经验丰富的开发者，都可以通过 Vacuum 高效地管理 API 文档和代码规范。

原文链接: https://bump.sh/blog/api-linting-with-vacuum