AIP-4236

· [tommwq@126.com]

API 可以使用 `google.api.api_version` 对服务进行注释。如果指定了 `google.api.api_version`，版本感知客户端**必须**在请求 API 时包含 `google.api.api_version` 的值。

### 预期的生成器和客户端库行为

如果服务使用 `google.api.api_version` 进行注释，客户端库生成器**必须**包含 HTTP 查询参数 `$apiVersion` 或 HTTP 头 `X-Goog-Api-Version`，但请求**不得**同时包含两者。

给定服务的生成文档**可以**包含 `google.api.api_version` 的值（如果它在源 protos 中存在）。

客户端**必须**将 `google.api.api_version` 的值视为不透明的，以确保强大的兼容性。这意味着版本字符串的特定格式或结构**不得**被解析或解释用于除识别预期 API 版本之外的任何目的。

## 原理

### 版本控制的必要性

使用 `google.api.api_version` 注释进行显式 API 版本控制对于维护客户端和服务之间的兼容性至关重要。随着服务的发展，它们的模式和行为可能会发生变化。通过指定 API 版本，客户端向服务传达其期望。这使得服务能够以与客户端理解一致的方式响应，防止由于不兼容的更改而导致的错误或意外结果。

### 不透明处理的重要性

将 `google.api.api_version` 值视为不透明的对于确保强大的兼容性保证非常重要。通过依赖此不透明标识符，客户端避免对底层版本控制方案做出假设，该方案可能会独立于 API 本身发生变化。这种灵活性允许服务提供商在不影响客户端兼容性的情况下发展其版本控制策略。

### 查询和头的互斥性

查询参数和头机制的存在是为了为不同的客户端环境提供灵活性。然而，如果同时允许两者，可能会导致值不同时的歧义。为了确保一致的版本识别并防止潜在的冲突，一次只能使用一种机制。