OpenStackClient/HumanInterfaceGuidelines
[注意：截至2015年1月，此页面不再维护，当前的OpenStackClient Human Interface Guide 在源代码仓库中维护，可以在 OpenStack Documentation 中找到]]
注意：此页面仅涵盖 OpenStackClient CLI，但看起来很熟悉，因为它源自 Horizon HIG。
概述
什么是 HIG？Human Interface Guidelines 文档是为 OpenStack 设计人员创建的，旨在指导新的 OpenStackClient 命令界面的创建。
Personas
用户画像是系统的典型用户。在设计界面时，请记住这些类型的用户。
Alice 管理员
Alice 是一位管理员，负责维护 OpenStack 云安装。她拥有多年的 Linux 系统管理经验。
Darren 部署者
Darren 负责在主机上执行初始 OpenStack 部署。
Emile 最终用户
Emile 使用云在虚拟机内进行软件开发。她使用命令行工具，因为她觉得它比使用仪表板更快。
原则
本节建立的原则定义了在设计和评估 OpenStack 命令行界面交互时要使用的最高级别优先级。原则范围广泛，可以被认为是 OpenStack 体验的哲学基础；虽然它们可能不会描述设计的具体实施，但它们应在决定多个设计方案时使用。
设计 OpenStack 体验的一个重要主题是关注系统的常见用法，而不是增加复杂性以支持很少使用的功能。
一致性
OpenStack 体验之间的一致性将确保命令行界面感觉像一个单一的体验，而不是一个由不同的产品组成的混合体。破碎的体验只会破坏用户对他们应该如何与系统交互的期望，从而创建一个不可靠的用户体验。为了避免这种情况，系统内的每个交互和视觉表示都必须以统一且可预测的方式使用。本文档中详细介绍的架构和元素将为建立一致的体验提供坚实的基础。
示例评审标准
- 命令操作是否坚持一致的应用操作？
- 是否引入了新的命令主题或输出？
- 设计是否使用如（核心元素）中定义的命令元素（选项和参数）？
- 是否可以使用现有元素完成任何新提出的命令元素（操作或主题）？
- 设计是否遵循核心体验的结构模型？（见核心架构）
- 是否以与核心体验中其他地方处理方式相矛盾的方式显示或操作任何数据对象？
简洁性
为了最好地支持新用户并创建直接的交互，设计应该尽可能简洁。在创建新命令时，设计应该尽量减少输出中存在的噪音：大量不必要的数据、过多的可能操作等。设计应该关注命令的意图，仅需要必要的组件，并删除多余的元素或通过可选参数使其可访问。OpenStack 使用表格的一个例子是：默认情况下仅显示最常用的列。可以通过输出控制选项访问更多数据，允许用户指定他们在日常工作中发现有用的数据类型。
示例评审标准
- 是否可以使用选项来组合否则相似的命令？
- 显示元素中有多少与大多数用户相关？
- 如果用户需要多个操作才能完成任务，那么每个步骤都是必需的，还是可以使流程更有效？
以用户为中心的设计
命令应该基于用户将如何与系统交互来设计，而不是系统后端的组织方式。虽然数据库结构和 API 可能会定义什么是可能的，但它们通常不会定义良好的用户体验；考虑用户的目标以及用户希望如何与他们的数据交互，然后为这些工作流程设计并使界面适应用户，而不是让用户适应界面。
命令应该可以通过界面本身发现。
要确定可用命令列表，请使用 ``-h`` 或 ``--help`` 选项
$ openstack --help
要获取单个命令的帮助，请使用 ``help`` 命令
$ openstack help server create
示例评审标准
- 用户能多快地弄清楚如何完成给定的任务？
- 内容是否已根据使用关系进行分组和排序？
- 工作流程是否支持用户目标或增加复杂性？
透明性
确保用户了解其基础设施和交互的当前状态。例如，用户应该能够轻松访问有关每个机器/虚拟机的状态信息，而无需主动寻找此信息。每当用户发起操作时，请确保显示确认信息[1]，以表明已收到输入。在流程完成后，请确保告知用户。确保用户永远不会质疑其环境的状态。
[1] 这与常见的 UNIX 哲学相悖，即仅报告错误条件和明确请求的输出。
示例评审标准
- 用户在发起流程时是否收到反馈？
- 流程完成后呢？
- 用户是否可以快速访问其基础设施的状态？
架构
命令结构
OpenStackClient 对其所有命令都具有一致且可预测的格式。
- 顶级命令名称是
openstack - 子命令的形式是
openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]
子命令应具有三个不同的部分（按其出现的顺序）
- 全局选项
- 命令对象和动作
- 命令选项和参数
输出格式
- 用户友好的表格，带有标题等
- 机器可解析的分隔符
笔记
- 所有长选项名称应以两个破折号 ('--') 开头，并在单词之间使用单个破折号 ('-') (
--like-this)。选项名称中不应使用下划线 ('_')。 - 身份验证选项符合 通用 CLI 身份验证指南。
全局选项
全局选项在某种程度上是全局的，即它们适用于每个命令调用，无论要执行的动作如何。它们包括身份验证凭据和 API 版本选择。大多数全局选项都有一个相应的环境变量，也可以用来设置该值。如果同时存在，命令行选项优先。环境变量名称是通过删除前导破折号 ('--')、将每个嵌入的破折号 ('-') 转换为下划线 ('_') 以及转换为大写来派生的。
例如，可以通过环境变量 `OS_USERNAME` 设置 `--os-username`。
--help
标准的 `--help` 全局选项在标准输出上显示调用程序的文档和可用命令列表。当存在此选项时，将忽略所有其他选项和命令。
FIXME(aspiers)：抄袭自“GNU 标准的 --help”。我们是否要抄袭其余部分并建议输出格式像这样？
- 在 `--help` 选项的输出结尾附近，请放置行，给出错误报告的电子邮件地址、软件包的主页以及通用帮助页面。格式应如下所示
Home page: <https://openstack.org/> Documentation: <https://docs.openstack.org/> Report bugs via: <https://openstack.org/community/>
--version
FIXME(aspiers): 抄袭自“GNU 标准的 --version 的开头。但还有许多其他好的想法可以复制。
- 标准的 `--version` 选项应指示程序在标准输出上打印有关其名称、版本、来源和法律状态的信息，然后成功退出。看到此选项后，应忽略其他选项和参数，并且程序不应执行其正常功能。
- 第一行旨在易于程序解析；正确的版本号从最后一个空格之后开始。此外，它包含此程序的规范名称，格式如下
OpenStack Nova (Compute) 2012.1.0.3
- 程序的名称应是一个常量字符串；不要从 `sys.argv` 计算它。想法是说明程序的标准或规范名称，而不是其文件名。有其他方法可以找到 `PATH` 中找到命令的精确文件名。
命令对象和动作
命令由一个或多个单词描述的对象后跟一个动作组成。需要两个对象的命令，主要对象位于动作之前，次要对象位于动作之后。标识对象的任何位置参数应按对象出现的顺序排列。用糟糕的英语表达，它是“(执行) 对象 1 (并执行) 动作 (使用) 对象 2 (到它)。”
<object-1> <action> <object-2>
示例
* group add user <group> <user> * volume type list # 'volume type' is a two-word single object
`help` 命令是唯一的，因为它出现在普通命令之前，并显示该命令的帮助文本，而不是执行它。
- 对象名称始终在命令中以单数形式指定。这与自然
语言用法相反。
命令参数和选项
每个命令可能有自己的一组与全局选项不同的选项。它们遵循与全局选项相同的样式，并且始终出现在命令及其所需的任何位置参数之间。
选项形式
- *布尔值*：布尔选项应使用 `--<true>|--<false>`（首选）或 `--<option>|--no-<option>` 的形式。例如，项目的 `enabled` 状态使用 `--enable|--disable` 设置。
命令输出
默认命令输出使用 Python `prettytable` 模块进行美观打印。
可以使用 `--format` 选项指定机器可解析的输出格式到 `list` 和 `show` 命令。`list` 命令具有一个选项 (`--format csv`) 用于 CSV 输出，`show` 命令具有一个选项 (`--format shell`) 用于 shell 变量赋值语法 `var="value"`。在两种情况下，所有数据字段都用 `"` 引号括起来
- [FIXME(ijw): 如果我想在命令行上解析输出，没有一种形式的引用，那么不能保证任何分隔符都是安全的。是否可以编写保证与例如所有实例名称一起工作的脚本？] [(dtroyer) 我在这里更新了文本以反映当前的情况。两种输出格式都用引号括起来。]**
帮助命令
由于其在命令中的特殊地位，帮助系统被单独考虑。它不是对系统执行任务，而是提供有关可用命令的信息来执行这些任务。因此，`help` 命令的格式与用于其他命令的格式不同，因为 `help` 命令出现在第一个对象之前。
选项 `--help` 和 `-h` 显示全局选项和受支持的命令列表。请注意，显示的命令取决于生效的 API 版本；即，如果存在 `--os-identity-api-version=3`，则显示 Identity API v3 命令。
示例
以下示例描述了 OpenStack 客户端预期产生的常见命令和输出格式。
身份验证
使用全局选项：
openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url https://:5000:/v2.0 server show appweb01 +------------------------+-----------------------------------------------------+ | Property | Value | +------------------------+-----------------------------------------------------+ | OS-DCF:diskConfig | MANUAL | | OS-EXT-STS:power_state | 1 | | flavor | m1.small | | id | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 | | image | Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef) | | keyname | demo-key | | name | appweb01 | | private_address | 10.4.128.13 | | status | ACTIVE | | user | demo | +------------------------+-----------------------------------------------------+
使用环境变量：
export OS_TENANT_NAME=ExampleCo export OS_USERNAME=demo export OS_PASSWORD=secrete export OS_AUTH_URL=https://:5000:/v2.0 openstack server show appweb01 +------------------------+-----------------------------------------------------+ | Property | Value | +------------------------+-----------------------------------------------------+ | OS-DCF:diskConfig | MANUAL | | OS-EXT-STS:power_state | 1 | | flavor | m1.small | | id | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 | | image | Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef) | | keyname | demo-key | | name | appweb01 | | private_address | 10.4.128.13 | | status | ACTIVE | | user | demo | +------------------------+-----------------------------------------------------+
机器输出格式
使用带有列表命令的 csv 输出格式
openstack server list --format csv "ID","Name","Status","Private_Address" "ead97d84-6988-47fc-9637-3564fc36bc4b","appweb01","ACTIVE","10.4.128.13"
使用 show 命令选项的 shell 输出格式，并添加前缀 'my_' 以避免与现有环境变量冲突
openstack server show --format shell --prefix my_ appweb01 my_OS-DCF:diskConfig="MANUAL" my_OS-EXT-STS:power_state="1" my_flavor="m1.small" my_id="dcbc2185-ba17-4f81-95a9-c3fae9b2b042" my_image="Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef)" my_keyname="demo-key" my_name="appweb01" my_private_address="10.4.128.13" my_status="ACTIVE" my_user="demo"
