AIP-2604

数值参数

一些API字段指的是百分比或固定数字。例如，在GCE中，可以创建一个组，并配置一个限制，该限制可以是组中同时进行维护的实例的百分比或数量：

```proto message ConcurrencyControl { enum LimitType { INVALID = 0; PERCENT = 1; FIXED = 2; } optional int32 concurrency_limit = 1; optional LimitType limit_type = 2; } ```

指导

标志布局

在gcloud中，这样的API字段应该对应于一个互斥组，该组由两个标志组成：一个用于指定数字，另一个用于指定百分比。因此，上面示例中的API字段将对应于gcloud中的以下表面规范：

```yaml

• group: mutex: true arguments:
  • name: concurrency-limit help_text: | 组中同时进行维护的最大实例数。
  • name: concurrency-limit-percent help_text: | 0到100之间的整数，表示组中同时进行维护的最大实例百分比。

```

标志命名

任何接受百分比的标志应以`-percent`结尾（而不是`-percentage`）。

标志类型

任何接受百分比的标志应接受0到100之间的整数。如果需要更高的精度，可以接受0到100之间的浮点数。

考虑的替代方案

一个标志，如果标志值以’%‘结尾，则指定百分比，否则假定为数字

换句话说，要指定10%，可以使用`–concurrency-limit=10%`，要指定10个实例，可以使用`–concurrency-limit=10`。

这将是一个更简洁的设计，因为它自然地将一个概念（限制）映射到一个标志（`–concurrency-limit`），避免了需要额外的标志来使帮助文本变得杂乱。

然而，不推荐这种方法的主要原因是它显著增加了用户错误的风险。例如，假设一个组当前包含20个实例，并发限制为10%，用户希望将限制更新为20%。如果用户发出描述命令（或执行GET请求）以查看现有限制，API响应将包含类似以下内容：

```yaml concurrencyControl: concurrencyLimit: 10 limitType: PERCENT ```

用户很容易忽略limitType，并假设`–concurrency-limit=20`会将限制更新为20%。然而，实际上这将把限制设置为20个实例（组的100%），可能导致灾难性的后果。

推荐的方法以牺牲一些优雅为代价避免了这种歧义，但我们认为这种权衡是必要的。

一个标志，如果标志值以’%‘结尾，则指定百分比，如果标志值以’n’结尾，则指定数字

换句话说，要指定10%，可以使用`–concurrency-limit=10%`，要指定10个实例，可以使用`–concurrency-limit=10n`。如果提供的值不以’%‘或’n’结尾，则会出现错误。

虽然这避免了用户混淆百分比和数字的可能性，但要求在数字末尾加上’n’是不优雅的用户体验。数字显然应该像数字，而选择’n’也相当随意。

例外

此CIP不适用于像时间戳这样的API字段，我们允许用户在同一标志中输入绝对时间或持续时间。这是因为绝对时间和持续时间具有不同的自然格式，因此用户不可能混淆两者。一般来说，如果是这种情况，为了用户体验的简单性，应优先选择一个接受两种格式的标志。