AIP-4232

· [tommwq@126.com]

方法签名

在协议缓冲区的RPC中，每个RPC只接受一个参数：一个消息。然而，在非常简单的请求情况下，发送完整的消息结构可能会很麻烦。

许多RPC提供了关于请求中哪些部分是重要且常用的信息。在许多语言中，函数和方法接受多个位置或关键字参数。

指导

一些API提供了注释，提示如何有效地从单个请求对象转换为单独的参数，客户端库**可能**基于这些提示提供重载。

然而，实现此功能的客户端库**必须**保留接受完整请求对象的默认行为。换句话说，如果API向已发布的API**添加**此注释，生成的库更改**必须**是向后兼容的。

客户端库生成器**可能**也会选择在某些情况下提供此功能，但在其他情况下不提供，视环境而定。例如，以下任何策略都是允许的：

仅当签名中的所有参数都是原始类型时提供重载。
仅在提供多个签名时，为第一个签名提供重载，以避免冲突。
上述策略的任何组合。

在所有这些情况下，仍然适用请求对象始终被接受的要求。

此外，客户端库生成器**可能**选择为以下RPC类型的子集支持此功能：

一元
服务器流
客户端流
双向流

方法签名

带有[`google.api.method_signature`][method_signature]注释的RPC表示在支持的情况下需要具有扁平化方法签名的重载。字符串包含按顺序排列的逗号分隔参数。如果字段名称包含句点（`.`）字符，则表示嵌套字段。

RPC可以多次提供此注释以指定多个签名。顺序在这里很重要：在某些情况下，可能无法为提供的每个签名生成重载。在这种情况下，客户端库生成器**必须**遵循“首次匹配优先”策略（为冲突集中的第一个签名生成重载，并丢弃其余部分）。

注意： 由此推论，只有在**追加**方法签名注释时，才能保证向后兼容。

必需参数

通常，请求消息上的某些字段始终是必需的，如[AIP-203][]所述。

虽然客户端库通常不应对此进行验证（这是服务器的角色），但如果适合语言，客户端库**可能**在方法签名中区分必需参数和可选参数。如果字段使用`google.api.field_behavior`注释值`REQUIRED`进行注释，则视为必需字段：

```proto message TranslateTextRequest { // 要翻译的文本。 string q = 1 [(google.api.field_behavior) = REQUIRED]; } ```

注意： 字段行为的注释附加到_字段_，而不是方法。

限制

如果RPC在[`google.api.method_signature`][method_signature]中列出了嵌套字段（例如，`“foo.bar.baz”`），则除了最后一个字段外，任何单个组件字段都不能重复（继续示例，`baz`可以重复，但`foo`或`bar`不能重复）。实现此功能的代码生成器在遇到非终端重复字段作为字段名称时**必须**出错，并提供描述性错误消息。

如果有任何字段是必需参数，则所有必需参数都应出现在任何可选参数之前。实现此功能的代码生成器在遇到必需字段在可选字段之后时**应**出错，并提供描述性错误消息，如果生成的客户端库无效，则**必须**出错。

兼容性

删除、重新排序或更改现有的`google.api.method_signature`条目是客户端库的破坏性更改。相关的生成方法要么被完全删除，要么其签名被更改，这两者都会破坏用户代码。

变更日志

**2020-07-14**：添加了对支持某些RPC类型的注意事项
**2019-09-27**：添加了兼容性部分。

<!– prettier-ignore-start –> [aip-203]: ../0203.md [method_signature]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto#L100 <!– prettier-ignore-end –>