1#[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 #[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 #[error("不支持的操作符: {0}")]
59 UnsupportedOperator(String),
60
61 #[error("参数非法: {0}")]
66 InvalidArgument(String),
67
68 #[error("未知错误: {0}")]
69 Unknown(String),
70}
71
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77#[non_exhaustive]
78pub enum DbErrorCategory {
79 Client,
81 Conflict,
83 NotFound,
85 Transient,
87 Server,
89}
90
91impl DbError {
92 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 pub fn category(&self) -> DbErrorCategory {
121 use DbErrorCategory as C;
122 match self {
123 DbError::ConnectionError(_)
125 | DbError::RedisConnectionError(_)
126 | DbError::RedisPoolError(_)
127 | DbError::RedisTimeoutError(_) => C::Transient,
128 DbError::ConstraintError(_) => C::Conflict,
130 DbError::TableNotFound(_) => C::NotFound,
132 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 DbError::QueryError(_)
144 | DbError::TransactionError(_)
145 | DbError::RedisCommandError(_)
146 | DbError::Unknown(_) => C::Server,
147 }
148 }
149
150 pub fn is_retryable(&self) -> bool {
152 self.category() == DbErrorCategory::Transient
153 }
154}
155
156#[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 match code.as_ref() {
172 "23000" | "23001" | "23502" | "23503" | "23505" | "23514" => {
174 DbError::ConstraintError(message.to_string())
175 }
176 "42S02" | "42P01" => DbError::TableNotFound(message.to_string()),
178 "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#[cfg(feature = "redis")]
212impl From<redis::RedisError> for DbError {
213 fn from(err: redis::RedisError) -> Self {
214 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#[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 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 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 #[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 let err = DbError::QueryError("测试".to_string());
379 let _: &dyn std::error::Error = &err;
380 }
381
382 #[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 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 #[test]
424 fn test_unsupported_operator_error_message() {
425 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 let err = DbError::UnsupportedOperator(String::new());
435 assert_eq!(format!("{}", err), "不支持的操作符: ");
436 }
437
438 #[test]
439 fn test_unsupported_operator_special_chars() {
440 let err = DbError::UnsupportedOperator("<>".to_string());
442 assert_eq!(format!("{}", err), "不支持的操作符: <>");
443 }
444
445 #[test]
446 fn test_unsupported_operator_implements_std_error() {
447 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 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 #[test]
463 fn test_db_error_category_coverage() {
464 use super::DbErrorCategory as C;
465 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 assert_eq!(DbError::ConstraintError("c".into()).category(), C::Conflict);
481 assert_eq!(DbError::TableNotFound("t".into()).category(), C::NotFound);
483 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 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 #[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 #[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 for &c in &codes {
555 assert!((800000..900000).contains(&c), "code {} 不在 8xxxxx 段", c);
556 }
557 }
558}