使用Go与CircleCI API交互的circleci客户端库

CircleCI是一个流行的持续集成和持续交付(CI/CD)平台，它提供了REST API让开发者可以编程方式与其交互。在Go生态中，circleci是一个常用的客户端库，用于简化与CircleCI API的交互。

安装circleci库

首先，你需要安装circleci库：

go get github.com/grezar/go-circleci

基本使用示例

1. 初始化客户端

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/grezar/go-circleci"
)

func main() {
	// 使用你的CircleCI API token初始化客户端
	// 可以在CircleCI网站的用户设置中获取API token
	token := "your-circleci-api-token"
	client := circleci.NewClient(token, nil)
	
	// 测试连接
	ctx := context.Background()
	user, err := client.Me.Get(ctx)
	if err != nil {
		log.Fatalf("Failed to get user info: %v", err)
	}
	
	fmt.Printf("Logged in as: %s (ID: %s)\n", user.Name, user.ID)
}

2. 获取项目列表

func listProjects(client *circleci.Client) {
	ctx := context.Background()
	projects, err := client.Projects.List(ctx)
	if err != nil {
		log.Fatalf("Failed to list projects: %v", err)
	}

	fmt.Println("Your projects:")
	for _, project := range projects {
		fmt.Printf("- %s (vcs: %s/%s)\n", 
			project.Name, 
			project.VcsType, 
			project.Username)
	}
}

3. 触发新的构建

func triggerBuild(client *circleci.Client, projectSlug string, branch string) {
	ctx := context.Background()
	
	// 项目slug格式为: vcs-type/org-name/repo-name
	// 例如: github/grezar/go-circleci
	
	build, err := client.Builds.TriggerPipeline(ctx, projectSlug, branch, nil)
	if err != nil {
		log.Fatalf("Failed to trigger build: %v", err)
	}
	
	fmt.Printf("Build triggered! ID: %s, Number: %d\n", 
		build.ID, 
		build.Number)
}

4. 获取构建状态

func getBuildStatus(client *circleci.Client, projectSlug string, buildNumber int) {
	ctx := context.Background()
	
	build, err := client.Builds.Get(ctx, projectSlug, buildNumber)
	if err != nil {
		log.Fatalf("Failed to get build info: %v", err)
	}
	
	fmt.Printf("Build #%d status: %s\n", build.Number, build.Status)
	fmt.Printf("Started at: %s, Duration: %d seconds\n", 
		build.StartTime, 
		build.BuildTimeMillis/1000)
}

高级功能

1. 使用环境变量

func manageEnvVars(client *circleci.Client, projectSlug string) {
	ctx := context.Background()
	
	// 列出环境变量
	envVars, err := client.Project.ListEnvVars(ctx, projectSlug)
	if err != nil {
		log.Fatalf("Failed to list env vars: %v", err)
	}
	
	fmt.Println("Environment variables:")
	for _, envVar := range envVars {
		fmt.Printf("- %s\n", envVar.Name)
	}
	
	// 添加新的环境变量
	newVar := &circleci.ProjectEnvVar{
		Name:  "SECRET_KEY",
		Value: "my-secret-value",
	}
	
	_, err = client.Project.AddEnvVar(ctx, projectSlug, newVar)
	if err != nil {
		log.Fatalf("Failed to add env var: %v", err)
	}
	fmt.Println("Added new environment variable")
}

2. 处理工作流

func getWorkflowInfo(client *circleci.Client, projectSlug string, workflowID string) {
	ctx := context.Background()
	
	workflow, err := client.Workflows.Get(ctx, workflowID)
	if err != nil {
		log.Fatalf("Failed to get workflow: %v", err)
	}
	
	fmt.Printf("Workflow %s status: %s\n", workflow.ID, workflow.Status)
	
	// 获取工作流中的任务
	jobs, err := client.Workflows.ListJobs(ctx, workflowID)
	if err != nil {
		log.Fatalf("Failed to list jobs: %v", err)
	}
	
	for _, job := range jobs {
		fmt.Printf("- Job %s: %s\n", job.Name, job.Status)
	}
}

错误处理

CircleCI API可能会返回各种错误，良好的错误处理很重要：

func handleErrors(client *circleci.Client, projectSlug string) {
	ctx := context.Background()
	
	_, err := client.Projects.Get(ctx, "nonexistent/project")
	if err != nil {
		if circleci.IsNotFound(err) {
			fmt.Println("Project not found")
		} else if circleci.IsUnauthorized(err) {
			fmt.Println("Unauthorized - check your API token")
		} else {
			fmt.Printf("Unexpected error: %v\n", err)
		}
		return
	}
}

总结

circleci Go客户端库提供了对CircleCI API的全面访问，使得从Go程序管理CI/CD流程变得简单。通过这个库，你可以：

1. 获取用户和项目信息
2. 触发和管理构建
3. 处理工作流和任务
4. 管理环境变量
5. 监控构建状态

记住始终妥善保管你的CircleCI API token，不要在代码中硬编码敏感信息，考虑使用环境变量或秘密管理工具来存储它们。

完整的API文档可以参考官方CircleCI API文档和go-circleci库文档。