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. Myself and Other Users
Once we’ve created a client, we can start to interact with the GitHub API.
If we’ve got a correctly authenticated client then we can use this to query the user that we’re authenticated as – known as 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. 倉庫
我們還可以與倉庫以及用户一起工作。 這將包括查詢用户擁有的倉庫列表的能力，但也包括訪問倉庫內容，甚至對其進行修改的能力。
請注意，GitHub 中的所有倉庫都由恰好一個用户擁有，因此我們需要知道用户名和倉庫名稱，才能正確訪問它們。
5.1. 列出倉庫
如果我們擁有一個 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();然而，這些方法會一次性獲取所有數據，如果數量非常龐大，可能會產生較高的成本。例如，微軟用户目前擁有6,688個倉庫。如果每頁獲取30個倉庫，則需要223次API調用才能收集完整的列表。
或者，我們可以獲取一個倉庫迭代器。這樣，API調用只會按需進行，從而更高效地訪問該集合：
Iterator<GHRepository> repositoriesSet = repositories.toIterator();儘管如此，<em PagedIterable</em> 本身也是一個 <em Iterable，可以直接在任何適用位置使用——例如，在增強型 for 循環中：
Set<String> names = new HashSet<>();
for (GHRepository ghRepository : user.listRepositories()) {
names.add(ghRepository.getName());
}
這段代碼簡單地遍歷所有返回的倉庫，並提取它們的名稱。由於我們使用了 PagedIterable，它將像一個普通的 Iterable 一樣，但在必要時會在幕後發起 API 調用。
5.2. 直接訪問倉庫
除了列出倉庫，我們還可以通過倉庫名稱直接訪問它們。如果擁有適當的 GHUser，則只需提供倉庫名稱即可：
GHRepository repository = user.getRepository("tutorials");當然，以下是翻譯後的內容：
或者，我們也可以直接從我們的客户端訪問倉庫。在這種情況下，我們需要將用户名和倉庫名合併成一個字符串。
GHRepository repository = gitHub.getRepository("eugenp/tutorials");這使得我們得到與通過瀏覽 GHUser 對象時完全相同的 GHRepository 對象。
5.3. 使用倉庫
一旦我們獲取了 GHRepository 對象，就可以直接與之交互。
最基本的功能是能夠檢索倉庫的詳細信息，例如倉庫名稱、所有者、創建日期以及更多信息。
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);如果它們存在，我們還可以訪問某些特殊文件——具體來説，是 readme 和 license 文件。
GHContent readme = repository.getReadme();
GHContent license = repository.getLicenseContent();這些工作方式與直接訪問文件完全相同，但無需知道文件名。特別是，GitHub 支持用於這些概念的不同文件名，它將返回正確的名稱。
5.4. 倉庫操作
除了讀取倉庫內容，我們還可以對其進行修改。
這包括更新倉庫本身的配置，例如更改描述、主頁、可見性等。
repository.setDescription("A new description");
repository.setVisibility(GHRepository.Visibility.PRIVATE);
我們還可以將其他倉庫打到我們的賬户中：
repository.createFork().name("my_fork").create();我們還可以創建分支、標籤、拉取請求和其他內容：
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 Java 庫進行了簡短的概述。 實際上，可以使用該庫做更多的事情。 下次您需要與 GitHub API 交互時，為什麼不嘗試一下呢。
