系统
浅色
深色GitHub 为什么选择 JSON Schema
返回博客挑战
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 数据的适当模式，就无法验证代码更改是否引入了新的错误，也无法确保从外部来源获取的数据是否符合自动化文档页面所需的格式。
解决方案
该团队开始引入 JSON Schema 来验证所有 JSON 数据文件、上下文数据和作为应用程序一部分消耗或生成的 API 请求主体。每次更改数据模型时，模式都会相应更新，并且在任何情况下，模式都用于验证应用程序在每次更改后是否都能正常运行。
这主要通过三种方式实现
- 当应用程序在生产环境中运行时，每个 API 调用都会通过相应的 JSON Schema 验证其请求主体，然后将事件传递到数据仓库
- 在自动化管道中检索外部数据时，无论何时将数据从源格式转换为 JSON，都会根据 JSON Schema 验证生成的 data，以确保数据已正确转换。如果验证成功，则生成的 data 会被检入 git 存储库以在生产环境中使用。否则，将引发故障以供调查。
在运行持续集成时，每次更改应用程序时，各种额外的模式都会确保
- YAML 前端属性已正确包含在用于在应用程序中生成页面的 Markdown 文件中
- 包含页面内容的 YAML 或 JSON 数据文件（由内容编写人员手动编写）已正确格式化
- 在运行时创建的上下文对象（包含整个网站内容以及应用程序的网站树）本身已正确格式化
“选择 JSON Schema 以允许 JSON Schema 验证是我们团队做出的自然而然的决定。自我们从静态网站迁移到动态应用程序大约 3 年前，它就一直是我们应用程序的基础部分。” - Rachael Sewell 和 Robert Sese，GitHub 的文档工程师
影响
在平台中引入 JSON Schema 对生产力、可发现性和可靠性产生了重大影响。
“JSON Schema 使得查看数据形状及其属性类型变得更加容易。我可以快速打开磁盘上的文件并了解数据结构。这在扩展依赖于模式支持的数据的功能时可以为整个团队节省时间。” - Rachael Sewell 和 Robert Sese，GitHub 的文档工程师
GitHub 团队行动迅速，文档团队每天发布 20 次或更多次到生产环境，并且严重依赖持续集成来检查每一次提交，以确保更改按预期工作。持续集成中的故障会在更改发布到生产环境之前提醒团队，JSON Schema 验证是确保应用程序所需的所有 JSON 数据都已正确格式化的一个重要组成部分。
GitHub - 公司
GitHub 是全球最大的开发人员平台，帮助全球各地的开发人员和组织构建、扩展和交付安全的软件。
该公司总部位于美国加利福尼亚州旧金山，但其招聘和工作文化以远程优先为导向。
在 GitHub 内部，有一个名为教育、社区和开源软件的内部组织，该组织负责负责文档应用程序的文档团队。这个文档团队由内容编写人员、内容设计师、文档产品经理以及文档设计师和文档工程师组成。
感谢 GitHub 文档工程团队的软件工程师 Rachael Sewell 和 Robert Sese，他们维护着很棒的 docs.github.com，以及整个 GitHub 团队，感谢他们分享他们的经验并允许我们与大家分享。