用途:在 Axum(Rust)中正确处理错误。核心规则是处理器的返回类型就是错误通道,应返回 Result<T, E>(E: IntoResponse),而不是用 panic、unwrap 或 expect 向客户端报错。Axum 在 tower::Service 层的错误类型为 Infallible,Err(E) 会被转成合法 HTTP 响应。
主要能力与模式:
- 返回 Result:可用 StatusCode 或 (StatusCode, String) 作为简单错误类型。
- 自定义 AppError 枚举:由枚举、IntoResponse 实现、每个来源错误的 From 实现三部分组成,? 通过 From 自动转换,并把内部错误存入 response.extensions 供日志层读取、不泄漏给客户端。
- thiserror:用 #[from] 生成 From、#[error] 生成 Display,按变体映射状态码(404/422/500 等)。
- anyhow 新类型包装:因孤儿规则不能为 anyhow::Error 直接实现 IntoResponse,需本地 newtype 加泛型 From,结果固定为 500,仅用于无需区分状态码时。
- 组合模式:thiserror 枚举加 #[error(transparent)] #[from] anyhow::Error 的兜底变体,是常见生产形态。
- HandleError / HandleErrorLayer:仅用于可失败的 tower::Service 中间件(如 TimeoutLayer),需放在受保护层之上,普通处理器不需要。
所需 crate:axum(0.7 或 0.8,相关 API 行为一致)、serde、thiserror、anyhow、tower,按需添加。
限制与注意:不要在处理器中 unwrap/expect/panic;不要为 anyhow::Error 直接实现 IntoResponse;不要向客户端序列化内部错误的 Display 文本;缺少 From 实现会导致 ? 报 trait 未实现;错误文本与日志处理策略见技能内参考文档。本介绍未提供更多具体 API 签名与完整示例,详见技能资料。