AIP-145 范围
| 编号 | 145 |
|---|---|
| 原文链接 | AIP-145: Ranges |
| 状态 | 批准 |
| 创建日期 | 2020-05-28 |
| 更新日期 | 2020-05-28 |
服务通常需要表示具体值或连续值的范围。这些范围的含义存在诸多差异，也存在许多数据类型：整数、浮点数、时间戳等（在此仅举几例）。根据所讨论范围的类型，范围的预期含义可能存在细微差异。
指南
表示范围的资源或消息通常 应当 使用两个相同类型的独立域，前缀为 start_ 和 end_ ：
// A representation of a chapter in a book.
message Chapter {
string title = 1;
// The page where this chapter begins.
int32 start_page = 2;
// The page where the next chapter or section begins.
int32 end_page = 3;
}
范围边界
大多数情况下，表示范围的域 应当 包含起始值，不含结束值（左闭右开区间）；用区间来表示，即： [start_xxx, end_xxx) 。
不含结束值更好，原因在于：
- 符合用户预期，特别是对于时间戳等连续值；避免了使用不精确“极限值”的需要（例如
2012-04-20T23:59:59）。 - 与大多数常见编程语言一致，包括C++、Java、Python和Go。
- 容易推理相邻范围：
[0, x), [x, y), [y, z)，值可以从一个范围链接到下一个。
时间戳区间
本节介绍了google.type.Interval类型的用法，它是AIP-213中介绍的常用组件之一，表示两个时间戳之间的范围，包含起始值，不含结束值。
两个时间戳之间的范围，如果符合 Interval 消息设计预期， 应当 使用此类型，而非独立的起始和结束域。这允许客户端使用 Interval 消息编码（例如检查给定时间戳是否在区间内），并在API中，甚至多个API中的不同时间戳区间中复用。
API 可以 使用起始和结束时间戳域作为备选方案。特别是如果API中的消息本质上描述了时间戳区间并且包含额外信息。使用 Interval 消息并引入额外嵌套级别未必是好的。
例外
在某些情况下，存在明显的俗成先例，包含起始和结束值（闭区间），使得不含结束值可能导致习惯了先例的人感到困惑。
例如在讨论日期（不要和时间戳混淆）时，大多数人会包含结束值：日期为“4月21日至23日”的会议预计将持续三天：4月21日、4月22日和4月23日。这也适用于星期几：营业时间为“周一到周五”的企业在周五是营业的，不会关闭。
此时 应当 使用前缀 first 和 last 代替：
// A representation of a chapter in a book.
message Chapter {
string title = 1;
// The first page of the chapter.
int32 first_page = 2;
// The last page of the chapter.
int32 last_page = 3;
}
表示具有明显俗成先例的、包含起始和结束值的范围的域， 应当 仅对这些范围包含结束值，并使用 first_ 和 last_ 前缀。对于不适用例外场景的其他范围，服务 应当 不含结束值，且 必须 用文档清楚记录每个范围是否包含结束值。