Java GitHub API 库使用指南

1. 引言

本文将带你了解 GitHub API For Java 库的使用方法。这个库提供了面向对象的 GitHub API 封装，让我们能在 Java 应用中轻松操作 GitHub。相比直接调用 REST API，这种封装能显著提升开发效率，减少踩坑概率。

2. 依赖配置

使用前需要添加最新版本依赖（当前为 1.327）。Maven 用户在 pom.xml 中添加：

<dependency>
    <groupId>org.kohsuke</groupId>
    <artifactId>github-api</artifactId>
    <version>1.327</version>
</dependency>

Gradle 用户同理，不再赘述。

3. 客户端创建

所有操作都始于 GitHub 客户端实例，这是与 GitHub API 交互的入口。创建方式分三种：

3.1 匿名连接

GitHub gitHub = GitHub.connectAnonymously();

✅ 优点：无需认证
❌ 缺点：功能受限（仅支持公开操作）

3.2 自动认证连接

GitHub gitHub = GitHub.connect();

库会按优先级自动寻找凭证：

环境变量 GITHUB_OAUTH（个人访问令牌）
环境变量 GITHUB_JWT（JWT 令牌）
环境变量 GITHUB_LOGIN + GITHUB_PASSWORD（用户名密码）
用户主目录下的 .github 文件（属性名小写，无 GITHUB_ 前缀）

⚠️ 若未找到有效凭证，创建会失败

3.3 手动指定凭证

GitHub github = new GitHubBuilder()
    .withOAuthToken("my_personal_token")
    .build();

GitHub github = new GitHubBuilder()
    .withJwtToken("my_jwt_token")
    .build();

GitHub github = new GitHubBuilder()
    .withPassword("my_user", "my_password")
    .build();

💡 懒加载机制：凭证仅在需要认证的接口调用时验证，匿名操作不受影响

4. 用户信息操作

4.1 获取当前用户

GHMyself myself = gitHub.getMyself();

查询示例：

assertEquals("someone", myself.getLogin());
assertEquals("someone@example.com", myself.getEmail());
assertEquals(50, myself.getFollows().size());

4.2 查询其他用户

GHUser user = gitHub.getUser("eugenp");
assertEquals("eugenp", user.getLogin());
assertEquals(2, user.getFollows().size());

📌 GHUser 是 GHMyself 的父类。当前用户（GHMyself）独有权限包括：

管理公钥
管理邮箱
管理组织成员资格

5. 仓库操作

5.1 列出仓库

从用户对象获取仓库列表：

PagedIterable<GHRepository> repositories = user.listRepositories();

可指定分页大小（默认30）：

PagedIterable<GHRepository> repositories = user.listRepositories(50);

三种获取方式对比： | 方式 | 特点 | 适用场景 | |------|------|----------| | toArray()/toList()/toSet() | 立即加载所有数据 | 仓库数量少时 | | toIterator() | 按需加载 | 大量仓库时 | | 增强 for 循环 | 自动分页加载 | 常规遍历 |

示例（高效遍历）：

Set<String> names = new HashSet<>();
for (GHRepository repo : user.listRepositories()) {
    names.add(repo.getName());
}

5.2 直接访问仓库

通过用户对象：

GHRepository repository = user.getRepository("tutorials");

或通过客户端（需完整路径）：

GHRepository repository = gitHub.getRepository("eugenp/tutorials");

5.3 仓库信息查询

基础信息：

String name = repository.getName();
String fullName = repository.getFullName();
GHUser owner = repository.getOwner();
Date created = repository.getCreatedAt();

Git 操作：

String defaultBranch = repository.getDefaultBranch();
GHBranch branch = repository.getBranch(defaultBranch);
String branchHash = branch.getSHA1();

GHCommit commit = repository.getCommit(branchHash);
System.out.println(commit.getCommitShortInfo().getMessage());

文件内容读取：

String defaultBranch = repository.getDefaultBranch();
GHContent file = repository.getFileContent("pom.xml", defaultBranch);
String fileContents = IOUtils.toString(file.read(), Charsets.UTF_8);

特殊文件（自动识别文件名）：

GHContent readme = repository.getReadme();
GHContent license = repository.getLicenseContent();

5.4 仓库操作

修改配置：

repository.setDescription("A new description");
repository.setVisibility(GHRepository.Visibility.PRIVATE);

Fork 仓库：

repository.createFork().name("my_fork").create();

创建分支/标签/PR：

repository.createRef("new-branch", oldBranch.getSHA1());
repository.createTag("new-tag", "This is a tag", branch.getSHA1(), "commit");
repository.createPullRequest("new-pr", "from-branch", "to-branch", "Description of the pull request");

⚠️ 创建提交等复杂操作需额外处理

6. 总结

本文介绍了 GitHub API For Java 库的核心功能，包括：

客户端创建（匿名/认证）
用户信息查询
仓库操作（列表/访问/查询/修改）

这只是冰山一角，该库还支持 Issues、Webhooks 等高级功能。下次需要操作 GitHub 时，不妨试试这个简单粗暴的解决方案。

所有示例代码可在 GitHub 获取。

Persistence

REST

Security