為何 JSON Schema 在 GitHub 成為顯而易見的選擇

挑戰

GitHub 作為軟體開發人員和相關領域人士無處不在且不可或缺的工具，能夠實現高效的程式碼管理、無縫協作、自動化、專案管理等。超過 1 億的使用者依賴該平台，他們中的許多人每天都在使用它來建立和共享開源軟體。

GitHub 中包含大量功能，協助開發生命週期的所有環節，而支援這個不斷增長的功能列表的是 GitHub 內部開發的強大而複雜的底層平台，以及涵蓋新舊功能的廣泛文件。

GitHub 的文件託管在 docs.github.com，這本身也是一項巨大的工程，涵蓋了平台上無數頁的功能。過去，這些文件被分成兩個靜態產生的網站 (help.github.com 和 developer.github.com)，但在 2020 年，這些靜態網站被合併到一個新的動態應用程式中，該應用程式託管在 docs.github.com。GitHub 文件重生的完整故事最好在 GitHub 部落格上 這裡 和 這裡閱讀，但這項變更的一個重要結果是轉向資料驅動的文件，特別是對使用 JSON 進行內容驅動以及應用程式平台內部的相互通訊進行了大量投資。

更具體地說，部分頁面內容完全從 JSON 資料檔案自動組裝，部分 JSON 由內容撰寫人員手動撰寫。在平台內，應用程式可查詢的整個記憶體內容可以 JSON 格式檢索。

「如果無法根據 JSON Schema 驗證我們的 JSON 資料，將會導致生產環境中出現錯誤，例如自動化文件頁面上遺失資料或頁面無法使用」，GitHub 文件工程團隊的軟體工程師 Rachael Sewell 和 Robert Sese 解釋說。

如果沒有針對 JSON 資料的適當 Schema，就無法驗證程式碼變更是否引入了新錯誤，也無法確保從外部來源取用的資料符合自動化文件頁面所需的格式。

解決方案

該團隊開始引入 JSON Schema 來驗證應用程式作為一部分使用或產生的所有 JSON 資料檔案、內容資料和 API 請求主體。每次對資料模型進行變更時，Schema 都會相應更新，並且在任何情況下，Schema 都會用於驗證應用程式在每次變更時都能正常運作。

這發生在三個主要方面

• 當應用程式在生產環境中執行時，每個 API 呼叫都會透過相應的 JSON Schema 驗證其請求主體，然後再將事件傳遞給資料倉儲
• 當在自動化管線中擷取外部資料時，每當資料從來源格式轉換為 JSON 時，產生的資料都會根據 JSON Schema 進行驗證，以確保其已正確轉換。如果驗證成功，則會將產生的資料簽入 Git 儲存庫以在生產環境中使用。否則，將會提出失敗以進行調查。

• 每次對應用程式進行變更時執行持續整合時，各種額外的 Schema 可確保

  • YAML 前置屬性已正確包含在 Markdown 檔案中，這些檔案用於在應用程式中產生頁面
  • 包含頁面內容並由內容撰寫人員手動撰寫的 YAML 或 JSON 資料檔案格式正確
  • 在執行階段建立的內容物件包含網站的全部內容以及應用程式的網站樹狀結構本身格式正確

「選擇 JSON Schema 允許 JSON Schema 驗證是我們團隊做出的自然且顯而易見的選擇。自從我們大約 3 年前從靜態網站遷移到動態應用程式以來，它一直是我們應用程式的基本組成部分。」- GitHub 文件工程師 Rachael Sewell 和 Robert Sese

影響

在平台中引入 JSON Schema 在生產力、可發現性以及可靠性方面產生了有意義的影響。

「JSON Schema 使查看資料的形狀及其屬性類型變得容易得多。我可以快速打開磁碟上的檔案，並了解資料結構的外觀。當擴展依賴 Schema 支援的資料的功能時，這可以節省整個團隊的時間。」- GitHub 文件工程師 Rachael Sewell 和 Robert Sese

GitHub 團隊行動迅速，文件團隊每天發布到生產環境 20 次或更多次，並且非常依賴持續整合檢查每個提交，以確保變更按預期工作。持續整合中的失敗會在變更發布到生產環境之前提醒團隊，而 JSON Schema 驗證是確保應用程式所需的所有各種 JSON 資料格式正確的必要部分。

GitHub - 公司

GitHub 是世界上最大的開發人員平台，可幫助世界各地的開發人員和組織建置、擴展和交付安全的軟體。

它總部位於加州舊金山，但其招聘和工作文化是遠端優先。

與手頭主題相關的是，GitHub 內部有一個名為「教育、社群和開源軟體」的內部組織，其中設有負責文件應用程式的文件團隊。這個文件團隊由內容撰寫人員、內容設計師、文件產品經理以及文件設計師和文件工程師組成。

感謝 GitHub 文件工程團隊的軟體工程師 Rachael Sewell 和 Robert Sese，他們維護著出色的 docs.github.com，並感謝整個 GitHub 團隊分享他們的經驗並允許我們進一步與您分享。