命名约定

本文档旨在提供关于如何在 OpenStack 公共 REST API 中命名资源方面的指导，以便我们的 API 感觉一致且专业。

REST API 资源名称

• REST API 中的资源始终表示为 API 暴露的实体的复数形式。
• 在 REST API 中暴露的资源名称应使用全部小写字母。
• 资源名称可能包含连字符。
• 资源名称不应包含下划线或其他标点符号（唯一的例外是连字符）。

API 请求或响应体中的字段

对 API 的 HTTP 请求可能包含一个主体，该主体通常是用户希望创建或修改的资源的序列化表示形式。 类似地，HTTP 响应包含一个主体，该主体通常是服务器创建、修改或列出的资源的序列化表示形式。

这些序列化的请求和响应体内的字段应根据以下准则命名

• 字段名称应使用 snake_case 风格，而不是 CamelCase 或 StUdLyCaPs 风格。

布尔字段

布尔字段应命名为使名称完成短语“这是 _____”或“这具有 ____”。 例如，如果您需要一个字段来指示所讨论的项目是否已启用，则“enabled”将是正确的形式，而不是像“is_enabled”这样的形式。 同样，要指示使用 DHCP 的网络，应使用字段名“dhcp_enabled”，而不是像“enable_dhcp”或仅“dhcp”这样的形式。

强烈建议避免否定命名，因此使用“enabled”而不是“disabled”或“not_enabled”。 原因是阅读代码时很难理解双重否定。 在这种情况下，“not_enabled = False”比“enabled = True”更难理解。

布尔参数

有两种类型的布尔参数：一种用于提供如上所述的布尔字段的值，另一种用于影响所调用方法行为的参数。 在第一种情况下，参数的名称应与字段的名称匹配。 例如，如果您正在提供数据以填充名为“enabled”的字段，则参数名称也应为“enabled”。 但是，在第二种情况下，如果参数用于切换所调用方法的行为，则名称应更像动词。 此形式的一个示例是参数“force”，它通常用于指示该方法应在没有正常安全检查的情况下执行其操作。 并且与布尔字段一样，由于相同的原因，强烈不建议对布尔参数使用否定命名。

状态与状态

虽然这两个名称几乎意味着相同的事情，但它们之间存在差异。 一般来说，当记录流程中的步骤时，应使用“状态”。 换句话说，“状态”预计会发生变化，然后仅更改为少量后续状态。 这方面的一个例子是 VM 的构建，它遵循一系列步骤，并且要么移动到下一个状态，要么进入 ERROR 状态。

另一方面，“状态”应用于没有预期一系列更改的情况。 服务可能具有“up”或“active”的状态，并且预计应保持这种状态，除非管理员更改它，或者发生故障。