Golang检测Go项目向后兼容性变化插件库apicompat的使用

介绍

apicompat是一个用于检测向后不兼容变更的工具。

apicompat的特点：

• 保证库的所有使用者仍然能够无错误地构建
• 仅检查导出的声明
• 没有误报（如果有，就是bug）
• 并非所有向后不兼容的变更都能被检测到，交换参数等变更仍需由库作者考虑
• 可以作为库简单使用
• 目前处于早期开发阶段，欢迎反馈和审查
• 早期开发时曾命名为abicheck

次要功能可能包括：

• 检测当前的语义版本并建议适当的增加
• 列出所有变更以帮助编写发布说明/提交消息

安装与使用

通过命令行安装和使用：

go get -u github.com/bradleyfalzon/apicompat/cmd/apicompat
cd /your/project/dir/with/committed/changes
apicompat

命令行参数

apicompat提供了命令行工具，支持以下参数：

-vcs    (auto|git|svn|etc) - 使用的版本控制系统 (默认: auto)
-before revision           - 作为"之前"版本的修订 (默认: 如果有未暂存的变更则检查这些变更，否则检查最后两次提交)
-after  revision           - 作为"之后"版本的修订 (默认: 如果有未暂存的变更则检查这些变更，否则检查最后两次提交)
-vcsDir path               - VCS根目录路径 (默认: 让VCS工具搜索)
-all                       - 显示非破坏性变更以及破坏性变更 (默认: false)

apicompat        # 仅检查当前包
apicompat ./...  # 检查子目录包

示例代码

下面是一个完整的示例，展示如何使用apicompat库进行API兼容性检查：

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/bradleyfalzon/apicompat"
)

func main() {
	// 初始化配置
	config := apicompat.NewConfig()
	
	// 设置要比较的版本
	config.Before = "HEAD~1"  // 前一个提交
	config.After = "HEAD"     // 当前提交
	
	// 设置VCS类型为git
	config.VCS = "git"
	
	// 运行兼容性检查
	changes, err := apicompat.Check(config, ".")
	if err != nil {
		log.Fatal(err)
	}
	
	// 输出发现的破坏性变更
	for _, change := range changes {
		if change.Breaks {
			fmt.Printf("破坏性变更: %s\n", change)
		}
	}
	
	if len(changes) == 0 {
		fmt.Println("没有检测到破坏性变更")
		os.Exit(0)
	} else {
		fmt.Printf("检测到%d个破坏性变更\n", len(changes))
		os.Exit(1)
	}
}

测试

测试使用golden master方法：

• 测试数据位于testdata/目录，包含before.go和after.go
• 每次运行go test时，输出会与testdata/exp.txt进行比较
• 运行测试：go test
• 更新golden master：go test -args update

开发状态

apicompat目前处于重开发和重构阶段，主要任务包括：

• 添加Mercurial、SVN等VCS系统支持
• 改进VCS选项
• 添加文档和流程图
• 改进输出格式
• 性能优化

注意：此工具仍在开发中，可能会有较大变化。