wechat_backend_auth/

error.rs

use thiserror::Error;

/// 微信授权错误类型
#[derive(Error, Debug)]
pub enum WeChatError {
    /// 配置错误
    #[error("配置错误: {0}")]
    Configuration(String),

    /// 网络传输错误
    #[error("网络传输错误: {0}")]
    Transport(#[from] TransportError),

    /// 响应解析失败
    #[error("响应解析失败 - URL: {url}, 错误: {error}, 预览: {preview}")]
    ResponseParseFailed {
        url: String,
        error: String,
        preview: String,
    },

    /// 微信API通用错误
    #[error("微信API错误 (errcode: {errcode}): {errmsg}")]
    ApiError { errcode: i32, errmsg: String },

    // ===== Access Token 相关错误 =====
    /// Access Token过期或无效
    ///
    /// 错误码: 40001, 40014, 42001
    ///
    /// 解决方案:
    /// 1. 检查AppSecret是否正确
    /// 2. 使用refresh_token刷新access_token
    /// 3. 如果refresh_token也过期,需要重新授权
    #[error("Access Token已过期或无效 (errcode: {code})")]
    AccessTokenExpired { code: i32 },

    /// Access Token缺失
    ///
    /// 错误码: 41001
    ///
    /// 解决方案: 检查API调用时是否传递了access_token参数
    #[error("缺少access_token参数")]
    AccessTokenMissing,

    /// 用户修改密码导致Token失效
    ///
    /// 错误码: 42007
    ///
    /// 原因: 用户修改了微信密码,导致之前授权的所有token失效
    ///
    /// 解决方案: 引导用户重新进行授权
    #[error("用户修改密码,access_token和refresh_token已失效,需要重新授权")]
    TokenInvalidated,

    // ===== Authorization Code 相关错误 =====
    /// 无效的授权码
    ///
    /// 错误码: 40029
    ///
    /// 原因:
    /// - 授权码格式错误
    /// - 授权码不是通过微信授权流程获得
    /// - AppID与授权码不匹配
    ///
    /// 解决方案: 检查授权流程是否正确,确保使用正确的AppID
    #[error("无效的授权码")]
    InvalidCode,

    /// 授权码已被使用
    ///
    /// 错误码: 40163
    ///
    /// 原因:
    /// - 授权码(code)只能使用一次
    /// - 页面刷新或重复请求导致code被重复使用
    /// - 服务端错误导致回调接口被调用多次
    ///
    /// 解决方案:
    /// 1. 检查前端是否有重复请求
    /// 2. 确保回调接口没有抛出异常
    /// 3. 避免页面刷新时重复使用旧的code
    /// 4. 让用户重新进行授权获取新的code
    #[error("授权码已被使用(code只能使用一次,请重新授权)")]
    CodeUsed,

    /// 授权码已过期
    ///
    /// 错误码: 42003
    ///
    /// 原因: 授权码(code)的有效期为5分钟,超时后无法使用
    ///
    /// 解决方案: 引导用户重新进行授权获取新的code
    #[error("授权码已过期(有效期5分钟,请重新授权)")]
    CodeExpired,

    // ===== Refresh Token 相关错误 =====
    /// Refresh Token无效
    ///
    /// 错误码: 40030
    ///
    /// 解决方案: 引导用户重新授权
    #[error("Refresh Token无效")]
    RefreshTokenInvalid,

    /// Refresh Token已过期
    ///
    /// 错误码: 42002
    ///
    /// 原因: refresh_token的有效期为30天,超时后无法使用
    ///
    /// 解决方案: 引导用户重新进行授权
    #[error("Refresh Token已过期(有效期30天,请重新授权)")]
    RefreshTokenExpired,

    // ===== 权限和限制相关错误 =====
    /// 用户未授权该API
    ///
    /// 错误码: 50001
    ///
    /// 原因:
    /// - 授权作用域不足
    /// - 账号类型不支持该API
    /// - 未配置授权回调域名
    ///
    /// 解决方案:
    /// 1. 检查授权时的scope参数
    /// 2. 确认账号类型是否支持(如需要认证的服务号)
    /// 3. 在微信后台配置授权回调域名
    #[error("用户未授权该API,请检查授权作用域和账号权限")]
    UserUnauthorized,

    /// API调用频率超限
    ///
    /// 错误码: 45009(分钟级), 45011(日级)
    ///
    /// 解决方案:
    /// 1. 实施请求限流
    /// 2. 使用缓存减少API调用
    /// 3. 等待限制解除后重试
    #[error("API调用频率超限 (errcode: {code}): {msg}")]
    RateLimitExceeded { code: i32, msg: String },

    /// 服务器IP未在白名单中
    ///
    /// 错误码: 40164
    ///
    /// 解决方案: 在微信公众平台后台添加服务器IP到白名单
    #[error("服务器IP未在微信后台白名单中")]
    IpNotWhitelisted,

    // ===== 系统错误 =====
    /// 微信系统繁忙
    ///
    /// 错误码: -1
    ///
    /// 解决方案: 这是临时性错误,等待后重试即可
    #[error("微信系统繁忙,请稍后重试")]
    SystemBusy,

    /// 参数错误
    ///
    /// 错误码: 61451
    ///
    /// 解决方案: 检查API调用参数是否正确
    #[error("请求参数错误: {0}")]
    InvalidParameter(String),

    /// HTTP构建错误
    #[error("HTTP请求构建错误: {0}")]
    HttpBuildError(String),
}

/// 网络传输错误
#[derive(Error, Debug)]
pub enum TransportError {
    /// HTTP请求失败
    #[error("HTTP请求失败: {0}")]
    RequestFailed(String),

    /// 连接超时
    #[error("连接超时")]
    Timeout,

    /// SSL/TLS错误
    #[error("SSL/TLS错误: {0}")]
    TlsError(String),

    /// 网络连接错误
    #[error("网络连接错误: {0}")]
    ConnectionError(String),

    /// 其他传输错误
    #[error("传输错误: {0}")]
    Other(String),
}

impl From<reqwest::Error> for WeChatError {
    fn from(err: reqwest::Error) -> Self {
        if err.is_timeout() {
            WeChatError::Transport(TransportError::Timeout)
        } else if err.is_connect() {
            WeChatError::Transport(TransportError::ConnectionError(err.to_string()))
        } else if err.is_request() {
            WeChatError::Transport(TransportError::RequestFailed(err.to_string()))
        } else {
            WeChatError::Transport(TransportError::Other(err.to_string()))
        }
    }
}

/// 从微信API错误码创建对应的错误类型
///
/// 根据微信官方文档将错误码映射到具体的错误类型,便于业务层做针对性处理
///
/// # 参数
///
/// - `errcode`: 微信API返回的错误码
/// - `errmsg`: 微信API返回的错误消息
///
/// # 返回
///
/// 返回对应的 `WeChatError` 类型
pub(crate) fn from_errcode(errcode: i32, errmsg: String) -> WeChatError {
    match errcode {
        // 系统错误
        -1 => WeChatError::SystemBusy,

        // Access Token相关错误
        40001 | 40014 => WeChatError::AccessTokenExpired { code: errcode },
        41001 => WeChatError::AccessTokenMissing,
        42001 => WeChatError::AccessTokenExpired { code: errcode },
        42007 => WeChatError::TokenInvalidated,

        // Authorization Code相关错误
        40029 => WeChatError::InvalidCode,
        40163 => WeChatError::CodeUsed,
        42003 => WeChatError::CodeExpired,

        // Refresh Token相关错误
        40030 => WeChatError::RefreshTokenInvalid,
        42002 => WeChatError::RefreshTokenExpired,

        // IP白名单错误
        40164 => WeChatError::IpNotWhitelisted,

        // 权限和作用域错误
        50001 => WeChatError::UserUnauthorized,

        // 频率限制错误
        45009 | 45011 => WeChatError::RateLimitExceeded {
            code: errcode,
            msg: errmsg.clone(),
        },

        // 参数错误
        61451 => WeChatError::InvalidParameter(errmsg.clone()),

        // 其他未分类错误
        _ => WeChatError::ApiError { errcode, errmsg },
    }
}

impl WeChatError {
    /// 判断错误是否可以重试
    ///
    /// # 返回值
    ///
    /// - `true`: 错误是临时性的,可以重试
    /// - `false`: 错误需要人工介入,重试无效
    ///
    /// # 示例
    ///
    /// ```
    /// # use wechat_backend_auth::WeChatError;
    /// # fn example(error: WeChatError) {
    /// if error.is_retriable() {
    ///     // 等待后重试
    ///     println!("可以重试");
    /// } else {
    ///     println!("无法重试,需要人工处理");
    /// }
    /// # }
    /// ```
    pub fn is_retriable(&self) -> bool {
        matches!(
            self,
            WeChatError::SystemBusy
                | WeChatError::Transport(TransportError::Timeout)
                | WeChatError::Transport(TransportError::ConnectionError(_))
                | WeChatError::RateLimitExceeded { .. }
        )
    }

    /// 判断错误是否需要重新授权
    ///
    /// # 返回值
    ///
    /// - `true`: 需要引导用户重新进行微信授权
    /// - `false`: 不需要重新授权
    ///
    /// # 示例
    ///
    /// ```
    /// # use wechat_backend_auth::WeChatError;
    /// # fn example(error: WeChatError) {
    /// if error.requires_reauthorization() {
    ///     // 清除本地token缓存
    ///     // 返回授权URL给前端
    ///     println!("需要重新授权");
    /// }
    /// # }
    /// ```
    pub fn requires_reauthorization(&self) -> bool {
        matches!(
            self,
            WeChatError::CodeExpired
                | WeChatError::CodeUsed
                | WeChatError::RefreshTokenExpired
                | WeChatError::RefreshTokenInvalid
                | WeChatError::TokenInvalidated
        )
    }

    /// 判断错误是否是配置问题
    ///
    /// # 返回值
    ///
    /// - `true`: 是配置问题,需要修改配置
    /// - `false`: 不是配置问题
    ///
    /// # 示例
    ///
    /// ```
    /// # use wechat_backend_auth::WeChatError;
    /// # fn example(error: WeChatError) {
    /// if error.is_configuration_error() {
    ///     // 记录配置错误日志
    ///     // 发送告警通知
    ///     eprintln!("配置错误: {}", error);
    /// }
    /// # }
    /// ```
    pub fn is_configuration_error(&self) -> bool {
        matches!(
            self,
            WeChatError::Configuration(_)
                | WeChatError::IpNotWhitelisted
                | WeChatError::UserUnauthorized
                | WeChatError::AccessTokenMissing
        )
    }

    /// 获取错误的推荐重试延迟(秒)
    ///
    /// # 返回值
    ///
    /// - `Some(seconds)`: 建议延迟的秒数
    /// - `None`: 不建议重试
    ///
    /// # 示例
    ///
    /// ```
    /// # use wechat_backend_auth::WeChatError;
    /// # async fn example(error: WeChatError) {
    /// if let Some(delay) = error.recommended_retry_delay() {
    ///     println!("建议{}秒后重试", delay);
    ///     // tokio::time::sleep(Duration::from_secs(delay)).await;
    /// }
    /// # }
    /// ```
    pub fn recommended_retry_delay(&self) -> Option<u64> {
        match self {
            WeChatError::SystemBusy => Some(1),
            WeChatError::RateLimitExceeded { code, .. } => match code {
                45009 => Some(60),   // 分钟级限制,等待1分钟
                45011 => Some(3600), // 日级限制,等待1小时
                _ => Some(60),
            },
            WeChatError::Transport(TransportError::Timeout) => Some(2),
            WeChatError::Transport(TransportError::ConnectionError(_)) => Some(5),
            _ => None,
        }
    }
}