使用vacuum进行Golang OpenAPI规范检查与质量检测

vacuum是一个超快速、轻量级的OpenAPI/Swagger规范检查工具，专为高性能验证和linting设计。下面我将详细介绍如何在Golang项目中使用vacuum。

vacuum简介

vacuum的主要特点：

• 极快的验证速度（比传统工具快10-100倍）
• 支持OpenAPI 2.0/3.0/3.1规范
• 内置丰富的linting规则
• 可自定义规则集
• 支持多种输出格式（JSON、YAML、HTML等）

安装vacuum

1. 直接安装

go install github.com/daveshanley/vacuum@latest

2. 作为库引入

go get github.com/daveshanley/vacuum

基本使用示例

1. 命令行使用

package main

import (
	"fmt"
	"os"
	"os/exec"
)

func main() {
	// 验证OpenAPI文档
	cmd := exec.Command("vacuum", "lint", "openapi.yaml")
	output, err := cmd.CombinedOutput()
	if err != nil {
		fmt.Printf("验证失败: %v\n", err)
		os.Exit(1)
	}
	fmt.Println(string(output))
}

2. 编程方式使用

package main

import (
	"fmt"
	"github.com/daveshanley/vacuum/model"
	"github.com/daveshanley/vacuum/motor"
	"github.com/daveshanley/vacuum/rulesets"
)

func main() {
	// 1. 加载OpenAPI规范文件
	specBytes, err := os.ReadFile("openapi.yaml")
	if err != nil {
		fmt.Printf("无法读取文件: %v\n", err)
		return
	}

	// 2. 创建规则集（使用内置推荐规则）
	defaultRuleset := rulesets.BuildDefaultRuleSets()

	// 3. 执行验证
	resultSet := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
		RuleSet: defaultRuleset,
		Spec:    specBytes,
	})

	// 4. 处理结果
	if resultSet.Errors != nil {
		fmt.Println("发现验证错误:")
		for _, err := range resultSet.Errors {
			fmt.Printf("- %s (位置: %d:%d)\n", err.Message, err.Range.Start.Line, err.Range.Start.Column)
		}
	} else {
		fmt.Println("OpenAPI规范验证通过!")
	}
}

高级功能

1. 自定义规则

func customRulesExample() {
	// 创建自定义规则集
	customRuleset := rulesets.CreateRuleSet(
		"我的自定义规则集",
		"自定义OpenAPI验证规则",
		rulesets.RuleSetDefinition{
			"operation-tags": &rulesets.Rule{
				Description: "每个操作必须有至少一个标签",
				Severity:    rulesets.Error,
				Recommended: true,
				RuleCategory: rulesets.RuleCategories{
					rulesets.OperationsCategory,
				},
				Given: "$.paths[*][*]",
				Then: &rulesets.RuleAction{
					Field: "tags",
					Function: "truthy",
				},
			},
		},
	)

	// 使用自定义规则集验证
	resultSet := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
		RuleSet: customRuleset,
		Spec:    specBytes,
	})
}

2. 生成HTML报告

func generateHTMLReport() {
	resultSet := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
		RuleSet: rulesets.BuildDefaultRuleSets(),
		Spec:    specBytes,
	})

	// 生成HTML报告
	htmlReport := model.GenerateHTMLReport(resultSet)
	err := os.WriteFile("report.html", []byte(htmlReport), 0644)
	if err != nil {
		fmt.Printf("无法生成报告: %v\n", err)
		return
	}
	fmt.Println("HTML报告已生成: report.html")
}

集成到CI/CD流程

package main

import (
	"fmt"
	"os"
	"github.com/daveshanley/vacuum/motor"
	"github.com/daveshanley/vacuum/rulesets"
)

func main() {
	// 在CI中严格验证
	specBytes, _ := os.ReadFile("openapi.yaml")
	
	strictRules := rulesets.BuildDefaultRuleSets()
	strictRules.Rules["operation-operationId"] = &rulesets.Rule{
		Description: "强制每个操作必须有operationId",
		Severity:    rulesets.Error,
		Recommended: true,
		RuleCategory: rulesets.RuleCategories{
			rulesets.OperationsCategory,
		},
		Given: "$.paths[*][*]",
		Then: &rulesets.RuleAction{
			Field: "operationId",
			Function: "truthy",
		},
	}

	result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
		RuleSet: strictRules,
		Spec:    specBytes,
	})

	if len(result.Errors) > 0 {
		fmt.Println("CI验证失败:")
		for _, err := range result.Errors {
			fmt.Printf("- %s\n", err.Message)
		}
		os.Exit(1)
	}
	fmt.Println("OpenAPI规范验证通过，CI继续执行")
}

性能优化技巧

1. 并行验证：vacuum内置并行处理，对于大型文档特别有效
2. 缓存规则集：重复验证时复用规则集对象
3. 选择性验证：只加载需要的规则

vacuum是Golang生态中验证OpenAPI规范的优秀工具，其出色的性能和灵活性使其成为API开发流程中的理想选择。