入行 Rust 写业务系统这几年我最想吐槽的一句话是错误处理在教科书里是最优雅的在线上系统里是最容易做丑的。ResultT, E把失败显式化这件事确实是 Rust 最吸引人的一点但项目一旦超过三个模块错误处理就会从“类型问题”变成“边界问题”。标题里这个从 Result 到系统级边界设计的演进不是一条理论曲线而是我在几个项目里被线上事故逼出来的经验总结。这篇内容想讲清楚两件事为什么你每个函数都返回 Result 了系统还会把错误处理得那么烂以及系统入口、出口这些边界上错误到底该怎么设计才不容易在重构时崩掉。适合正在把 Rust 用于后端服务、中间件或 CLI 工具的团队参考也适合那些已经从“能编译过”走向“线上能稳”的开发者读。1. Result 撑不起整个错误处理的工程诉求1.1 编译期显式化只是第一步运行期才是主战场编译器保证了两件事你可能失败这件事必须被显式处理错误类型必须出现在函数签名里。但编译器不保证你的错误类型是否携带了足够定位的信息跨层传递之后上下文是否还完整错误被记录和翻译时是否选择了正确的动作。async fn submit_order(order: Order) - ResultOrderId, AppError { let user user_repo.find(order.user_id).await?; let inventory inv_repo.query(order.items).await?; let payment payment_gateway.charge(order.user_id, order.amount).await?; let saved order_repo.save(order).await?; Ok(saved.id) }这个函数没有任何 unwrap每一个?看起来都很标准。但如果你追问下去user_repo.find返回的是“用户不存在”还是“数据库连接失败”payment_gateway.charge超时时错误里是否带上了charge_id和重试次数order_repo.save失败后调用方拿到的AppError能不能区分“订单号冲突”和“磁盘只读”如果这些问题的答案都是否那这段代码只是把错误从底层搬到了上层并没有完成真正的错误处理。我把这个现象叫“编译期显式化”与“运行期契约”的落差。简洁的函数签名、漂亮的?链只代表编译器满意了运行期排障需要的是错误里有上下文、有链路、有可区分的分类。系统级边界设计要补的正是运行期这一侧。1.2 商业错误和系统错误混在一个枚举里是最常见的腐化起点错误建模的第一分水岭是区分商业错误和系统错误。商业错误是业务逻辑的正常分支比如参数非法、用户不存在、订单状态不允许流转它们要被上层感知还要翻译成对外 API 的稳定错误码。系统错误则是基础设施故障比如数据库连接失败、第三方超时、磁盘写入失败它们不该成为业务 match 的主要对象而应该被观测、告警、降级或重试。很多团队一开始会把它们塞进同一个enum AppErrorpub enum AppError { InvalidParam(String), UserNotFound(u64), OrderStateConflict(String), DbConnection(String), ThirdPartyTimeout { service: static str }, SerializationError(String), // 依赖一多这里开始失控 KafkaSendError(String), RedisError(String), }这个枚举在三个模块以内还能忍模块一多每次新增依赖都要来这里加变体每个业务函数 match 都要处理一堆它不关心的基础设施分支枚举越滚越大。更难受的是底层依赖的错误类型被一股脑From转换进来你真想溯源时原始错误早就被to_string()拍扁了。我的建议是至少在 crate 内部把两类错误做强区分。商业错误进业务层错误枚举系统错误保留为可观测的基础设施错误形态在边界处再决定是否向外部暴露。这个区分越早做后边的演进越省力。实践中我会为系统错误单独建一个小的内部类型比如InfraError { op, target, source }。它简洁、稳定、可包裹一切依赖错误且不允许被直接返回给外部。这样业务代码在 match 时只需要关心商业错误系统错误统一走观测通道。2. 错误建模从单层枚举到分层错误域的演进2.1 分层错误域内部、传输、展示三层各干各的事参考我在线上服务里逐步沉淀下来的分层方式内部域每个模块自己定义错误枚举只表达该模块知道的事。它不负责兼容所有调用方也不考虑怎么展示给外部。传输域服务与客户端、服务与服务之间的错误表示通常是扁平结构稳定错误码、HTTP 状态码、机器可读的 detail。展示域面向日志聚合系统或用户界面的文本表示需要防泄露、可定位、可能还要支持 i18n。日常业务函数签名里返回的是内部域错误只有到达服务边界HTTP handler、RPC 入口、消息消费入口、CLI 入口时才做传输域的翻译展示域只是传输域序列化成 JSON 或日志行的一种规格。这样做的好处是内部域的演进不会被外部协议绑架。内部把DbTimeout改名为StorageTimeout不需要动对外错误码外部协议要调整错误文案也不会污染模块内部代码。这个解耦和你把数据库表结构和服务 API 分开是同一个道理。2.2 上下文粘合从 anyhow::Context 抄作业到自定义错误很多人对 anyhow 有误解认为它只是“把错误处理变简单”。但anyhow::Context真正教给我们的是错误跨层时必须追加该层视角的上下文。use anyhow::Context; let resp client .post(format!({}/api/orders, base_url)) .json(body) .send() .await .context(下发订单请求失败)?;这行代码往下游传递错误时错误链里会带着“哪个请求、哪个 URL、哪个阶段”。这是错误工程化的雏形每跨一层就追加一层“人在现场”的说明。如果你不想引入 anyhow完全可以把它吸收进自定义错误类型#[derive(Debug)] pub struct FetchError { stage: static str, url: String, retry_count: u32, source: Boxdyn std::error::Error Send Sync, }我自己的经验是所有从库函数向外冒泡的?原则上一层至少包一次带上当前函数名或模块标识的上下文。代码 review 时我会直接打回那些“裸冒泡”的错误——它们虽然在编译器眼里合法在排障视角里等于没有信息。每层都做一次包装配合#[source]链最终错误链读起来才像一份事故报告而不是一个孤零零的消息。2.3 内部错误枚举的两个长期主义设计第一表达 source 链。自定义错误枚举里不要出现String裸字段最好有source: Boxdyn std::error::Error Send Sync或#[source] source: SomeError。否则底层错误一旦被转换成字符串链路信息就永久丢失。这个问题在日志里特别明显你只看到“操作失败”却看不到最根本的“连接被拒绝”。第二为传输域预留“映射函数”。不要在枚举里写死对外错误码要写fn public_code(self) - Optionstatic str或者集中到一个translate模块。好处是未来增加新错误码时不需要改内部模块只改映射逻辑。错误码跨度变大后这个模块会成为最容易做单元测试、也最容易发现遗漏的部分。我在一个服务里把全部错误翻译收敛到一个文件里之后新来的同事 review 成本大幅下降因为所有“内部错误如何对外”的决策都在一个地方。3. 落到系统边界上的三种动作捕获、翻译、吞没3.1 边界是契约不是泄洪口系统边界指哪些位置HTTP handler、RPC 服务入口、后台任务循环入口、事件消费入口、命令行工具入口以及所有调用外部服务的地方。边界设计的第一原则所有跨过边界的错误都必须经过一次显式决策不允许默默往上冒。我把边界上的动作抽象成三种并在工程规范里要求每个入口函数必须选择其一捕获capture记录日志、采集指标、保留内部错误链但不对外返回内部细节。一般用于系统错误。翻译translate把内部错误映射成对外稳定错误码、HTTP 状态码和固定 message。一般用于商业错误和需要客户端感知的部分系统错误。吞没suppress对噪音错误降噪不打错误日志只进 debug 日志或指标。必须同时有吞没计数告警兜底。一个典型的 HTTP handler 长这样async fn get_order(State(state): StateAppState, Path(id): Pathu64) - Resultimpl IntoResponse, ApiError { let result state.order_service.get_order(id).await; match result { Ok(order) Ok(order), Err(e) Err(state.error_translator.translate(e)), } }关键点handler 只认识ApiError和translate不认识模块内部那些系统错误枚举。这样内部怎么变对外协议都稳定。如果一个入口最终选择了“捕获”那要同时确认监控里能看到这个动作的发生次数否则等于把错误扔进黑洞。3.2 翻译到传输域时的稳定错误码设计对外的传输域错误不要把 message 当协议要设计 code。结构建议字段说明示例code稳定机器码ORDER_NOT_FOUNDhttp_status对应 HTTP 状态404message面向调用方的简短说明订单不存在或已删除detail可选补充信息只放非敏感内容无trace_id关联日志链路67f3a9c20b错误码不要直接用内部枚举名。内部枚举名会随代码重构变化一旦对外发布错误码就是协议的一部分要遵守兼容性可以新增不能修改含义不能混用。我曾见过下游用msg.contains(timeout)判断超时并触发重试一旦 message 被翻译成其他语言或文案调整重试逻辑直接失效。正确做法是把“错误是否属于可重试”做成传输域的一个字段或 code 前缀约定比如RETRYABLE_TIMEOUT和CLIENT_INVALID_ARGUMENT分开程序只依赖 code。消息文本是给人看的code 才是给程序看的。3.3 吞没动作的代价与审批条件吞错是最危险的边界动作因为它的默认结果是一切正常。线上一个后台任务循环里如果某个临时错误被吞掉可能只会看到指标在某个队列上一直停滞没有任何日志提示。所以我在规范里规定想吞一个错误必须过三个问题这个错误是否真的可忽略忽略后业务是否真的不受影响忽略后有没有对应的监控计数器比如suppressed_errors_total打点。有没有兜底告警比如 5 分钟内吞没次数超过阈值就告警。三个问题有一个答不上来那就不要吞先降级为 debug 日志等观测数据充分之后再做决策。这样即便决策错了也能从指标里看到痕迹而不是黑盒失败。吞没这个动作本质上是“用监控换噪音”不是“用消失换清净”。前者可控后者是埋雷。4. 工程化护栏日志关联、panic 策略与 CI 审计4.1 让错误和 trace 绑定而不是只打印一个堆栈错误从 Result 到边界设计的中间件是观测。最轻量的起步是用tracing配合tracing-error让错误包装时保留 span 上下文。推荐做法是入口中间件为每个请求创建 span带上request_id、account_id、endpoint错误在边界翻译之前先统一tracing::error!记录内部错误含 source chain并打点一个 error counter。线上排查时客户端的trace_id能直接把你带到服务端日志再靠 span 结构把同一个请求在多个模块里的错误链串起来。如果服务还没有链路系统至少先从入口中间件统一生成 request_id 开始再让每个模块日志都带它。直接打印堆栈当然也能看到一行行调用帧但缺少请求维度遇到并发高的服务时日志被多请求交叠很难确定某条错误属于谁。错误和 trace 绑定之后你看到的就不是一坨孤立的堆栈而是一条完整的请求轨迹。4.2 panic 还是 Result要在仓库规范里提前划界零 panic 是理想不是默认状态。真实系统里索引越界、整数除法溢出、unsafe 前置条件依然可能触发 panic所以我不会强行要求代码中零 panic而是按层划界场景策略理由库代码不允许主动 panic库无法替调用方决策启动阶段配置错误允许 panic 快速失败没有运行时恢复手段运行阶段内部错误不允许 panic走 Result 或显式终止流程需要保留现场、flush 日志后台线程 panic必须被观测和重启默认 unwind 只终止线程不终止进程我对这个表格有切身体会线上有个服务里一个后台轮询线程因为一次 unwrap 挂在角落 panic服务主进程完全没退出但业务数据不再更新直到用户反馈才被查到。部署策略里必须明确监控 panic并决定是让整个实例重启还是告警后人工介入。不要天真地以为 panic 一定等于进程退出在panic unwind下线程级 panic 是静默发生的。4.3 用 CI 卡住低质量错误处理最后是没人爱做但回报最高的部分CI 审计。clippy 开启-D clippy::unwrap_used -D clippy::expect_used让非测试代码里的 unwrap/expect 直接失败。注意测试代码需要豁免否则测试里写 unwrap 也会被拦住那会很痛苦建议在测试目录单独配置 allow。开启RUSTFLAGS-D warnings把编译器警告升级为错误。review 规则新代码的 handler 入口必须走统一翻译函数自定义错误类型必须包含 source 链对外错误码的新增必须过评审。这些规则加进去的第一个星期通常哀嚎一片很多历史代码会冒出成片的 unwrap 挡住 CI。我的处理方式是老代码开一轮专项整改新代码直接执行硬标准。经过一次清理之后线上新增的错误相关事故会明显下降。CI 在这里不是为难人而是把“错误处理是否合格”从口头约定变成机器检查。4.4 告警把错误处理变成 SLO 的一部分仅记录错误还不够要持续知道边界上发生了什么。简单做法在每个入口翻译函数里按 code 打点一个计数器api_error_total{code...}对高影响错误如支付失败、数据库不可用、消息消费失败单独建监控面板和告警阈值对整体 5xx 比例设置告警。这一步让错误处理从“代码评审”变成“可观测的运行时质量”。我见过很多团队把错误枚举做得很漂亮但完全没监控错误依然是黑盒。体系做到这里才算真正闭环错误有类型、有上下文、有翻译、有指标、有告警缺一环排障时都要多花几倍的时间。5. 复现三个真实事故我给出的边界设计原则5.1 事故一内部错误直接序列化给了客户端之前接手过一个服务handler 里直接return Err(e.into())错误类型 Display 又带着Debug格式化后的内部信息。一次配置错误导致线上返回了配置文件路径、环境变量名、内部服务地址。客户端原样把错误信息打在自己的日志里又转发给第三方信息面扩散失控。修复很朴素handler 入口只允许返回传输域错误类型内部错误一律先记录日志再通过translate映射对外。为了在编译层面减少漏网之鱼我特意不实现内部错误到传输错误的自动 From 转换必须显式调用翻译函数。自动转换虽然省事但会让错误泄露变成默认路径。这个事后看很土的决策恰恰是最有效的一道防线。5.2 事故二错误在 catch 决策里被吞掉上下文批量导入任务里开发者对单个条目失败只记录error!(item {} failed, id)没有保留 source chain也没有记录条目具体数据片段。线上一个大表导入失败后日志全部是 invalid data根本无法定位是哪个字段、哪一段数据导致的。我的改进是批任务里每个条目错误都要带item_id、attempt、对应数据摘要和完整 source chain。同时写了一个统一的多行日志格式让批处理失败日志在聚合系统里一眼能看出同一批次范围内哪些条目失败、失败原因是否一致。这个改动把“功能正常但批量成功率低”的问题从黑盒变成可视化。错误是否成功被观测与错误是否成功处理同等重要。5.3 事故三把第三方库的错误当作“不失败”消息队列消费端的一个错误分支被误判为“正常情况不需要日志”导致某个分区消费一直卡在错误分支里没有 error也没有正常 ack直到积压监控报警才发现。后来做了消费结果去重统计区分 ack、retry、drop 三类把那个错误分支单独画到面板上问题立刻显现。这给我的教训是吞错前先过 3.3 节那三个问题尤其第三方库的错误语义不要凭直觉判断要以消费结果指标为准。当时那条错误从库文档描述看确实像“正常情况”但实际行为是一旦发生就永远处理不了不观测就是事故。5.4 边界设计的一个可抄清单把零散原则浓缩成一张检查清单新服务上线前对每个边界入口过一遍内部错误是否没有直接返回外部是否每个边界入口都显式选择并记录了 捕获/翻译/吞没 动作对外错误是否使用稳定 code而非 message错误链是否包含 source 和当前层上下文日志是否带 request_id / trace_id吞没动作是否有计数器与兜底告警panic 策略是否按启动/运行分层明确CI 是否禁用了非测试代码的 unwrap/expect这张清单不复杂但它把本文提到的所有原则压缩成了可执行动作。每个新模块上线前过一遍能省掉很多后半夜的排障时间。我后来在任何项目里都先画一张边界错误动作表再写业务代码这个习惯帮我省掉的排障时间比任何错误处理库都值钱。最后说点个人长期体会。错误处理从 Result 到系统级边界设计本质不是技术选型而是组织协作每个模块要知道哪些错误是自己的哪些是要翻译给别人的哪些是必须吞掉的。顺序上也别搞反先守住系统边界再抠内部每一个?。不然你写完三万个自定义错误枚举线上该炸还是炸。边界动作表画清楚了错误处理这件事的工程化才算真正开始。