AIP-4221

```org

客户端重试

许多API都有客户端应重试的错误模式。这些错误模式因API而异，用户需要根据可用文档在客户端库周围手动编写重试逻辑。客户端库可以通过实现自动客户端重试已知错误模式来提供帮助。

指导

客户端库**应**提供自动的客户端重试逻辑。具有自动客户端重试逻辑的客户端库**应**提供一种机制，使用户可以指定要重试的错误代码以及这些重试的延迟。

支持远程解析客户端重试配置的API系统的客户端库**应**尊重远程解析的配置。然而，用户配置**必须**被优先考虑。

实现此功能的客户端库生成器**必须**接受重试配置。此重试配置**可以**通过`protoc`插件选项提供。在没有给定重试配置的情况下，客户端库生成器**不应**生成默认的重试配置。

重试实现

客户端库**应**使客户端重试对用户透明。用户**不应**需要明确选择加入客户端重试，但用户**必须**有一种方式可以完全禁用客户端重试。

重试配置机制

客户端库**应**提供一种机制，使用户可以控制客户端重试配置，包括完全禁用客户端重试。

例如，gRPC服务的Go客户端库可以在客户端初始化时提供一个选项WithDisableRetry，以禁用自动客户端重试逻辑的使用。

```go opts := []grpc.DialOption{ grpc.WithDisableRetry(), grpc.WithTransportCredentials(creds), }

cc, err := grpc.Dial(“my.api.net:443”, opts…) if err != nil { // … } ```

远程解析的客户端配置

一些API系统具有内置机制，使客户端可以检索远程定义的配置，其中包括客户端重试配置。

例如，gRPC支持客户端配置的解析，其中包括自动客户端重试的配置。

客户端库**应**尊重远程解析的配置，除非用户通过上述客户端库重试配置机制覆盖它。

客户端库生成器重试配置

实现客户端重试的客户端库生成器**必须**接受重试配置。这是为了使API生产者能够提供最适合其服务的重试配置。

例如，gRPC客户端重试通过RetryPolicy在gRPC服务配置中进行配置。以下是一个配置示例，该配置将`RetryPolicy`应用于`google.example.library.v1.LibraryService`服务中的所有方法，除了那些明确命名的方法，这些方法不应用`RetryPolicy`。

```json { “methodConfig”: [{ “name”: [{ “service”: “google.example.library.v1.LibraryService” }], “waitForReady”: true, “timeout”: “60s”, “retryPolicy”: { “maxAttempts”: 3, “initialBackoff”: “0.01s”, “maxBackoff”: “60s”, “backoffMultiplier”: 1.3, “retryableStatusCodes”: [“UNAVAILABLE”] } }, { “name”: [ { “service”: “google.example.library.v1.LibraryService”, “method”: “CreatePublisher” }, { “service”: “google.example.library.v1.LibraryService”, “method”: “DeletePublisher” }, { “service”: “google.example.library.v1.LibraryService”, “method”: “CreateBook” }, { “service”: “google.example.library.v1.LibraryService”, “method”: “DeleteBook” }, { “service”: “google.example.library.v1.LibraryService”, “method”: “UpdateBook” }, { “service”: “google.example.library.v1.LibraryService”, “method”: “MoveBook” } ], “waitForReady”: true, “timeout”: “60s” }] } ```

重试配置**可以**是`protoc`插件选项。例如，生成器可以接受配置文件的路径，如下所示：

–{plugin_name}_opt=“retry-config=/path/to/config.file”

在没有重试配置的情况下，生成器**不应**生成“默认”重试配置。这将导致生成的客户端库不会重试任何内容，除非用户配置它这样做。

进一步阅读

• 有关应重试的错误代码，请参见AIP-194。

变更日志

• **2020-09-23**：将示例从“shelves”更改为“publishers”，以提供更好的资源所有权示例。

```