gRPC 状态码枚举文档

gRPC 状态码枚举文档

gRPC 框架定义了一系列的状态码，用于表示远程过程调用（RPC）的结果。以下是 grpc 命名空间中 StatusCode 枚举的详细说明：

OK (0)

• 操作成功，没有错误。
• 常见使用场景：远程过程调用成功完成。
• 错误处理建议：无需采取任何错误处理措施，正常流程。

CANCELLED (1)

• 操作被取消，通常是调用方主动请求的。
• 常见使用场景：调用方在操作完成前取消了请求。
• 错误处理建议：检查调用逻辑，确保在取消请求时释放资源，避免内存泄漏。

UNKNOWN (2)

• 未知错误。如果从另一个地址空间接收到的状态值属于在此地址空间未知的错误空间，或者API没有返回足够的错误信息，可能会返回此错误。
• 常见使用场景：系统内部错误，或者接收到来自未知错误空间的状态。
• 错误处理建议：记录错误详情，尝试重新执行操作，如果问题持续，可能需要联系系统管理员。

INVALID_ARGUMENT (3)

• 客户端指定了无效的参数。与 FAILED_PRECONDITION 不同，INVALID_ARGUMENT 表示无论系统状态如何，参数本身都是有问题的（例如，文件名格式错误）。
• 常见使用场景：调用方提供了不合规范的参数。
• 错误处理建议：验证输入参数的有效性，提供清晰的错误信息给调用方。

DEADLINE_EXCEEDED (4)

• 操作在完成前已超时。对于改变系统状态的操作，即使操作本身已经成功完成，也可能返回此错误。例如，即使服务器的响应是成功的，如果响应延迟导致超时，也可能返回此错误。
• 常见使用场景：操作因超时而未能完成。
• 错误处理建议：根据操作性质决定是否重试，考虑增加超时时间或优化性能。

NOT_FOUND (5)

• 请求的实体（如文件或目录）未找到。
• 常见使用场景：请求的资源（如文件、目录或数据库记录）不存在。
• 错误处理建议：确认资源路径或标识符，提供错误信息并可能要求用户重新输入。

ALREADY_EXISTS (6)

• 尝试创建的实体（如文件或目录）已存在。
• 常见使用场景：尝试创建已存在的资源。
• 错误处理建议：检查资源是否已存在，提供更新或删除现有资源的选项。

PERMISSION_DENIED (7)

• 调用者没有执行指定操作的权限。PERMISSION_DENIED 不应用于因资源耗尽导致的拒绝（应使用 RESOURCE_EXHAUSTED），也不应用于无法识别调用者的情况（应使用 UNAUTHENTICATED）。
• 常见使用场景：调用方没有足够的权限执行操作。
• 错误处理建议：要求调用方提供适当的权限或认证信息。

RESOURCE_EXHAUSTED (8)

• 资源耗尽，可能是每个用户的配额，或者整个文件系统没有空间。
• 常见使用场景：系统资源耗尽，如达到API调用配额限制。
• 错误处理建议：实施资源配额管理，提示用户减少请求频率或升级服务。

FAILED_PRECONDITION (9)

• 操作因系统不在操作执行所需的状态而被拒绝。例如，要删除的目录可能不为空，或者对非目录应用了删除操作等。
• 常见使用场景：操作依赖于特定的系统状态，而当前状态不满足要求。
• 错误处理建议：确保所有前提条件都满足后再重试操作。

ABORTED (10)

• 由于并发问题（如序列号检查失败、事务中止等）通常会导致操作中止。
• 常见使用场景：由于并发问题，如事务冲突，操作被中止。
• 错误处理建议：检查并发控制机制，可能需要重试或调整事务逻辑。

OUT_OF_RANGE (11)

• 操作尝试超出有效范围。例如，尝试读取文件末尾之后的内容。
• 常见使用场景：操作尝试超出了有效范围，如索引超出数组界限。
• 错误处理建议：检查索引或范围参数，确保它们在有效范围内。

UNIMPLEMENTED (12)

• 操作未实现或在此服务中不支持/未启用。
• 常见使用场景：请求的方法或功能在服务中未被实现。
• 错误处理建议：提示调用方该功能不可用，或提供替代方案。

INTERNAL (13)

• 内部错误。意味着底层系统预期的一些不变量已被破坏。如果看到这些错误，说明有严重的问题。
• 常见使用场景：内部错误，如系统崩溃或严重的程序错误。
• 错误处理建议：记录错误详情，尝试重启服务或联系技术支持。

UNAVAILABLE (14)

• 服务当前不可用。这很可能是暂时性的条件，通过带有退避的重试可能会得到纠正。注意，对于非幂等操作，重试并不总是安全的。
• 常见使用场景：服务不可用，可能是由于过载或维护。
• 错误处理建议：实施重试机制，增加退避策略，或提示用户稍后再试。

DATA_LOSS (15)

• 不可恢复的数据丢失或损坏。
• 常见使用场景：数据丢失或损坏，无法恢复。
• 错误处理建议：尝试从备份中恢复数据，如果没有备份，可能需要手动重建丢失的数据。

UNAUTHENTICATED (16)

• 请求没有有效的认证凭据进行操作。
• 常见使用场景：调用方未提供有效的认证凭据。
• 错误处理建议：要求调用方进行认证。

DO_NOT_USE (-1)

• 强制用户包含一个默认分支。
• 常见使用场景：这是一个保留值，不应用于实际的错误状态。
• 错误处理建议：如果遇到此状态码，检查代码逻辑，确保没有错误地使用此值。