重要：此 crate 的功能已集成到 tonic-types 中，并将在那里积极维护。此存储库不再维护。

Tonic Richer Error

使用 tonic 实现 gRPC 富错误模型的资源。

此 crate 引入了 WithErrorDetails trait 并在 tonic::Status 中实现它，允许以方便的方式使用 gRPC 富错误模型。

示例 | 网站 | 文档

使用方法

WithErrorDetails trait 为 tonic::Status 添加了关联函数，可用于服务器端创建带有错误详情的状态，然后将其返回给 gRPC 客户端。此外，该 trait 还为 tonic::Status 添加了方法，可用于 tonic 客户端提取错误详情，并轻松处理。

入门

要构建此 crate，您必须安装 Protocol Buffer 编译器 protoc。说明请参阅 此处。

[dependencies]
tonic = "0.8"
tonic-richer-error = "0.3"

示例

以下示例涵盖了基本的使用场景。更完整的服务器和客户端实现可以在示例目录中找到。

服务器端：使用tonic::Status生成带有ErrorDetails结构的ErrorDetails

use tonic::{Code, Status};
use tonic_richer_error::{ErrorDetails, WithErrorDetails};

// ...
// Inside a gRPC server endpoint that returns `Result<Response<T>, Status>`

// Create empty `ErrorDetails` struct
let mut err_details = ErrorDetails::new();

// Add error details conditionally
if some_condition {
    err_details.add_bad_request_violation(
        "field_a",
        "description of why the field_a is invalid"
    );
}

if other_condition {
    err_details.add_bad_request_violation(
        "field_b",
        "description of why the field_b is invalid",
    );
}

// Check if any error details were set and return error status if so
if err_details.has_bad_request_violations() {

    // Add additional error details if necessary
    err_details
        .add_help_link("description of link", "https://resource.example.local")
        .set_localized_message("en-US", "message for the user");

    let status = Status::with_error_details(
        Code::InvalidArgument,
        "bad request",
        err_details,
    );

    return Err(status);
}

// Handle valid request

// ...

客户端：从tonic::Status中提取ErrorDetails结构

use tonic::{Response, Status};
use tonic_richer_error::WithErrorDetails;

// ...

// Where `req_result` was returned by a gRPC client endpoint method
fn handle_request_result<T>(req_result: Result<Response<T>, Status>) {
    match req_result {
        Ok(response) => {
            // Handle successful response
        },
        Err(status) => {
            let err_details = status.get_error_details();
            if let Some(bad_request) = err_details.bad_request {
                // Handle bad_request details
            }
            if let Some(help) = err_details.help {
                // Handle help details
            }
            if let Some(localized_message) = err_details.localized_message {
                // Handle localized_message details
            }
        }
    };
}

发送不同的标准错误消息

在ErrorDetails文档中提供了多个示例。有关如何正确使用标准错误消息类型字段的说明，请参阅error_details.proto。

替代的tonic::Status相关函数和方法

在WithErrorDetails文档中，展示了与tonic::Status交互的替代方法，使用包裹在ErrorDetail枚举中的错误详情结构体的向量。这种方法可以在必要时提供对将生成或接收的标准错误消息向量的更多控制。有关如何采用此方法，请参阅WithErrorDetails::with_error_details_vec和WithErrorDetails::get_error_details_vec文档，以及示例目录。

除此之外，WithErrorDetails文档中还提供了多个使用替代错误详情提取方法的示例，如果客户端只处理一种类型的标准错误消息，这将特别有用。例如，使用WithErrorDetails::get_details_bad_request是从tonic::Status中提取BadRequest错误消息的更直接的方法。

许可证

此项目使用MIT许可证。

贡献

除非您明确表示，否则您有意提交的任何贡献都将按MIT许可证授权，不附加任何其他条款或条件。