knife_util/

error.rs

use anyhow::Error as AnyhowError;
use serde_json::Value;
use std::fmt;

/// 应用程序统一错误类型
///
/// 提供结构化的错误处理，支持错误链、上下文信息和序列化。
/// 设计用于替代简单的字符串错误，提供更丰富的错误信息。
///
/// # 特性
/// - **错误代码**: 机器可读的错误标识符
/// - **错误消息**: 人类可读的错误描述
/// - **详细信息**: 可选的详细错误信息
/// - **上下文**: JSON 格式的上下文数据
/// - **错误链**: 支持原始异常和堆栈追踪
///
/// # 示例
/// ```rust
/// use knife_util::AppError;
///
/// let error = AppError::new("FILE_NOT_FOUND", "配置文件不存在")
///     .with_message_detail("路径: /etc/app/config.toml")
///     .with_attribute("file_path", "/etc/app/config.toml");
/// ```
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct AppError {
    /// 错误代码 - 机器可读的错误标识符
    pub code: String,
    /// 错误消息 - 人类可读的错误描述
    pub message: String,
    /// 详细错误信息 - 可选的额外错误详情
    pub message_detail: Option<String>,
    /// 上下文信息 - JSON 格式的上下文数据
    pub context: Value,
    /// 原始异常和堆栈追踪 - 不参与序列化
    #[serde(skip_serializing, skip_deserializing)]
    pub source: Option<AnyhowError>,
}

impl AppError {
    /// 创建新的错误实例
    pub fn new(code: &str, message: &str) -> Self {
        Self {
            code: code.to_string(),
            message: message.to_string(),
            message_detail: None,
            context: Value::Object(serde_json::Map::new()),
            source: None,
        }
    }

    /// 获取错误代码
    pub fn code(&self) -> &str {
        &self.code
    }

    /// 获取错误消息
    pub fn message(&self) -> &str {
        &self.message
    }

    /// 获取详细错误信息
    pub fn message_detail(&self) -> Option<&str> {
        self.message_detail.as_deref()
    }

    /// 设置详细错误信息
    pub fn with_message_detail(mut self, detail: &str) -> Self {
        self.message_detail = Some(detail.to_string());
        self
    }

    /// 添加上下文信息
    pub fn with_attribute(mut self, key: &str, value: impl Into<Value>) -> Self {
        if let Value::Object(ref mut map) = self.context {
            map.insert(key.to_string(), value.into());
        }
        self
    }

    /// 获取上下文信息
    pub fn get_attribute(&self, key: &str) -> Option<&Value> {
        self.context.get(key)
    }

    /// 设置完整的上下文信息
    pub fn with_context(mut self, context: Value) -> Self {
        self.context = context;
        self
    }

    /// 获取原始异常信息
    pub fn source(&self) -> Option<&AnyhowError> {
        self.source.as_ref()
    }

    /// 设置原始异常信息
    pub fn with_source(mut self, source: AnyhowError) -> Self {
        self.source = Some(source);
        self
    }

    /// 从其他错误类型创建AppError
    pub fn from_error<E: std::error::Error + Send + Sync + 'static>(code: &str, message: &str, err: E) -> Self {
        Self {
            code: code.to_string(),
            message: message.to_string(),
            message_detail: None,
            context: Value::Object(serde_json::Map::new()),
            source: Some(AnyhowError::new(err)),
        }
    }

    /// 从anyhow::Error创建AppError
    pub fn from_anyhow(code: &str, message: &str, err: AnyhowError) -> Self {
        Self::new(code, message).with_source(err)
    }

    /// 从Display类型创建AppError
    pub fn from_display<E: std::fmt::Display>(code: &str, message: &str, err: E) -> Self {
        Self::new(code, message).with_message_detail(&err.to_string())
    }

    /// 从Display类型创建AppError并保存原始错误
    pub fn from_display_with_source<E: std::fmt::Display + std::error::Error + Send + Sync + 'static>(code: &str, message: &str, err: E) -> Self {
        Self::new(code, message).with_message_detail(&err.to_string()).with_source(AnyhowError::new(err))
    }

    /// 获取完整的错误堆栈信息
    pub fn get_cause(&self) -> Option<String> {
        self.source.as_ref().map(|err| {
            let mut trace = String::new();
            trace.push_str(&format!("Error: {}\n", err));
            let mut error: &dyn std::error::Error = err.as_ref();
            let mut depth = 0;
            while let Some(source) = error.source() {
                depth += 1;
                trace.push_str(&format!("CausedBy ({}): {}\n", depth, source));
                error = source;
            }
            let backtrace = err.backtrace();
            if backtrace.status() == std::backtrace::BacktraceStatus::Captured {
                trace.push_str(&format!("Backtrace:\n{}", backtrace));
            }
            trace
        })
    }
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "AppError [{}] {}", self.code, self.message)?;

        if let Some(detail) = &self.message_detail {
            write!(f, "\n\tMessageDetail: {}", detail)?;
        }

        if let Value::Object(map) = &self.context
            && !map.is_empty()
        {
            write!(f, "\n\tContextAttribute:")?;
            for (key, value) in map {
                write!(f, "\n\t\t{}: {}", key, value)?;
            }
        }

        if let Some(source) = &self.source {
            write!(f, "\n\tErrorSource: {}", source)?;
            if let Some(cause) = self.get_cause() {
                write!(f, "\n\tErrorCause:")?;
                for line in cause.lines() {
                    write!(f, "\n\t\t{}", line)?;
                }
            }
        }

        Ok(())
    }
}

impl std::error::Error for AppError {}

impl Clone for AppError {
    fn clone(&self) -> Self {
        Self {
            code: self.code.clone(),
            message: self.message.clone(),
            message_detail: self.message_detail.clone(),
            context: self.context.clone(),
            source: self.source.as_ref().map(|err| AnyhowError::msg(err.to_string())),
        }
    }
}

impl From<std::io::Error> for AppError {
    fn from(err: std::io::Error) -> Self {
        let kind_str = format!("{:?}", err.kind());
        let message = err.to_string();
        AppError::from_error("IO_ERROR", "IO异常", err)
            .with_attribute("io_error_kind", kind_str)
            .with_attribute("io_error_message", message)
    }
}

impl From<tracing_subscriber::util::TryInitError> for AppError {
    fn from(err: tracing_subscriber::util::TryInitError) -> Self {
        let message = err.to_string();
        AppError::from_error("LOGGING_INIT_ERROR", "日志系统初始化失败", err).with_attribute("tracing_init_error", message)
    }
}

impl From<AppError> for std::io::Error {
    fn from(err: AppError) -> Self {
        if let Some(source) = err.source.as_ref()
            && let Some(io_error) = source.downcast_ref::<std::io::Error>()
        {
            return std::io::Error::new(io_error.kind(), io_error.to_string());
        }
        std::io::Error::other(err.to_string())
    }
}