Skip to main content

yang_db/
error.rs

1/// 数据库错误类型
2///
3/// 标注 `#[non_exhaustive]`:未来新增变体不构成跨 crate 破坏性变更(下游 match 需
4/// 带 `_` 臂)。同 crate 内的穷举 match 不受影响。
5#[derive(Debug, thiserror::Error)]
6#[non_exhaustive]
7pub enum DbError {
8    #[error("连接错误: {0}")]
9    ConnectionError(String),
10
11    #[error("查询错误: {0}")]
12    QueryError(String),
13
14    #[error("SQL 语法错误: {0}")]
15    SqlSyntaxError(String),
16
17    #[error("约束错误: {0}")]
18    ConstraintError(String),
19
20    #[error("类型转换错误: {0}")]
21    TypeConversionError(String),
22
23    #[error("序列化错误: {0}")]
24    SerializationError(String),
25
26    #[error("反序列化错误: {0}")]
27    DeserializationError(String),
28
29    #[error("事务错误: {0}")]
30    TransactionError(String),
31
32    #[error("表不存在: {0}")]
33    TableNotFound(String),
34
35    #[error("缺少 WHERE 条件,禁止全表操作")]
36    MissingWhereClause,
37
38    // Redis 相关错误
39    #[error("Redis 连接错误: {0}")]
40    RedisConnectionError(String),
41
42    #[error("Redis 命令错误: {0}")]
43    RedisCommandError(String),
44
45    #[error("Redis 连接池错误: {0}")]
46    RedisPoolError(String),
47
48    #[error("Redis 类型转换错误: {0}")]
49    RedisTypeConversionError(String),
50
51    #[error("Redis 超时错误: {0}")]
52    RedisTimeoutError(String),
53
54    #[error("HAVING 子句需要 GROUP BY 子句")]
55    MissingGroupByClause,
56
57    /// 不支持的操作符错误,当传入的操作符不在支持集合中时返回
58    #[error("不支持的操作符: {0}")]
59    UnsupportedOperator(String),
60
61    /// 参数非法(调用方过错):批量数据列集不一致、空数据、batch_size 为 0 等。
62    ///
63    /// 与 [`DbError::SerializationError`] 区分——后者专表「(反)序列化失败」,
64    /// 此变体专表「入参本身不合法」,便于调用方按变体精确分流(DB-14)。
65    #[error("参数非法: {0}")]
66    InvalidArgument(String),
67
68    #[error("未知错误: {0}")]
69    Unknown(String),
70}
71
72/// 数据库错误的引擎级分类(与具体 HTTP/传输层无关)。
73///
74/// 用于下游统一适配(弹性重试、错误上报分桶)。`Transient` 表示瞬时故障、可重试;
75/// 其余为确定性错误,重试无益。
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77#[non_exhaustive]
78pub enum DbErrorCategory {
79    /// 调用方过错(SQL 语法、缺 WHERE/GROUP BY、不支持的操作符、参数非法、(反)序列化)
80    Client,
81    /// 约束冲突(唯一键/外键/非空/检查)
82    Conflict,
83    /// 资源不存在(表不存在)
84    NotFound,
85    /// 瞬时故障(连接/超时/连接池),可重试
86    Transient,
87    /// 服务端/未知错误
88    Server,
89}
90
91impl DbError {
92    /// 稳定错误码(8xxxxx 段,独立于 yang-base 的 BaseError 码命名空间)。
93    ///
94    /// 与 [`DbError::category`] 同源维护;新增变体需同步补码。
95    pub fn code(&self) -> u32 {
96        match self {
97            DbError::ConnectionError(_) => 800001,
98            DbError::QueryError(_) => 800002,
99            DbError::SqlSyntaxError(_) => 800003,
100            DbError::ConstraintError(_) => 800004,
101            DbError::TypeConversionError(_) => 800005,
102            DbError::SerializationError(_) => 800006,
103            DbError::DeserializationError(_) => 800007,
104            DbError::TransactionError(_) => 800008,
105            DbError::TableNotFound(_) => 800009,
106            DbError::MissingWhereClause => 800010,
107            DbError::RedisConnectionError(_) => 810001,
108            DbError::RedisCommandError(_) => 810002,
109            DbError::RedisPoolError(_) => 810003,
110            DbError::RedisTypeConversionError(_) => 810004,
111            DbError::RedisTimeoutError(_) => 810005,
112            DbError::MissingGroupByClause => 800011,
113            DbError::UnsupportedOperator(_) => 800012,
114            DbError::InvalidArgument(_) => 800013,
115            DbError::Unknown(_) => 899999,
116        }
117    }
118
119    /// 引擎级分类。是 [`DbError::is_retryable`] 的单一事实源。
120    pub fn category(&self) -> DbErrorCategory {
121        use DbErrorCategory as C;
122        match self {
123            // 瞬时:连接/超时/连接池 —— 可重试
124            DbError::ConnectionError(_)
125            | DbError::RedisConnectionError(_)
126            | DbError::RedisPoolError(_)
127            | DbError::RedisTimeoutError(_) => C::Transient,
128            // 约束冲突
129            DbError::ConstraintError(_) => C::Conflict,
130            // 不存在
131            DbError::TableNotFound(_) => C::NotFound,
132            // 调用方过错:语法/缺子句/不支持操作符/(反)序列化/类型转换
133            DbError::SqlSyntaxError(_)
134            | DbError::MissingWhereClause
135            | DbError::MissingGroupByClause
136            | DbError::UnsupportedOperator(_)
137            | DbError::InvalidArgument(_)
138            | DbError::SerializationError(_)
139            | DbError::DeserializationError(_)
140            | DbError::TypeConversionError(_)
141            | DbError::RedisTypeConversionError(_) => C::Client,
142            // 服务端/未知:查询错误、Redis 命令错误、未知
143            DbError::QueryError(_)
144            | DbError::TransactionError(_)
145            | DbError::RedisCommandError(_)
146            | DbError::Unknown(_) => C::Server,
147        }
148    }
149
150    /// 是否为可重试的瞬时错误(等价 `category() == Transient`)。
151    pub fn is_retryable(&self) -> bool {
152        self.category() == DbErrorCategory::Transient
153    }
154}
155
156/// 从 sqlx::Error 转换为 DbError
157#[cfg(any(feature = "mysql", feature = "postgres"))]
158impl From<sqlx::Error> for DbError {
159    fn from(err: sqlx::Error) -> Self {
160        match err {
161            sqlx::Error::Configuration(_) => DbError::ConnectionError(format!("配置错误: {}", err)),
162            sqlx::Error::Database(db_err) => {
163                let code = db_err.code().unwrap_or_default();
164                let message = db_err.message();
165
166                // 数据库错误码映射(同时覆盖 MySQL 与 PostgreSQL)
167                //
168                // MySQL 使用 ANSI SQLSTATE 子集,PostgreSQL 使用完整 SQLSTATE(5 位)。
169                // 两者在约束冲突 / 表不存在 / 语法错误上的常见码不同,这里统一映射,
170                // 使 yang-db 的 MySQL 与 PostgreSQL 后端返回一致的 DbError 语义。
171                match code.as_ref() {
172                    // 约束冲突:MySQL 23000;PostgreSQL 类 23xxx(唯一/外键/非空/检查)
173                    "23000" | "23001" | "23502" | "23503" | "23505" | "23514" => {
174                        DbError::ConstraintError(message.to_string())
175                    }
176                    // 表/视图不存在:MySQL 42S02;PostgreSQL 42P01
177                    "42S02" | "42P01" => DbError::TableNotFound(message.to_string()),
178                    // 语法/访问规则错误:MySQL 42000;PostgreSQL 42601(语法) / 42703(列不存在) / 42P02
179                    "42000" | "42601" | "42703" | "42P02" => {
180                        DbError::SqlSyntaxError(message.to_string())
181                    }
182                    _ => DbError::QueryError(format!("数据库错误 [{}]: {}", code, message)),
183                }
184            }
185            sqlx::Error::Io(_) => DbError::ConnectionError(format!("IO 错误: {}", err)),
186            sqlx::Error::Tls(_) => DbError::ConnectionError(format!("TLS 错误: {}", err)),
187            sqlx::Error::Protocol(_) => DbError::QueryError(format!("协议错误: {}", err)),
188            sqlx::Error::RowNotFound => DbError::QueryError("未找到记录".to_string()),
189            sqlx::Error::TypeNotFound { type_name } => {
190                DbError::TypeConversionError(format!("类型未找到: {}", type_name))
191            }
192            sqlx::Error::ColumnIndexOutOfBounds { index, len } => {
193                DbError::QueryError(format!("列索引越界: {} (总列数: {})", index, len))
194            }
195            sqlx::Error::ColumnNotFound(col) => DbError::QueryError(format!("列不存在: {}", col)),
196            sqlx::Error::ColumnDecode { index, source } => {
197                DbError::TypeConversionError(format!("列 {} 解码失败: {}", index, source))
198            }
199            sqlx::Error::Decode(source) => {
200                DbError::DeserializationError(format!("解码失败: {}", source))
201            }
202            sqlx::Error::PoolTimedOut => DbError::ConnectionError("连接池超时".to_string()),
203            sqlx::Error::PoolClosed => DbError::ConnectionError("连接池已关闭".to_string()),
204            sqlx::Error::WorkerCrashed => DbError::ConnectionError("工作线程崩溃".to_string()),
205            _ => DbError::Unknown(format!("未知错误: {}", err)),
206        }
207    }
208}
209
210/// 从 redis::RedisError 转换为 DbError
211#[cfg(feature = "redis")]
212impl From<redis::RedisError> for DbError {
213    fn from(err: redis::RedisError) -> Self {
214        // 用协议层稳定 API 分类,而非脆弱的 Display 子串匹配:
215        // - 超时优先(is_timeout 涵盖连接超时与响应超时)
216        // - 连接断开 / IO / 连接拒绝 → 连接错误
217        // - 类型不匹配(TypeError)→ 类型转换错误
218        // - 其余 → 命令错误(兜底)
219        use redis::ErrorKind;
220        if err.is_timeout() {
221            DbError::RedisTimeoutError(format!("超时错误: {}", err))
222        } else if err.is_connection_dropped() || err.is_io_error() || err.is_connection_refusal() {
223            DbError::RedisConnectionError(format!("连接错误: {}", err))
224        } else if matches!(err.kind(), ErrorKind::TypeError) {
225            DbError::RedisTypeConversionError(format!("类型错误: {}", err))
226        } else {
227            DbError::RedisCommandError(format!("Redis 错误: {}", err))
228        }
229    }
230}
231
232/// 从 deadpool_redis::PoolError 转换为 DbError
233#[cfg(feature = "redis")]
234impl From<deadpool_redis::PoolError> for DbError {
235    fn from(err: deadpool_redis::PoolError) -> Self {
236        match err {
237            deadpool_redis::PoolError::Timeout(_) => {
238                DbError::RedisTimeoutError("连接池获取连接超时".to_string())
239            }
240            deadpool_redis::PoolError::Closed => {
241                DbError::RedisPoolError("连接池已关闭".to_string())
242            }
243            deadpool_redis::PoolError::NoRuntimeSpecified => {
244                DbError::RedisPoolError("未指定运行时".to_string())
245            }
246            deadpool_redis::PoolError::PostCreateHook(source) => {
247                DbError::RedisPoolError(format!("连接创建后钩子失败: {:?}", source))
248            }
249            deadpool_redis::PoolError::Backend(err) => DbError::from(err),
250        }
251    }
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    #[test]
259    fn test_error_display_chinese() {
260        // 测试所有 19 个错误变体的中文消息
261        let errors = vec![
262            DbError::ConnectionError("测试".to_string()),
263            DbError::QueryError("测试".to_string()),
264            DbError::SqlSyntaxError("测试".to_string()),
265            DbError::ConstraintError("测试".to_string()),
266            DbError::TypeConversionError("测试".to_string()),
267            DbError::SerializationError("测试".to_string()),
268            DbError::DeserializationError("测试".to_string()),
269            DbError::TransactionError("测试".to_string()),
270            DbError::TableNotFound("测试".to_string()),
271            DbError::MissingWhereClause,
272            DbError::RedisConnectionError("测试".to_string()),
273            DbError::RedisCommandError("测试".to_string()),
274            DbError::RedisPoolError("测试".to_string()),
275            DbError::RedisTypeConversionError("测试".to_string()),
276            DbError::RedisTimeoutError("测试".to_string()),
277            DbError::MissingGroupByClause,
278            DbError::UnsupportedOperator("测试".to_string()),
279            DbError::InvalidArgument("测试".to_string()),
280            DbError::Unknown("测试".to_string()),
281        ];
282
283        for error in errors {
284            let msg = format!("{}", error);
285            // 验证错误消息包含中文字符
286            let has_chinese = msg.chars().any(|c| matches!(c, '\u{4e00}'..='\u{9fff}'));
287            assert!(has_chinese, "错误消息应该包含中文: {}", msg);
288        }
289    }
290
291    #[test]
292    fn test_connection_error() {
293        let err = DbError::ConnectionError("无法连接到数据库".to_string());
294        assert_eq!(format!("{}", err), "连接错误: 无法连接到数据库");
295    }
296
297    #[test]
298    fn test_query_error() {
299        let err = DbError::QueryError("查询超时".to_string());
300        assert_eq!(format!("{}", err), "查询错误: 查询超时");
301    }
302
303    #[test]
304    fn test_sql_syntax_error() {
305        let err = DbError::SqlSyntaxError("语法错误".to_string());
306        assert_eq!(format!("{}", err), "SQL 语法错误: 语法错误");
307    }
308
309    #[test]
310    fn test_constraint_error() {
311        let err = DbError::ConstraintError("主键冲突".to_string());
312        assert_eq!(format!("{}", err), "约束错误: 主键冲突");
313    }
314
315    #[test]
316    fn test_type_conversion_error() {
317        let err = DbError::TypeConversionError("无法转换类型".to_string());
318        assert_eq!(format!("{}", err), "类型转换错误: 无法转换类型");
319    }
320
321    /// 对抗性验证:Redis 类型错误必须精确归类,普通响应错误不能混入类型转换错误。
322    #[test]
323    #[cfg(feature = "redis")]
324    fn test_redis_error_classification_distinguishes_type_and_command_errors() {
325        let type_error = redis::RedisError::from((redis::ErrorKind::TypeError, "返回值类型不匹配"));
326        let response_error =
327            redis::RedisError::from((redis::ErrorKind::ResponseError, "命令执行失败"));
328
329        assert!(matches!(
330            DbError::from(type_error),
331            DbError::RedisTypeConversionError(_)
332        ));
333        assert!(matches!(
334            DbError::from(response_error),
335            DbError::RedisCommandError(_)
336        ));
337    }
338
339    #[test]
340    fn test_serialization_error() {
341        let err = DbError::SerializationError("序列化失败".to_string());
342        assert_eq!(format!("{}", err), "序列化错误: 序列化失败");
343    }
344
345    #[test]
346    fn test_deserialization_error() {
347        let err = DbError::DeserializationError("反序列化失败".to_string());
348        assert_eq!(format!("{}", err), "反序列化错误: 反序列化失败");
349    }
350
351    #[test]
352    fn test_transaction_error() {
353        let err = DbError::TransactionError("事务已提交".to_string());
354        assert_eq!(format!("{}", err), "事务错误: 事务已提交");
355    }
356
357    #[test]
358    fn test_table_not_found() {
359        let err = DbError::TableNotFound("users".to_string());
360        assert_eq!(format!("{}", err), "表不存在: users");
361    }
362
363    #[test]
364    fn test_missing_where_clause() {
365        let err = DbError::MissingWhereClause;
366        assert_eq!(format!("{}", err), "缺少 WHERE 条件,禁止全表操作");
367    }
368
369    #[test]
370    fn test_unknown_error() {
371        let err = DbError::Unknown("未知问题".to_string());
372        assert_eq!(format!("{}", err), "未知错误: 未知问题");
373    }
374
375    #[test]
376    fn test_error_implements_std_error() {
377        // 验证 DbError 实现了 std::error::Error trait
378        let err = DbError::QueryError("测试".to_string());
379        let _: &dyn std::error::Error = &err;
380    }
381
382    // Redis 错误测试
383    #[test]
384    fn test_redis_connection_error() {
385        let err = DbError::RedisConnectionError("连接失败".to_string());
386        assert_eq!(format!("{}", err), "Redis 连接错误: 连接失败");
387    }
388
389    #[test]
390    fn test_redis_command_error() {
391        let err = DbError::RedisCommandError("命令执行失败".to_string());
392        assert_eq!(format!("{}", err), "Redis 命令错误: 命令执行失败");
393    }
394
395    #[test]
396    fn test_redis_pool_error() {
397        let err = DbError::RedisPoolError("连接池错误".to_string());
398        assert_eq!(format!("{}", err), "Redis 连接池错误: 连接池错误");
399    }
400
401    #[test]
402    fn test_redis_type_conversion_error() {
403        let err = DbError::RedisTypeConversionError("类型转换失败".to_string());
404        assert_eq!(format!("{}", err), "Redis 类型转换错误: 类型转换失败");
405    }
406
407    #[test]
408    fn test_redis_timeout_error() {
409        let err = DbError::RedisTimeoutError("操作超时".to_string());
410        assert_eq!(format!("{}", err), "Redis 超时错误: 操作超时");
411    }
412
413    #[test]
414    #[cfg(feature = "redis")]
415    fn test_pool_error_conversion() {
416        // 测试 deadpool_redis::PoolError 转换
417        let pool_err = deadpool_redis::PoolError::Closed;
418        let db_err: DbError = pool_err.into();
419        assert!(matches!(db_err, DbError::RedisPoolError(_)));
420    }
421
422    // 验证需求: 4.4 — UnsupportedOperator 变体错误消息格式测试
423    #[test]
424    fn test_unsupported_operator_error_message() {
425        // 验证错误消息格式为 "不支持的操作符: {op}"
426        let op = "BETWEEN";
427        let err = DbError::UnsupportedOperator(op.to_string());
428        assert_eq!(format!("{}", err), "不支持的操作符: BETWEEN");
429    }
430
431    #[test]
432    fn test_unsupported_operator_empty_string() {
433        // 验证空字符串操作符的错误消息格式
434        let err = DbError::UnsupportedOperator(String::new());
435        assert_eq!(format!("{}", err), "不支持的操作符: ");
436    }
437
438    #[test]
439    fn test_unsupported_operator_special_chars() {
440        // 验证包含特殊字符的操作符错误消息格式
441        let err = DbError::UnsupportedOperator("<>".to_string());
442        assert_eq!(format!("{}", err), "不支持的操作符: <>");
443    }
444
445    #[test]
446    fn test_unsupported_operator_implements_std_error() {
447        // 验证 UnsupportedOperator 变体实现了 std::error::Error trait
448        let err = DbError::UnsupportedOperator("IN".to_string());
449        let _: &dyn std::error::Error = &err;
450    }
451
452    #[test]
453    fn test_unsupported_operator_message_contains_chinese() {
454        // 验证错误消息包含中文字符("不支持的操作符")
455        let err = DbError::UnsupportedOperator("XOR".to_string());
456        let msg = format!("{}", err);
457        let has_chinese = msg.chars().any(|c| matches!(c, '\u{4e00}'..='\u{9fff}'));
458        assert!(has_chinese, "错误消息应该包含中文: {}", msg);
459    }
460
461    /// DB-7:category() 覆盖全部 19 个变体
462    #[test]
463    fn test_db_error_category_coverage() {
464        use super::DbErrorCategory as C;
465        // Transient:连接/超时/连接池
466        assert_eq!(
467            DbError::ConnectionError("c".into()).category(),
468            C::Transient
469        );
470        assert_eq!(
471            DbError::RedisConnectionError("c".into()).category(),
472            C::Transient
473        );
474        assert_eq!(DbError::RedisPoolError("p".into()).category(), C::Transient);
475        assert_eq!(
476            DbError::RedisTimeoutError("t".into()).category(),
477            C::Transient
478        );
479        // Conflict:约束冲突
480        assert_eq!(DbError::ConstraintError("c".into()).category(), C::Conflict);
481        // NotFound:表不存在
482        assert_eq!(DbError::TableNotFound("t".into()).category(), C::NotFound);
483        // Client:语法/缺子句/不支持操作符/参数非法/类型转换/(反)序列化/Redis类型转换
484        assert_eq!(DbError::SqlSyntaxError("s".into()).category(), C::Client);
485        assert_eq!(DbError::MissingWhereClause.category(), C::Client);
486        assert_eq!(DbError::MissingGroupByClause.category(), C::Client);
487        assert_eq!(
488            DbError::UnsupportedOperator("o".into()).category(),
489            C::Client
490        );
491        assert_eq!(DbError::InvalidArgument("a".into()).category(), C::Client);
492        assert_eq!(
493            DbError::TypeConversionError("t".into()).category(),
494            C::Client
495        );
496        assert_eq!(
497            DbError::SerializationError("s".into()).category(),
498            C::Client
499        );
500        assert_eq!(
501            DbError::DeserializationError("d".into()).category(),
502            C::Client
503        );
504        assert_eq!(
505            DbError::RedisTypeConversionError("t".into()).category(),
506            C::Client
507        );
508        // Server:查询错误/事务错误/Redis命令错误/未知
509        assert_eq!(DbError::QueryError("q".into()).category(), C::Server);
510        assert_eq!(DbError::TransactionError("t".into()).category(), C::Server);
511        assert_eq!(DbError::RedisCommandError("c".into()).category(), C::Server);
512        assert_eq!(DbError::Unknown("u".into()).category(), C::Server);
513    }
514
515    /// DB-7:is_retryable = (category == Transient)
516    #[test]
517    fn test_db_error_is_retryable() {
518        assert!(DbError::ConnectionError("c".into()).is_retryable());
519        assert!(DbError::RedisTimeoutError("t".into()).is_retryable());
520        assert!(!DbError::QueryError("q".into()).is_retryable());
521        assert!(!DbError::MissingWhereClause.is_retryable());
522        assert!(!DbError::ConstraintError("c".into()).is_retryable());
523    }
524
525    /// DB-7:code() 唯一性(19 个变体均为独立码段)
526    #[test]
527    fn test_db_error_code_unique() {
528        let codes: Vec<u32> = vec![
529            DbError::ConnectionError("".into()).code(),
530            DbError::QueryError("".into()).code(),
531            DbError::SqlSyntaxError("".into()).code(),
532            DbError::ConstraintError("".into()).code(),
533            DbError::TypeConversionError("".into()).code(),
534            DbError::SerializationError("".into()).code(),
535            DbError::DeserializationError("".into()).code(),
536            DbError::TransactionError("".into()).code(),
537            DbError::TableNotFound("".into()).code(),
538            DbError::MissingWhereClause.code(),
539            DbError::RedisConnectionError("".into()).code(),
540            DbError::RedisCommandError("".into()).code(),
541            DbError::RedisPoolError("".into()).code(),
542            DbError::RedisTypeConversionError("".into()).code(),
543            DbError::RedisTimeoutError("".into()).code(),
544            DbError::MissingGroupByClause.code(),
545            DbError::UnsupportedOperator("".into()).code(),
546            DbError::InvalidArgument("".into()).code(),
547            DbError::Unknown("".into()).code(),
548        ];
549        let mut sorted = codes.clone();
550        sorted.sort();
551        sorted.dedup();
552        assert_eq!(codes.len(), sorted.len(), "19 个变体的 code 应全部唯一");
553        // 所有码在 8xxxxx 段
554        for &c in &codes {
555            assert!((800000..900000).contains(&c), "code {} 不在 8xxxxx 段", c);
556        }
557    }
558}