tommwq.work/aip

AIP-141 数量

· [tommwq@126.com]
编号 141
原文链接 https://google.aip.dev/141
状态 批准
创建日期 2019-07-18
更新日期 2019-07-18

许多服务需要表示对象的具体数量（字节数、公里数、节点数等）。

指南

带有明确测量单位（如字节、公里等）的量 必须 包含测量单位后缀。适当时，单位 应当 使用通行缩写（例如使用 distance_km 而非 distance_kilometers ）。

// A representation of a non-stop air route.
message Route {
  // The airport where the route begins.
  string origin = 1;

  // The destination airport.
  string destination = 2;

  // The distance between the origin and destination airports.
  // This value is also used to determine the credited frequent flyer miles.
  int32 distance_miles = 3;
}

如果量是对象的数目（例如集群中的节点数），域 应当 使用后缀 _count （ 非 前缀 num_ ）：

// A cluster of individual nodes.
message Cluster {
  // The number of nodes in the cluster.
  int32 node_count = 1;
}

注意 域 不得 使用无符号整数类型，许多编程语言和系统不支持。

专用消息

有时可以创建一个表示特定数量的消息。这对以下两种场景非常有用：

适当时，API 可以 创建表示量的消息。使用这种消息作为域时，如果具有实际意义，API 应当 使用消息名字作为域名字的后缀。

修订记录

  • 2019-09-13 添加针对uint和fixed类型的禁令。