Format Atlas

指南

选择配置文件格式

先确认目标工具接受哪些格式。若有多种选择，应选团队能够安全验证和维护的格式。

应该选择哪种格式？

根据文件在工作流程中的用途选择格式。

  • API 与网页数据交换 → JSON
  • 易读的层级配置 → YAML
  • 以键值为主的配置 → TOML
  • 工具只接受指定格式 → 遵循其要求

优先确认工具支持

配置格式取决于应用、程序库、CI 系统和托管环境。请核对支持的格式及规范版本。

自动验证语法

JSON、YAML 和 TOML 都可能因语法或类型错误而无法读取。保存时或在 CI 中验证，且不要把凭据写入仓库中的配置文件。

候选格式

JSON

适用于: 接受 JSON 的 API 或设置

不太适用于: 需要注释的人工维护配置

YAML

适用于: 由人维护的层级配置

不太适用于: 担心缩进错误的简单交换

TOML

适用于: 以键值组织的配置

不太适用于: 明确要求 JSON 或 YAML 的工具

导出前注意事项

  • 确认目标工具支持的格式和规范版本。
  • 不要把凭据或私钥存入代码仓库。

相关比较

JSON vs TOMLJSON 广泛用于 API 和程序间数据交换。TOML 面向人工维护的应用配置，提供易读的键值、表格和数组结构。YAML vs TOMLYAML 和 TOML 都是用于人工维护配置的文本格式。YAML 支持灵活的层级结构；TOML 更强调通过键和值、表格明确而易读地表达设置。应根据工具和数据结构选择。JSON vs YAMLJSON 是常用于 API 和程序间数据交换的严格文本格式。YAML 的语法适合人工编辑配置和结构化数据。应结合工具生态与工作流选择。YAML 与 XMLYAML 和 XML 都能表示结构化数据。YAML 常用于人工维护的配置；依赖元素、属性、Schema 或命名空间的集成则常用 XML。

指南

选择数据交换格式先看接收系统的规范。结构化 API 数据可用 JSON；需要既有 Schema 的集成用 XML；单一表格可用 CSV。选择 Web 数据与配置格式API 等机器间交换可考虑 JSON；人工编辑的配置可考虑 YAML；已有 Schema 的集成可考虑 XML。配置和密钥应存放在哪里将普通配置与凭据分开，并根据访问需求为本地开发、CI 和生产环境选择合适的存放方式。

参考资料与规范