AIP-4234

· [tommwq@126.com]

```org

通用服务客户端混入

通常，API可以具有用于管理资源的通用功能，这些功能被分离到实用服务中。这些通用的实用服务在离散的产品服务之间共享。这些通用服务每个都有一个集中定义的表面，但各个实例与每个产品服务一起托管。因此，由产品服务托管的每个通用服务的表面在运行时“混入”。

指导

客户端库**可以**为其API声明为混入的通用服务提供客户端方法。这些方法通过从配置为与托管混入服务的产品服务通信的客户端呈现混入方法，从而改善用户体验。

如果客户端库支持混入服务，它们**必须**支持以下通用服务（并且**可以**支持其他服务）：

`google.cloud.location.Locations`
`google.iam.v1.IAMPolicy`
`google.longrunning.Operations`

注意： 支持的混入服务列表和混入服务本身都很少更改。任何要支持的新通用服务**必须**添加到此处列表中，并且生成器**必须**更新。

要生成到客户端库中，混入服务**必须**在google.api.Service的apis下声明。此外，只有在同一google.api.Service的http配置中声明了google.api.http绑定的RPC才能生成（有关这些绑定的更多详细信息，请参见AIP-127）。如果混入服务RPC在google.api.Service中没有声明google.api.http规则，则**不得**生成。

实现混入支持

生成器配置

客户端库生成器**必须**接受YAML格式的google.api.Service文件路径。此文件通过一个**必须**为可选的标志指定。换句话说，对于省略混入方法的基本客户端生成，该标志**不得**是必需的。

混入API客户端配置

如果混入API利用客户端库配置（即注释、默认重试设置等），例如`google.api.method_signature`或请求头注入，生成器**可以**在生成的混入方法中支持它，前提是配置是可访问的。

在客户端库配置需要完全限定名称的地方，**必须**使用混入的完全限定名称。也就是说，主机服务**不得**像在自己的包中一样引用混入元素。

例如，配置`google.iam.v1.IAMPolicy.GetIAMPolicy`的默认重试和超时设置如下：

```json { “name”: [{ “service”: “google.iam.v1.IAMPolicy”, “method”: “GetIAMPolicy” }], “timeout”: “60s”, “retryPolicy”: { “initialBackoff”: “0.1s”, “maxBackoff”: “5s”, “backoffMultiplier”: 1.3, “retryableStatusCodes”: [“UNKNOWN”] } } ```

生成混入方法

混入API RPC**应该**作为主机API服务客户端库表面上的方法生成，与主机服务的RPC一起。这使它们作为客户端上的顶级方法呈现，但在底层，应调用适当的混入API存根或请求。然而，生成器**可以**选择以更符合语言习惯的方式呈现混入API RPC。

注意： 对于gRPC客户端，**必须**使用混入API gRPC存根以正确构造gRPC请求。例如，生成的Go gRPC存根LocationsClient必须用于调用`google.cloud.location.Locations`混入的RPC，而不是主机服务的gRPC存根。

多个主机服务客户端

如果主机API定义了多个服务，这些服务将导致生成多个客户端，生成器**必须**在所有符合条件的生成服务客户端上包含混入方法。

覆盖重复的RPC

如果主机服务已经定义了具有相同名称的RPC，客户端库生成器**不得**在任何主机服务客户端上生成混入方法。例如，采用以下服务定义：

```proto service LibraryService { rpc ListBooks(ListBooksRequest) returns (ListBooksResponse);

// 其他主机API RPCs…

// google.iam.v1.IAMPolicy混入服务的重新定义。 rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy);

rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy);

rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse); } ```

如果主机API声明`google.iam.v1.IAMPolicy`为混入服务，客户端库生成器**不得**生成与上述明确声明的名称匹配的混入方法，用于主机proto包中的_任何_服务客户端，但它们**必须**生成此混入的其他方法。在这种情况下，生成器**可以**记录警告，指示避免了冲突，或者静默跳过有问题的混入方法。

```