1. 簡介

在本文中，我們將研究 GitHub API For Java 庫。該庫為我們提供了一個面向對象的 GitHub API 的表示，從而使我們能夠輕鬆地從 Java 應用程序中與之交互。

2. 依賴項

要使用 GitHub API for Java 庫，我們需要在我們的構建中包含 最新版本，目前是 1.327。

如果我們在使用 Maven，可以在我們的 pom.xml 文件中包含此依賴項：

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

此時，我們已準備好在我們的應用程序中使用它。

3. 客户端創建

為了使用該庫，我們首先需要創建一個 GitHub客户端實例。這作為與 GitHub API 交互的主要入口點。

創建此實例的最簡單方法是匿名連接：

GitHub gitHub = GitHub.connectAnonymously();

這允許我們訪問 API 而無需任何身份驗證憑據。但是，我們能夠使用此方法進行的功能受到限制。

或者，我們可以使用憑據連接：

GitHub gitHub = GitHub.connect();

這將嘗試以多種方式確定用於使用的憑據：

• 如果環境屬性 GITHUB_OAUTH已設置，則將使用它作為個人訪問令牌。
• 否則，如果環境屬性 GITHUB_JWT已設置，則將其用作 JWT 令牌。
• 否則，如果同時設置了 GITHUB_LOGIN和 GITHUB_PASSWORD，則將直接使用它們作為憑據。
• 否則，我們將嘗試使用用户的家目錄中的 .github屬性文件，以提供等效屬性。在這種情況下，名稱將轉換為小寫且不包含 GITHUB_前綴。

如果未提供任何這些值，則創建客户端將失敗。

我們還可以選擇通過手動提供憑據來創建客户端：

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();

如果我們選擇使用這些，我們就可以從任何我們希望的地方加載適當的憑據。

請注意，該庫僅在需要時使用這些憑據。這意味着如果提供的憑據無效，我們只會與需要身份驗證的 API 交互時才發現。如果使用任何以匿名方式工作的 API 方法，這些方法將繼續有效。

4. 我自己及其他用户一旦我們創建了客户端，我們就可以開始與 GitHub API 交互。

如果我們擁有經過身份驗證的客户端，我們就可以使用它來查詢我們已認證的身份 – 也就是 Myself:

GHMyself myself = gitHub.getMyself();

然後我們可以使用此對象來查詢當前用户：

assertEquals("someone", myself.getLogin());
assertEquals("[email protected]", myself.getEmail());
assertEquals(50, myself.getFollows().size());

我們還可以查詢其他用户的詳細信息：

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

這返回一個 GHUser，它是 GHMyself 的父類。因此，我們可以對 GHMyself 對象 – 代表當前已認證的用户 – 執行某些操作，而不能在任何其他用户身上執行這些操作。這些包括：

管理公鑰

管理電子郵件地址

管理組織成員關係

但是，任何期望接收一個 GHUser 的對象也可以接受一個 GHMyself 作為輸入。

5. Repositories

我們還可以與倉庫一起工作，以及與用户一起工作。 這將包括查詢用户擁有的倉庫列表，但也可以訪問倉庫的內容，甚至對其進行修改。

5.1. Listing Repositories

如果我們有 GHUser 對象 – 或 GHMyself ，則我們可以使用它來獲取該用户擁有的倉庫。 這通過使用 listRepositories() 實現：

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

這給了我們一個 PagedIterable ，因為這些倉庫可能數量非常多。 默認情況下，它與一個頁面大小為 30 的大小一起工作，但如果需要，我們可以指定在列出倉庫時使用的頁面大小：

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

這然後給了我們訪問實際倉庫的多種方式。 我們可以將其轉換為 Array、List 或 Set 類型，其中包含所有倉庫的集合：

Array<GHRepository> repositoriesArray = repositories.toArray();
 List<GHRepository> repositoriesList = repositories.toList();
 Set<GHRepository> repositoriesSet = repositories.toSet();

但是，這些會一次性獲取所有內容——這在有大量倉庫的情況下可能很昂貴。 例如，Microsoft 用户 擁有 6,688 個倉庫。 如果頁面大小為 30 個倉庫，則需要 223 個 API 調用來收集完整列表。

或者，我們可以獲取倉庫的迭代器。 這將僅在需要時才進行 API 調用，從而使我們能夠更有效地訪問集合：

Iterator<GHRepository> repositoriesSet = repositories.toIterator();

更簡單的是，PagedIterable 本身就是一個 Iterable ，並且可以在任何適用之處直接使用它——例如，在增強型 for 循環中：

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

這只是迭代返回的所有倉庫並提取它們的名稱。 因為我們正在使用 PagedIterable ，所以它將像一個正常的 Iterable ，但僅在需要時才進行 API 調用。

5.2. Directly Accessing Repositories

除了列出倉庫之外，我們還可以直接通過名稱訪問它們。 如果我們有適當的 GHUser ，則我們只需要倉庫名稱：

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

或者，我們可以直接從我們的客户端訪問倉庫。 在這種情況下，我們需要組合用户名和倉庫名稱成一個字符串：

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

這然後給 us the exact same GHRepository object as if we’d navigated through the GHUser object.

5.3. Working With Repositories

一旦我們有了 GHRepository 對象，我們就可以直接與之交互。

在最簡單的情況下，這允許 us to retrieve repository details such as its name, owner, creation date, and more.

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

但是，我們也可以查詢倉庫的內容。 我們可以通過將其視為 Git 倉庫來做到這一點——允許 us to access branches, tags, commits, and so on:

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);
 

如果存在，我們也可以訪問某些特殊文件——特別是 readme 和 license：

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

這些與直接訪問文件相同，但無需知道文件名。 尤其是，GitHub 支持用於這些概念的不同文件名，並且它將返回正確的名稱。

5.4. Manipulating Repositories

除了讀取倉庫內容之外，我們還可以對其進行修改。

這包括更改倉庫本身的配置，允許 us to do things like changing the description, home page, visibility, and so on:

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

我們還可以將其他倉庫“fork”到我們的帳户中：

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

我們還可以創建分支、標籤、 pull request 和其他內容：

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");
 

甚至可以創建 commit 如果需要，儘管這更復雜。

6. 結論

在本文中，我們對 GitHub Java 庫進行了簡短的概述。 還有很多可以利用該庫完成的任務。 下次您需要與 GitHub API 交互時，為什麼不嘗試一下？