githubv4

githubv4 包是用于访问 GitHub GraphQL API v4 (https://docs.github.com/en/graphql) 的客户端库。

如果你正在寻找 GitHub REST API v3 的客户端库，推荐使用 github 包（也称为 go-github）。

重点

友好、简单且功能强大的 API。
正确性、高性能和高效率。
通过从 schema 生成代码来支持 GitHub GraphQL API v4 的所有功能。

安装

go get github.com/shurcooL/githubv4

使用方法

身份验证

GitHub GraphQL API v4 需要身份验证。githubv4 包不直接处理身份验证。相反，在创建新客户端时，你需要传入一个执行身份验证的 http.Client。最简单且推荐的方法是使用 golang.org/x/oauth2 包。你需要从 GitHub 获取一个 OAuth 令牌（例如，个人访问令牌）并具有正确的权限范围。然后：

import "golang.org/x/oauth2"

func main() {
	src := oauth2.StaticTokenSource(
		&oauth2.Token{AccessToken: os.Getenv("GITHUB_TOKEN")},
	)
	httpClient := oauth2.NewClient(context.Background(), src)

	client := githubv4.NewClient(httpClient)
	// 使用 client...
}

如果你使用的是 GitHub Enterprise，请使用 githubv4.NewEnterpriseClient：

client := githubv4.NewEnterpriseClient(os.Getenv("GITHUB_ENDPOINT"), httpClient)
// 使用 client...

简单查询

要进行查询，你需要定义一个与 GitHub GraphQL schema 相对应的 Go 类型，并包含你想要查询的字段。你可以在 https://docs.github.com/en/graphql/reference/queries 查看 GitHub GraphQL schema。

例如，要进行以下 GraphQL 查询：

query {
	viewer {
		login
		createdAt
	}
}

你可以定义这个变量：

var query struct {
	Viewer struct {
		Login     githubv4.String
		CreatedAt githubv4.DateTime
	}
}

然后调用 client.Query，传入一个指向它的指针：

err := client.Query(context.Background(), &query, nil)
if err != nil {
	// 处理错误
}
fmt.Println("    Login:", query.Viewer.Login)
fmt.Println("CreatedAt:", query.Viewer.CreatedAt)

// 输出：
//     Login: gopher
// CreatedAt: 2017-05-26 21:17:14 +0000 UTC

标量类型

对于 https://docs.github.com/en/graphql/reference/scalars 列出的 GitHub GraphQL schema 中的每个标量，githubv4 包中都有对应的 Go 类型。

你可以在编写查询时使用这些类型：

var query struct {
	Viewer struct {
		Login          githubv4.String
		CreatedAt      githubv4.DateTime
		IsBountyHunter githubv4.Boolean
		BioHTML        githubv4.HTML
		WebsiteURL     githubv4.URI
	}
}
// 调用 client.Query() 并在 query 中使用结果...

然而，根据你计划如何使用查询结果，使用其他 Go 类型通常会更方便。

encoding/json 规则用于将 GraphQL 响应中的单个 JSON 编码字段转换为 Go 值。详情请参阅 https://godoc.org/encoding/json#Unmarshal。会遵循 json.Unmarshaler 接口。

这意味着你可以通过使用预声明的 Go 类型来简化前面的查询：

// import "time"

var query struct {
	Viewer struct {
		Login          string    // 例如，"gopher"。
		CreatedAt      time.Time // 例如，time.Date(2017, 5, 26, 21, 17, 14, 0, time.UTC)。
		IsBountyHunter bool      // 例如，true。
		BioHTML        string    // 例如，`I am learning <a href="https://graphql.org">GraphQL</a>!`。
		WebsiteURL     string    // 例如，"https://golang.org"。
	}
}
// 调用 client.Query() 并在 query 中使用结果...

DateTime 标量被描述为"ISO-8601 编码的 UTC 日期字符串"。如果你想以该形式获取而不解析为 time.Time，可以使用 string 类型。例如，这样可以工作：

// import "html/template"

type MyBoolean bool

var query struct {
	Viewer struct {
		Login          string        // 例如，"gopher"。
		CreatedAt      string        // 例如，"2017-05-26T21:17:14Z"。
		IsBountyHunter MyBoolean     // 例如，MyBoolean(true)。
		BioHTML        template.HTML // 例如，template.HTML(`I am learning <a href="https://graphql.org">GraphQL</a>!`)。
		WebsiteURL     template.URL  // 例如，template.URL("https://golang.org")。
	}
}
// 调用 client.Query() 并在 query 中使用结果...

参数和变量

通常，你会想要在某些字段上指定参数。你可以使用 graphql 结构体字段标签来实现这一点。

例如，要进行以下 GraphQL 查询：

{
	repository(owner: "octocat", name: "Hello-World") {
		description
	}
}

你可以定义这个变量：

var q struct {
	Repository struct {
		Description string
	} `graphql:"repository(owner: \"octocat\", name: \"Hello-World\")"`
}

然后调用 client.Query：

err := client.Query(context.Background(), &q, nil)
if err != nil {
	// 处理错误
}
fmt.Println(q.Repository.Description)

// 输出：
// My first repository on GitHub!

然而，这只适用于参数是常量且预先已知的情况。否则，你需要使用变量。将结构体字段标签中的常量替换为变量名：

// fetchRepoDescription 获取指定所有者和名称的仓库描述。
func fetchRepoDescription(ctx context.Context, owner, name string) (string, error) {
	var q struct {
		Repository struct {
			Description string
		} `graphql:"repository(owner: $owner, name: $name)"`
	}

在向 GraphQL 发送变量时，你需要使用与 GraphQL 标量类型完全匹配的类型，否则 GraphQL 服务器将返回错误。

因此，定义一个 variables 映射，其中包含转换为 GraphQL 标量类型的值：

	variables := map[string]interface{}{
		"owner": githubv4.String(owner),
		"name":  githubv4.String(name),
	}

最后，调用 client.Query 并提供 variables：

	err := client.Query(ctx, &q, variables)
	return q.Repository.Description, err
}

内联片段

一些 GraphQL 查询包含内联片段。你可以使用 graphql 结构体字段标签来表示它们。

例如，要进行以下 GraphQL 查询：

{
	repositoryOwner(login: "github") {
		login
		... on Organization {
			description
		}
		... on User {
			bio
		}
	}
}

你可以定义这个变量：

var q struct {
	RepositoryOwner struct {
		Login        string
		Organization struct {
			Description string
		} `graphql:"... on Organization"`
		User struct {
			Bio string
		} `graphql:"... on User"`
	} `graphql:"repositoryOwner(login: \"github\")"`
}

或者，你可以定义对应于内联片段的结构体类型，并在查询中将它们用作嵌入字段：

type (
	OrganizationFragment struct {
		Description string
	}
	UserFragment struct {
		Bio string
	}
)

var q struct {
	RepositoryOwner struct {
		Login                string
		OrganizationFragment `graphql:"... on Organization"`
		UserFragment         `graphql:"... on User"`
	} `graphql:"repositoryOwner(login: \"github\")"`
}

然后调用 client.Query：

err := client.Query(context.Background(), &q, nil)
if err != nil {
	// 处理错误
}
fmt.Println(q.RepositoryOwner.Login)
fmt.Println(q.RepositoryOwner.Description)
fmt.Println(q.RepositoryOwner.Bio)

// 输出：
// github
// How people build software.
//

分页

假设你想获取一个问题的完整评论列表，而不仅仅是前10条左右。要做到这一点，你需要执行多个查询并使用分页信息。例如：

type comment struct {
	Body   string
	Author struct {
		Login     string
		AvatarURL string `graphql:"avatarUrl(size: 72)"`
	}
	ViewerCanReact bool
}
var q struct {
	Repository struct {
		Issue struct {
			Comments struct {
				Nodes    []comment
				PageInfo struct {
					EndCursor   githubv4.String
					HasNextPage bool
				}
			} `graphql:"comments(first: 100, after: $commentsCursor)"` // 每页100条。
		} `graphql:"issue(number: $issueNumber)"`
	} `graphql:"repository(owner: $repositoryOwner, name: $repositoryName)"`
}
variables := map[string]interface{}{
	"repositoryOwner": githubv4.String(owner),
	"repositoryName":  githubv4.String(name),
	"issueNumber":     githubv4.Int(issue),
	"commentsCursor":  (*githubv4.String)(nil), // 获取第一页时使用空指针作为after参数。
}

// 获取所有页面的评论。
var allComments []comment
for {
	err := client.Query(ctx, &q, variables)
	if err != nil {
		return err
	}
	allComments = append(allComments, q.Repository.Issue.Comments.Nodes...)
	if !q.Repository.Issue.Comments.PageInfo.HasNextPage {
		break
	}
	variables["commentsCursor"] = githubv4.NewString(q.Repository.Issue.Comments.PageInfo.EndCursor)
}

执行分页有多种方式。可以考虑使用PageInfo对象中的其他字段。

突变操作

突变操作通常需要先执行查询来获取信息。假设你已经完成了这一步。

例如，要执行以下GraphQL突变：

mutation($input: AddReactionInput!) {
	addReaction(input: $input) {
		reaction {
			content
		}
		subject {
			id
		}
	}
}
variables {
	"input": {
		"subjectId": "MDU6SXNzdWUyMTc5NTQ0OTc=",
		"content": "HOORAY"
	}
}

你可以定义：

var m struct {
	AddReaction struct {
		Reaction struct {
			Content githubv4.ReactionContent
		}
		Subject struct {
			ID githubv4.ID
		}
	} `graphql:"addReaction(input: $input)"`
}
input := githubv4.AddReactionInput{
	SubjectID: targetIssue.ID, // 来自之前查询的目标问题的ID。
	Content:   githubv4.ReactionContentHooray,
}

然后调用client.Mutate：

err := client.Mutate(context.Background(), &m, input, nil)
if err != nil {
	// 处理错误。
}
fmt.Printf("为ID为%#v的主题添加了一个%v反应！\n", m.AddReaction.Subject.ID, m.AddReaction.Reaction.Content)

// 输出：
// 为ID为"MDU6SXNzdWUyMTc5NTQ0OTc="的主题添加了一个HOORAY反应！