Rust错误处理体系设计：rust-web-app如何从数据库层到HTTP响应层层传递错误

Rust错误处理体系设计：rust-web-app如何从数据库层到HTTP响应层层传递错误

【免费下载链接】rust-web-appCode template for a production Web Application using Axum: The AwesomeApp Blueprint for Professional Web Development.项目地址: https://gitcode.com/gh_mirrors/ru/rust-web-app

rust-web-app是一个基于Axum的生产级 Rust Web 应用脚手架（Rust Web 应用蓝图），它最值得学习的设计之一就是Rust 错误处理体系：每个 crate 定义自己的错误枚举，错误通过?算子从数据库层一路传递到HTTP 响应层，最终被统一转换成带正确状态码的 JSON 错误响应。本文带你梳理这套从底层到上层的错误传递链路，掌握Rust 错误传播、错误枚举分层设计的实战方法 🧭

1. 为什么需要分层错误体系

Rust 的哲学是"错误也是返回值"：用Result<T, E>显式处理错误，而不是靠异常或日志猜测。但多 crate 的 Web 项目会面临两个难题：

• 底层错误信息太"技术"：数据库驱动报出的原始错误（如 Postgres 唯一约束冲突码23505）直接暴露给前端并不合适；
• 错误语义要逐层增强：数据库层的sqlx::Error到了业务层应该变成"用户名已存在"，到了 HTTP 层应该变成400 + 友好提示。

rust-web-app的解法是：每层一个错误枚举（Error enum），用#[from]自动包装下一层的错误，用?向上冒泡，最后在最外层统一翻译给客户端。

2. 总体架构：5 层错误枚举各管一段

整个错误传递链路横跨 5 个 crate，每一层都有独立的错误文件：

层级	Crate	错误定义位置	职责
数据库层	lib-core(dbx)	crates/libs/lib-core/src/model/store/dbx/error.rs	封装sqlx错误与事务错误
模型层	lib-core(model)	crates/libs/lib-core/src/model/error.rs	业务错误 + 数据库错误的"翻译器"
认证层	lib-auth	crates/libs/lib-auth/src/pwd/error.rs	密码哈希/校验错误
RPC 层	lib-rpc-core	crates/libs/lib-rpc-core/src/error.rs	包装模型错误，接入 JSON-RPC 路由
Web 层	lib-web	crates/libs/lib-web/src/error.rs	汇总所有错误，映射为 HTTP 状态码

传递方式非常朴素：上层枚举通过derive_more的#[from]派生自动转换。例如 RPC 层错误只写了两个变体：

#[derive(Debug, From, Serialize, RpcHandlerError)] pub enum Error { #[from] Model(lib_core::model::Error), #[from] SerdeJson(serde_json::Error), }

从此模型层的任何错误都可以用?直接"冒泡"进 RPC 层，无需手写match转换，这就是分层枚举 +Fromtrait 的组合威力 ⚡

3. 数据库层：Dbx 对 sqlx 的第一道封装

数据访问封装在Dbx结构体中（crates/libs/lib-core/src/model/store/dbx/mod.rs），它持有连接池并支持按需开启数据库事务（begin_txn系列方法）。

对应的错误枚举 dbx/error.rs 设计得很克制——只有两类：

• 事务错误：TxnCantCommitNoOpenTxn（没有开启事务却要提交）、CannotBeginTxnWithTxnFalse（配置了非事务模式却尝试开事务）等，把事务生命周期问题变成可枚举、可判断的类型；
• 驱动错误：Sqlx(sqlx::Error)，用#[from]自动包装，并通过DisplayFromStr处理序列化（sqlx::Error本身不可直接序列化）。

这一层的意义是：模型层从此只依赖dbx::Error，而不是到处散落sqlx::Error的分支处理。

4. 模型层：把"数据库黑话"翻译成业务错误

模型层错误枚举（model/error.rs）是整套体系的"翻译中枢"。它包含三类变体：

1. 业务错误：EntityNotFound { entity, id }、UserAlreadyExists { username }、ListLimitOverMax等，直接描述业务事实；
2. 下层错误包装：#[from] Dbx(dbx::Error)、#[from] Pwd(pwd::Error)，让数据库和密码模块的错误自动升级；
3. 外部库错误：SeaQuery、ModqlIntoSea等 SQL 构建与查询过滤库的错误。

唯一约束冲突的"精准化"技巧

最有意思的设计是resolve_unique_violation（model/error.rs#L55-L73）：

// "23505" => postgresql "unique violation" Some((Some(Cow::Borrowed("23505")), Some(table), Some(constraint))) => { ... }

当数据库报出原始的唯一约束冲突（Postgres 错误码23505）时，这个函数会提取表名和约束名，再通过调用方提供的resolver回调，把它翻译成更精确的业务错误。在用户注册场景（model/user.rs#L133-L139）中，唯一冲突会被解析成UserAlreadyExists；解析不了时则兜底为通用UniqueViolation { table, constraint }。

这一步是"错误从数据库层向业务层语义升级"的典范：原始错误信息不丢失，但获得了业务含义🎯

5. RPC 层：错误枚举 + 派生宏对接 JSON-RPC 路由

lib-rpc-core的所有错误统一在 rpc-core/src/error.rs。它通过#[derive(RpcHandlerError)]宏自动实现了IntoRpcHandlerErrortrait，使错误可以安全地放进rpc-router的动态路由系统（内部用 TypeMap 保存，避免Box<dyn Any>的手工管理）。

RPC 成功响应的规范化也在这一层：rpc_result.rs 定义了DataRpcResult<T>，把所有 RPC 返回值统一包成{"data": ...}，为将来在result根部附加元数据（如分页信息）留出了空间。

6. Web 层：错误 → HTTP 状态码 → 客户端友好 JSON

Web 层是错误传递的终点站，核心文件 lib-web/src/error.rs 做了三件事：

6.1 汇总所有来源的错误

Error枚举聚合了登录失败（LoginFailPwdNotMatching等）、认证中间件错误（CtxExt）、模型错误、RPC 错误、请求解析错误等所有上游错误，是名副其实的"根错误"。

6.2 把 RPC 框架错误"拆包"成具体类型

rpc-router返回的错误是通用的CallError，而 lib-web/src/error.rs#L82-L106 实现了From<rpc_router::CallError>：从 TypeMap 中remove::<lib_rpc_core::Error>()，把不透明的"任意错误"还原成具体的应用错误变体RpcLibRpc；若类型未识别，则记录RpcHandlerErrorUnhandled并打警告日志——既安全又不丢失排查线索。

6.3 状态码映射 + 客户端安全错误体

client_status_and_error（lib-web/src/error.rs#L143-L203）定义了内部错误到 HTTP 响应的映射规则：

内部错误	HTTP 状态码	客户端错误（ClientError）
登录失败（用户不存在/密码错误）	403 Forbidden	LOGIN_FAIL
认证上下文错误	403 Forbidden	NO_AUTH
EntityNotFound	400 Bad Request	ENTITY_NOT_FOUND { entity, id }
RPC 请求/参数解析失败	400 Bad Request	RPC_REQUEST_INVALID等
其余（兜底）	500 Internal Server Error	SERVICE_ERROR

注意客户端错误被设计成独立的ClientError枚举（lib-web/src/error.rs#L205-L218）：它是白名单式的，只包含前端需要知道的信息，数据库细节、内部堆栈统统不会泄漏出去——这是错误体系设计里安全边界的体现 🔒

6.4 中间件统一渲染错误响应

HTTP 错误的最终渲染集中在响应映射中间件 middleware/mw_res_map.rs：

1. Error::into_response先把错误塞进Axum 响应扩展（而非直接生成响应体），状态码先占位为 500；
2. mw_res_map中间件从响应扩展中取出错误，调用client_status_and_error重新生成真实的响应体与状态码；
3. 同时记录请求日志（含req_uuid），方便前后端按 UUID 对账排查。

最终客户端收到的 JSON-RPC 风格错误体形如：

{ "id": "req-123", "error": { "message": "ENTITY_NOT_FOUND", "data": { "req_uuid": "……", "detail": { "entity": "agent", "id": 42 } } } }

RPC 请求的入口处理在 handlers/handlers_rpc.rs，认证信息解析在 middleware/mw_auth.rs（CtxExtError枚举覆盖了 token 缺失、格式错误、校验失败等细分场景）——这些细节错误最终都汇入 Web 层Error，走同一套状态码映射。

7. 新手可以抄走的 5 条经验

1. 每层一个 Error 枚举 +#[from]：用derive_more自动生成From转换，?就能跨层传播错误，杜绝手工match样板代码；
2. 错误语义逐层升级：底层保留原始错误（可观测），上层翻译成业务错误（可理解），最外层白名单化（安全）；
3. 把底层"黑话"翻译成业务错误：如 Postgres23505→UserAlreadyExists，保留表名/约束名兜底，不丢信息；
4. 统一出口渲染错误响应：用中间件集中做"错误 → 状态码 + JSON 体"的转换，handler 里不用关心 HTTP 细节；
5. 每个 crate 的 error.rs 都配Display+std::error::Error：项目里用注释块// region: Error Boilerplate固定这个位置，维护成本极低。

这套Rust 错误处理模式并不复杂，难的是坚持分层的一致性。对照 crates/libs/lib-web/src/error.rs 的完整实现，你就能在自己的 Axum + Cargo workspace 项目中复刻出同样清晰的数据库错误 → HTTP 错误响应传递链路。

【免费下载链接】rust-web-appCode template for a production Web Application using Axum: The AwesomeApp Blueprint for Professional Web Development.项目地址: https://gitcode.com/gh_mirrors/ru/rust-web-app