baichun-framework-db 0.1.0

//! 数据库错误处理模块
//!
//! 本模块定义了数据库操作过程中可能遇到的各种错误类型，包括：
//! - 连接错误
//! - 查询错误
//! - 事务错误
//! - 连接池错误
//! - 配置错误
//! - 迁移错误
//! - 验证错误
//!
//! 同时提供了错误处理的工具函数和类型别名。

use std::fmt::Debug;
use thiserror::Error;

/// 数据库模块错误类型
///
/// 定义了数据库操作中可能出现的所有错误类型。
/// 每种错误类型都包含详细的错误信息。
#[derive(Debug, Error)]
pub enum DbError {
    /// 数据库连接错误
    ///
    /// 当无法建立数据库连接时发生，可能的原因包括：
    /// - 网络问题
    /// - 认证失败
    /// - 数据库服务未启动
    #[error("Database connection error: {0}")]
    #[allow(dead_code)]
    Connection(String),

    /// 数据库查询错误
    ///
    /// 执行 SQL 查询时发生的错误，可能的原因包括：
    /// - SQL 语法错误
    /// - 表或字段不存在
    /// - 数据类型不匹配
    #[error("Database query error: {0}")]
    #[allow(dead_code)]
    Query(String),

    /// 数据库事务错误
    ///
    /// 在事务处理过程中发生的错误，例如：
    /// - 事务提交失败
    /// - 事务回滚失败
    /// - 事务超时
    #[error("Database transaction error: {0}")]
    #[allow(dead_code)]
    Transaction(String),

    /// 数据库连接池错误
    ///
    /// 连接池管理相关的错误，例如：
    /// - 连接池已满
    /// - 无法创建新连接
    /// - 连接获取超时
    #[error("Database pool error: {0}")]
    #[allow(dead_code)]
    Pool(String),

    /// 数据库配置错误
    ///
    /// 配置相关的错误，例如：
    /// - 配置参数无效
    /// - 必要配置缺失
    /// - 配置格式错误
    #[error("Database configuration error: {0}")]
    #[allow(dead_code)]
    Config(String),

    /// 数据库迁移错误
    ///
    /// 数据库架构迁移过程中的错误，例如：
    /// - 迁移脚本执行失败
    /// - 版本冲突
    /// - 回滚失败
    #[error("Database migration error: {0}")]
    #[allow(dead_code)]
    Migration(String),

    /// 数据库验证错误
    ///
    /// 数据验证相关的错误，例如：
    /// - 字段值不符合约束条件
    /// - 数据完整性检查失败
    #[error("Database validation error: {0}")]
    #[allow(dead_code)]
    Validation(String),

    /// IO 错误
    ///
    /// 文件操作相关的错误
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// 序列化错误
    ///
    /// JSON 数据序列化/反序列化过程中的错误
    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),
}

/// 通用结果类型
///
/// 为模块中的函数提供统一的返回类型，
/// 使用 `Error` 作为错误类型。
pub type Result<T> = std::result::Result<T, Error>;

/// 核心错误类型
///
/// 定义了框架中使用的主要错误类型，
/// 包含了所有可能出现的错误情况。
#[derive(Error, Debug)]
pub enum Error {
    /// 数据库错误
    ///
    /// 来自 SQLx 的原始数据库错误
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),

    /// 连接池错误
    ///
    /// 连接池管理相关的错误
    #[error("Pool error: {0}")]
    Pool(String),

    /// 事务错误
    ///
    /// 事务处理过程中的错误
    #[error("Transaction error: {0}")]
    Transaction(String),

    /// 查询错误
    ///
    /// SQL 查询执行过程中的错误
    #[error("Query error: {0}")]
    Query(String),

    /// 值转换错误
    ///
    /// 数据类型转换过程中的错误
    #[error("Value conversion error: {0}")]
    Conversion(String),

    /// 配置错误
    ///
    /// 配置相关的错误
    #[error("Configuration error: {0}")]
    Config(String),

    /// 其他错误
    ///
    /// 未分类的通用错误
    #[error(transparent)]
    Other(#[from] anyhow::Error),

    /// 记录未找到错误
    ///
    /// 查询结果为空时的错误
    #[error("Row not found")]
    RowNotFound,
}

impl Error {
    /// 检查是否为记录未找到错误
    ///
    /// 返回 `true` 如果错误类型为 `RowNotFound`
    pub fn is_not_found(&self) -> bool {
        matches!(self, Error::RowNotFound)
    }

    /// 检查是否为唯一约束违反错误
    ///
    /// 返回 `true` 如果错误是由唯一约束违反导致的
    pub fn is_unique_violation(&self) -> bool {
        matches!(self, Error::Database(e) if e.as_database_error()
            .map(|e| matches!(e.kind(), sqlx::error::ErrorKind::UniqueViolation))
            .unwrap_or(false))
    }

    /// 检查是否为外键约束违反错误
    ///
    /// 返回 `true` 如果错误是由外键约束违反导致的
    pub fn is_foreign_key_violation(&self) -> bool {
        matches!(self, Error::Database(e) if e.as_database_error()
            .map(|e| matches!(e.kind(), sqlx::error::ErrorKind::ForeignKeyViolation))
            .unwrap_or(false))
    }
}