整合者的最佳做法

想要和 GitHub 平臺進行整合？應(yīng)該是一個不錯的選擇。這個指南會幫助您創(chuàng)建一個應(yīng)用程序，并讓其在確保能可靠地和API交互的前提下為您的用戶提供最好的體驗。

• 保證 GitHub 發(fā)送過來的負載的安全
• 能夠異步的情況下就不要同步
• 當回應(yīng) GitHub 時使用恰當?shù)?HTTP 狀態(tài)碼
• 對用戶提供盡可能多的信息
• 跟隨所有 API 發(fā)來的重定向請求
• 不要手動解析 URL
• 處理速率限制
• 處理 API 錯誤

保證 GitHub 發(fā)送過來的負載的安全

保全從 GitHub 發(fā)送過來的負載是非常重要的。雖然沒有個人信息（例如密碼）會通過負載傳輸，但泄露任何信息終歸是不好的。因為有的信息可能會被認為敏感，例如發(fā)出 commit 的用戶郵箱或者私有存儲庫的名稱。

你能通過以下三個步驟來保全來自 GitHub 的負載：

1. 確保你的接收用服務(wù)器是工作在 HTTPS 連接上。默認情況下，每次發(fā)送負載時 GitHub 都會驗證 SSL 證書。

2. 你可以將我們發(fā)送 hook 時使用的 IP 地址添加進服務(wù)器的白名單。你還可以通過 /meta 端點來查找我們使用的地址，以確保你一直在使用我們正確的地址。

3. 提供一個秘密令牌來確保負載的確來自于 GitHub。使用秘密令牌，你就能確保你的服務(wù)器接收的任何數(shù)據(jù)都是絕對來自于 GitHub。理想情況下，你應(yīng)該為每個不同的用戶提供不同的秘密令牌，這樣即使一個令牌淪陷，也不至于影響到其他用戶。

能夠異步的情況下就不要同步

GitHub 期望整合服務(wù)器能在接收到 webhook 負載的 30 秒內(nèi)回應(yīng)。如果你的服務(wù)沒能在時限內(nèi)發(fā)出回應(yīng)，GitHub會終止連接，所發(fā)送的負載也將會丟失。

因為我們不可能預(yù)計你的服務(wù)會需要多長時間完成，你應(yīng)該將所有“真正的工作”放在后臺處理。Resque (用于 Ruby), RQ (用于 Python), 或 RabbitMQ (用于 Java) 都是一些用來控制后臺工作的排隊和處理的庫。

請注意即使有后臺工作正在運行，GitHub 仍然期望你的服務(wù)器能在 30 秒內(nèi)回應(yīng)。你的服務(wù)器只需要通過發(fā)送某種形式的回應(yīng)確認它接收了負載。所以你的服務(wù)能否在最短時間內(nèi)驗證負載是至關(guān)重要的，這樣才能即時準確地向 GitHub 回應(yīng)你的服務(wù)器是否還要繼續(xù)處理該次請求。

當回應(yīng) GitHub 時使用恰當?shù)?HTTP 狀態(tài)碼

每一個 webhook 都有它自己的“最近投遞”區(qū)域，里面寫明了一次部署是否成功。

http://wiki.jikexueyuan.com/project/github-developer-guides/images/webhooks_recent_deliveries.png" alt="最近投遞視圖" />

你應(yīng)該利用正確的 HTTP 狀態(tài)碼來告知用戶。你能使用類似 201 或 202 來確認一些不會被處理的負載（例如，一個由不是默認分支發(fā)送過來的負載）。保留錯誤碼 500 用于災(zāi)難性錯誤。

對用戶提供盡可能多的信息

用戶可以調(diào)查你發(fā)回給 GitHub 的服務(wù)器回應(yīng)。請確保你的信息清晰并且有用。

http://wiki.jikexueyuan.com/project/github-developer-guides/images/payload_response_tab.png" alt="查看一個負載回應(yīng)" />

跟隨所有 API 發(fā)來的重定向請求

當一個資源被移動時，GitHub 會很明確地通過一個重定向狀態(tài)碼告訴你。所以你應(yīng)該跟隨這些重定向請求。每一個重定向回應(yīng)都會將 Location 頭設(shè)定為目標 URI。如果你的收到一個重定向請求，你最好將新的 URI 更新到你的代碼，以防你再次要求一個我們隨時可能移除的已經(jīng)過時的路徑。

我們提供了一個 HTTP 狀態(tài)碼列表，以供您設(shè)計應(yīng)用程序時參考來執(zhí)行重定向請求。

不要手動解析 URL

經(jīng)常地，API 的回應(yīng)包含 URL 形式的數(shù)據(jù)。例如，當你請求一個存儲庫，我們會發(fā)送一個叫做 clone_url 的鍵，附帶你能用來復制存儲庫的 URL。

為了您的應(yīng)用程序穩(wěn)定性，你不應(yīng)該試圖解析這些數(shù)據(jù)，或者嘗試猜測和構(gòu)建未來 URL 的格式。一旦我們決定更改 URL 格式，你的程序就很可能失效。

舉例來說，當處理分頁結(jié)果時，自行構(gòu)建那些結(jié)尾帶有 ?page=<number> 的 URL 經(jīng)常顯得十分誘人。請抵制這種誘惑。遍歷分頁頁面指南會提供一些信息讓你安全可靠地跟隨分頁結(jié)果。

處理速率限制

GitHub API 速率限制確保了這套 API 對所有人都同樣快速和可用。

如果你達到速率限制，那么你應(yīng)該暫時停止發(fā)送請求，并且在你被允許的前提下稍后再試。不遵循這個規(guī)則將導致您的應(yīng)用程序被禁止。

你能隨時檢查你的速率限制狀況。查詢你的速率限制狀況所產(chǎn)生的通訊不會負面影響你的速率限制狀況。

處理 API 錯誤

盡管代碼也許從未引入任何 bug，但你還是可能會在訪問 API 的過程中遇到一連串的錯誤。

比起忽略接踵而來的 4xx 和 5xx 狀態(tài)碼，你更應(yīng)該確保你在用正確的方式和 API 進行互動。舉個例子，如果一個端點請求一個字符串，然而你卻返回了一個數(shù)字值，那必然會導致 5xx 驗證錯誤，該調(diào)用也不會成功。相似的，嘗試訪問一個未經(jīng)授權(quán)的甚至不存在的端點會引起 4xx 錯誤。

故意忽略多次驗證錯誤會導致您的應(yīng)用程序因為濫用被暫停。