什么是规范的 YAML 命名风格

Posted 2023-02-26

【中文标题】什么是规范的 YAML 命名风格

【英文标题】：What is the canonical YAML naming style

【发布时间】：2014-05-11 08:41:00

【问题描述】：

我正在设计一个新的 YAML 文件，我想使用最标准的命名风格。是哪个？

连字符？

- job-name:
    ...

lower_case_with_underscores?

- job_name:
    ...

驼峰式？

- jobName:
    ...

【参考方案1】：

使用周围软件规定的标准。

例如，在我当前的项目中，YAML 文件包含 Python 属性的默认值。由于 YAML 中使用的名称出现在相关的 Python API 中，因此很明显，在这个特定项目中，YAML 名称应遵循 PEP-8 中的 Python lower_case_with_underscores 命名约定。

我的下一个项目可能有不同的流行命名约定，在这种情况下，我将在关联的 YAML 文件中使用它。

【讨论】：

YAML 是独立的，所以它不服从任何东西。

我同意@Miraage。而且，从实用的角度来看，如果“周边软件”是用多种语言编写的呢？

@RobWorsnop 就像他说的那样，它与软件语言无关。您可以使用您最喜欢的 CASE。

yaml 名称可以以下划线开头吗？比如，_jobname__，更准确地说，我需要这个，__version__

至少，使用任何将要读取 yaml 的约定。例如，您最终可能需要做更多的工作才能让 kebab-cased-properties 在 C# 或 Java 中正确反序列化。在有人问之前：如果你有多个组件，更不用说在不同的技术中读取相同的 yaml，那可能有点异味。

【参考方案2】：

Kubernetes 使用 camelCase：https://kubernetes.io/docs/user-guide/jobs/

apiVersion, restartPolicy

使用snake_case的CircleCI：https://circleci.com/docs/1.0/configuration/

working_directoryrestore_cache，store_artifacts

带有破折号的Jenkins：https://github.com/jenkinsci/yaml-project-plugin/blob/master/samples/google-cloud-storage/.jenkins.yaml

stapler-class

---

所以看起来项目和团队使用自己的约定，并且没有一个明确的标准。

【讨论】：

添加：GitLab 和 Ansible 都使用snake_case：docs.gitlab.com/ee/ci/yamlgithub.com/ansible/ansible-examples/blob/master/lamp_simple/…

你说得对，没有通用标准。我认为重要的是要指出 CircleCI 和 GitLab 都在使用 snake_case 和 kebab-case 的 mix。也许在第一次发布答案的时候不是这样，但现在是这样。 GitHub Actions（一种较新的基于 yaml 的 ci 服务）使用 kebab-case（至少对于所有主要配置选项）。

【参考方案3】：

根据多年经验得出的不太受欢迎的意见：

TL;DR

显然遵守约定，但恕我直言，遵循在项目的 YML 文件中建立的约定，而不是依赖项附带的约定。我敢说，命名约定取决于太多因素，无法给出明确的答案，甚至无法描述“有一些”以外的良好做法。

完整答案

库可能会随着时间的推移而发生变化，这会导致在一个配置中出现多个命名约定，这比任何理智的程序员想要的都要频繁 - 除非您想引入（并稍后维护）一个全新的专用抽象层，否则您无能为力仅此而已：保持参数命名约定原始。

为什么您会在配置与依赖项附带的配置中需要不同的命名约定的一个示例是可搜索性，例如如果所有依赖项都使用名为 request_id 的参数，则将您的参数命名为 request-id 或 requestId 将使其与众不同且易于搜索，同时不会影响名称的描述性。

此外，有时将多个同名参数嵌套在不同的命名空间中是有意义的。在这种情况下，根据一些现有的命名约定发明一个全新的命名约定可能是合理的，例如：

order.request-id.format 和 notification.request-id.format

虽然您的 IDE 可能没有必要区分这两者（因为它能够在命名空间中为参数编制索引），但出于对同行的礼貌，您还是可以考虑这样做 - 不仅是其他可能使用不同的开发人员IDE，尤其是 DevOps 和管理员，他们通常确实在维护、迁移和部署期间使用不太专业的工具。

最后，我的一位同事提出的另一个好处是，可以通过一个简单的awk 命令轻松地将独特的参数名称转换为不同的约定。反过来这样做显然是可能的，但要复杂一个数量级，这通常会在 KISS 倡导者社区中引发关于“保持简单愚蠢”的真正含义的辩论。

结论是：做对你和你的团队最明智的事情。