Async-GraphQL 错误扩展机制深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00421/article/details/148577310

Async-GraphQL 错误扩展机制深度解析

async-graphql A GraphQL server library implemented in Rust 项目地址: https://gitcode.com/gh_mirrors/as/async-graphql

前言

在 GraphQL 服务开发中，错误处理是一个非常重要的环节。传统的错误信息往往只包含简单的错误消息，这对于客户端调试和问题定位来说远远不够。Async-GraphQL 提供了强大的错误扩展机制，允许开发者为错误添加丰富的上下文信息，极大提升了错误信息的可用性。

错误扩展的基本概念

GraphQL 规范中定义了错误扩展的概念，它允许在错误响应中添加额外的扩展信息。这些扩展信息以键值对的形式存在，可以提供错误的详细上下文、错误代码、解决建议等。

在 Async-GraphQL 中，所有面向用户的错误都会被转换为 Error 类型。默认情况下，错误会通过 std::fmt::Display 暴露错误消息，但开发者可以通过扩展机制添加更多信息。

基础使用示例

让我们看一个简单的例子，了解如何在解析器中返回带有扩展信息的错误：

async fn parse_with_extensions(&self) -> Result<i32, Error> {
    Err(Error::new("解析失败")
        .extend_with(|_, e| {
            e.set("error_code", "PARSE_ERROR");
            e.set("suggestion", "请检查输入是否为有效数字");
        }))
}

这样的错误会返回如下 JSON 响应：

{
  "errors": [
    {
      "message": "解析失败",
      "extensions": {
        "error_code": "PARSE_ERROR",
        "suggestion": "请检查输入是否为有效数字"
      }
    }
  ]
}

ErrorExtensions 特性

Async-GraphQL 提供了 ErrorExtensions 特性，使得错误扩展更加方便。这个特性可以将任何错误转换为带有扩展信息的 Error。

转换标准库错误

我们可以轻松地将标准库中的错误转换为带有扩展信息的 GraphQL 错误：

use std::num::ParseIntError;

async fn parse_int(&self, input: &str) -> Result<i32> {
    input.parse()
        .map_err(|err: ParseIntError| 
            err.extend_with(|_err, e| {
                e.set("code", 400);
                e.set("input_value", input);
            })
        )
}

为自定义错误实现扩展

对于自定义错误类型，我们可以实现 ErrorExtensions 特性：

#[derive(Debug, thiserror::Error)]
pub enum ApiError {
    #[error("资源未找到")]
    NotFound,
    
    #[error("无效参数: {0}")]
    InvalidArgument(String),
    
    #[error("内部服务器错误")]
    InternalError,
}

impl ErrorExtensions for ApiError {
    fn extend(&self) -> Error {
        Error::new(self.to_string()).extend_with(|err, e| {
            match self {
                ApiError::NotFound => {
                    e.set("code", "NOT_FOUND");
                    e.set("severity", "low");
                }
                ApiError::InvalidArgument(_) => {
                    e.set("code", "INVALID_ARGUMENT");
                    e.set("severity", "medium");
                }
                ApiError::InternalError => {
                    e.set("code", "INTERNAL_ERROR");
                    e.set("severity", "high");
                }
            }
        })
    }
}

使用方式：

async fn get_resource(&self, id: i32) -> Result<Resource> {
    if id < 0 {
        return Err(ApiError::InvalidArgument("ID不能为负数".to_string()).extend());
    }
    // ...
}

ResultExt 特性

ResultExt 特性提供了更简洁的错误扩展方式，可以直接在 Result 上调用 extend_err 方法：

async fn validate_input(&self, input: &str) -> Result<()> {
    if input.is_empty() {
        Err("输入不能为空")
            .extend_err(|_, e| {
                e.set("code", "EMPTY_INPUT");
                e.set("required_length", 1);
            })
    } else {
        Ok(())
    }
}

链式扩展

Async-GraphQL 支持链式调用扩展方法，这使得错误信息的构建更加灵活：

async fn complex_operation(&self) -> Result<i32> {
    let result = "123a".parse()
        .map_err(|e| e
            .extend_with(|_, e| e.set("stage", "parsing"))
            .extend_with(|_, e| e.set("timestamp", Utc::now().to_rfc3339()))
            .extend_with(|_, e| e.set("code", 500))?;
    
    Ok(result)
}

实际应用建议

错误分类：为不同类型的错误定义不同的扩展信息，如错误代码、严重程度等
调试信息：在开发环境中添加更多调试信息，如堆栈跟踪、输入参数等
用户指导：提供用户友好的建议信息，帮助用户解决问题
错误追踪：添加请求ID、时间戳等信息，方便日志追踪

注意事项

当前实现的一个限制是由于 Rust 稳定版缺少特化功能，ErrorExtensions 是为 &E 而非 E 实现的。这意味着在某些情况下需要特别注意：

// 这样会编译失败
"123a".parse().extend_err(|_, e| e.set("code", 400))

// 正确的写法
"123a".parse()
    .map_err(|ref e| e.extend_with(|_, e| e.set("code", 400)))