山东 网站备案网站流量查询站长之家
| 编号 | 143 |
|---|---|
| 原文链接 | AIP-143: Standardized codes |
| 状态 | 批准 |
| 创建日期 | 2019-07-24 |
| 更新日期 | 2019-07-24 |
许多常见的概念，如语言、国家、货币等，都有用于数据通信和处理的通用代号（通常由国际标准化组织正式定义）。这些代号解决了在书面语言中，同一概念往往存在多种表达方式的问题（如“United States”和“USA”、“Español”和“Spanish”）。
指南
对于存在标准代号且广泛使用的概念，表示这些概念的域 应当 使用标准代号进行输入和输出。
// A message representing a book.
message Book {// Other fields...// The IETF BCP-47 language code representing the language in which// the book was originally written.// https://en.wikipedia.org/wiki/IETF_language_tagstring language_code = 99;
}
- 表示标准概念的域 必须 为标准代号选择合适的数据类型（通常是
string）。- 表示标准概念的域 不应 使用枚举，即使只允许一个很小的取值集合。在这种情况下使用枚举，往往导致在使用多个API时出现令人沮丧的查找表。
- 表示标准概念的域 必须 表明所遵守的标准，最好带上链接（指向标准本身、维基百科描述或类似内容）。
- 域名字 应当 以
_code或_type结尾，概念拥有更明确后缀的除外。 - 在处理用户输入值时，验证过程 应当 是大小写不敏感的，除非可能引发歧义（如
en-gb和en-GB）。当向用户返回值时，API 应当 使用规范大小写（上例中的en-GB）。
内容类型
表示内容或媒体类型的域 必须 使用IANA媒体类型。由于历史原因，域 应当 称为 mime_type 。
国家和地区
表示单个国家或地区的域 必须 使用Unicode CLDR地区代号（列表），例如 US 或 CH ，域 必须 称为 region_code 。
重要提示 请阅读此要求的理由。
货币
表示货币的域 必须 使用ISO-4217货币代号，例如 USD 或 CHF ，域 必须 称为 currency_code 。
注意 要表示以特定货币计价的金额，而非货币代号本身，请使用google.type.Money。
语言
表示语言的域 必须 使用IETF BCP-47语言代号（列表），例如 en-US 或 de-CH ，域 必须 称为 language_code 。
时区
表示时区的域 应当 使用IANA TZ代号，域 必须 称为 time_zone 。
域也 可以 表示UTC偏移量而非时区（注意两者存在细微差别）。此时，域 必须 使用ISO-8601格式， 必须 命名为 utc_offset 。
理由
国家地区域名字
使用 region_code 而非 country_code 非常重要，可以表达与国家不同的地区，避免与地区主权或归属有关的政治争端。许多公司是Unicode CLDR的支持者，按照Unicode CLDR标准进行产品国际化工作，API也不例外。此外，Unicode CLDR支持的许多值本身并不是国家，因此使用更通用的名字实际上更符合规范。此外，Unicode CLDR支持的值很多本身并非独立国家，使用更通用的名字实际上与规范更兼容。
修订记录
- 2024-12-03 补充国家地区域名字理由。
- 2024-11-12 将国家地区代号列表从IANA列表改为CLDR列表。
- 2020-05-12 将
country_code指南替换为region_code，修正之前的错误。