Rust 2026 经验谈 - 错误处理在库与应用中的分层设计

1
use thiserror::Error;
2

3
#[derive(Error, Debug)]
4
#[non_exhaustive]
5
pub enum DatabaseError {
6
    #[error("connection failed: {0}")]
7
    Connection(String),
8

9
    #[error("query execution failed: {0}")]
10
    Query(String),
11

12
    #[error("timeout after {0:?}")]
13
    Timeout(std::time::Duration),
14

15
    // 新变体可以随时添加，不会破坏下游的 match
16
}

1
#[derive(Error, Debug)]
2
#[non_exhaustive]
3
pub enum CacheError {
4
    #[error("backend connection failed: {details}")]
5
    ConnectionFailed {
6
        details: String,
7
        #[source]
8
        source: Box<dyn std::error::Error + Send + Sync>,
9
    },
10

11
    #[error("serialization failed for key `{key}`: {reason}")]
12
    SerializationFailed {
13
        key: String,
14
        reason: String,
15
    },
16

17
    #[error("key `{0}` not found")]
18
    NotFound(String),
19
}
20

21
impl CacheError {
22
    pub fn from_redis(err: redis::RedisError) -> Self {
23
        CacheError::ConnectionFailed {
24
            details: err.to_string(),
25
            source: err.into(),
26
        }
27
    }
28
}

1
// 反模式：按底层事件划分
2
pub enum HttpError {
3
    DnsResolutionFailed,
4
    TcpConnectionRefused,
5
    TlsHandshakeFailed,
6
    HttpResponse500,
7
    HttpResponse429,
8
}
9

10
// 正确：按调用者需要的处理策略划分
11
pub enum HttpError {
12
    #[error("connection failed: {0}")]
13
    ConnectionFailed(String),      // 重试
14

15
    #[error("rate limited, retry after {0:?}")]
16
    RateLimited(std::time::Duration),  // 等待后重试
17

18
    #[error("server error: {0}")]
19
    ServerError(u16),              // 5xx，可能重试
20

21
    #[error("client error: {0}")]
22
    ClientError(u16),              // 4xx，不应重试
23
}

1
use anyhow::{Context, Result};
2

3
fn run_app() -> Result<()> {
4
    let config = load_config()
5
        .context("failed to load configuration")?;
6

7
    let db = connect_db(&config.db_url)
8
        .context("failed to connect to database")?;
9

10
    let cache = connect_cache(&config.cache_url)
11
        .context("failed to connect to cache")?;
12

13
    serve(db, cache)
14
        .context("server failed")?;
15

16
    Ok(())
17
}

1
use anyhow::Error;
2

3
fn display_for_cli(err: &Error) -> ! {
4
    eprintln!("Error: {}", err);
5
    // 只显示最外层消息，不暴露内部细节
6
    std::process::exit(1)
7
}
8

9
fn display_for_http_api(err: &Error) -> HttpResponse {
10
    // 结构化 JSON，包含错误码
11
    let code = classify_error(err);
12
    HttpResponse::json(serde_json::json!({
13
        "error": {
14
            "code": code,
15
            "message": err.to_string(),
16
            // 生产环境不暴露 backtrace
17
        }
18
    })).with_status(code.http_status())
19
}
20

21
fn display_for_log(err: &Error) {
22
    // 完整的 error chain + backtrace
23
    tracing::error!(
24
        error = %err,
25
        error_chain = ?err.chain().map(|e| e.to_string()).collect::<Vec<_>>(),
26
        backtrace = ?err.backtrace(),
27
        "operation failed"
28
    );
29
}

1
#[derive(Debug, Clone, Copy)]
2
enum ErrorClass {
3
    Config,     // 配置错误，无法启动
4
    Network,    // 网络错误，可重试
5
    Database,   // 数据库错误，可能重试
6
    Logic,      // 业务逻辑错误，不可重试
7
    Internal,   // 内部错误，需要告警
8
}
9

10
impl ErrorClass {
11
    fn http_status(self) -> u16 {
12
        match self {
13
            ErrorClass::Config => 500,
14
            ErrorClass::Network => 503,
15
            ErrorClass::Database => 503,
16
            ErrorClass::Logic => 400,
17
            ErrorClass::Internal => 500,
18
        }
19
    }
20

21
    fn is_retryable(self) -> bool {
22
        matches!(self, ErrorClass::Network | ErrorClass::Database)
23
    }
24
}
25

26
fn classify_error(err: &anyhow::Error) -> ErrorClass {
27
    if err.is::<io::Error>() {
28
        ErrorClass::Network
29
    } else if err.is::<DatabaseError>() {
30
        ErrorClass::Database
31
    } else {
32
        ErrorClass::Internal
33
    }
34
}

1
use tracing::{instrument, error, info, Span};
2
use anyhow::{Context, Result};
3

4
#[instrument(skip(db), fields(db_id = %db.id()))]
5
async fn process_order(db: &Database, order: Order) -> Result<()> {
6
    info!("processing order");
7

8
    let inventory = db.get_inventory(&order.item_id)
9
        .await
10
        .context("failed to fetch inventory")?;
11

12
    if inventory.quantity < order.quantity {
13
        // 错误被当前 span 上下文化
14
        error!(
15
            available = inventory.quantity,
16
            requested = order.quantity,
17
            "insufficient inventory"
18
        );
19
        return Err(anyhow::anyhow!("insufficient inventory"));
20
    }
21

22
    db.decrement_inventory(&order.item_id, order.quantity)
23
        .await
24
        .context("failed to update inventory")?;
25

26
    Ok(())
27
}

1
// 错误：span 在错误返回后才记录
2
async fn bad_example() -> Result<()> {
3
    let span = tracing::info_span!("operation");
4
    let _enter = span.enter();
5

6
    let result = risky_operation().await; // _enter 在这里还存活
7
    // _enter drop → span 退出
8

9
    if let Err(e) = result {
10
        // 此时已经不在 span 中了！错误日志丢失上下文
11
        tracing::error!(error = %e, "failed");
12
    }
13
    result
14
}
15

16
// 正确：使用 instrument 或 in_span
17
async fn good_example() -> Result<()> {
18
    risky_operation()
19
        .instrument(tracing::info_span!("operation"))
20
        .await
21
        .map_err(|e| {
22
            // 错误仍在 span 内被记录
23
            tracing::error!(error = %e, "failed");
24
            e
25
        })
26
}

1
use tracing::instrument;
2
use anyhow::{Context, Result};
3

4
#[instrument(err)]  // err 属性：自动记录返回的 Err
5
async fn fetch_user(id: u64) -> Result<User> {
6
    let resp = http_client
7
        .get(&format!("/users/{}", id))
8
        .send()
9
        .await
10
        .context("HTTP request failed")?;  // context 附加位置信息
11

12
    let user: User = resp.json().await
13
        .context("JSON deserialization failed")?;
14

15
    Ok(user)
16
}

1
// 反模式：俄罗斯套娃
2
pub enum AppError {
3
    Db(DbError),
4
    Cache(CacheError),
5
    Auth(AuthError),
6
}
7

8
pub enum DbError {
9
    Pool(PoolError),
10
    Query(QueryError),
11
}
12

13
pub enum PoolError {
14
    Timeout(TimeoutError),
15
    Connection(ConnectionError),
16
}
17
// 调用者需要 match AppError::Db(DbError::Pool(PoolError::Timeout(...)))