当前位置：首页 > news >正文

AIP-145 范围

news 来源：原创 2025/9/22 9:39:19

编号	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_ 前缀。对于不适用例外场景的其他范围，服务应当不含结束值，且必须用文档清楚记录每个范围是否包含结束值。

指南

范围边界

时间戳区间

例外

相关文章：