统一返回 Result<T, E> 的分层设计:领域层、服务层与控制层的契约划分

在编写中大型 Rust 软件时,由于没有类似 Java 的全局异常抛出机制,每一个函数的签名都在向外界显式声明其错误契约 Result<T, E>。
很多转码初学者在设计错误类型时,经常会陷入两种极端的混乱:
- 混乱形态 A(全员泛型化):所有函数通篇返回
Result<T, Box<dyn std::error::Error>>或anyhow::Result<T>,导致底层无法针对特定错误做精准模式匹配; - 混乱形态 B(全员大杂烩):定义了一个全局的
AppError枚举,里面既包含了底层的EthernetTruncated,又包含了网络层的HttpTimeout,甚至包含了 UI 层的TerminalResizeFailed,导致模块间产生严重的循环依赖与强耦合。
一个具备高内聚、低耦合特性的工业级 Rust 系统,必须在**领域层(Domain)、服务层(Service)与控制层(Controller/CLI)**之间建立清晰的错误分层与转换契约。
今天这篇文章,我们在抓包分析器中完整落地这套三层错误体系。
1. 三层错误契约划分全景架构
┌────────────────────────────────────────────────────────────────────────┐
│ 控制层 / CLI 入口层 (main.rs / tui_runner) │
│ - 契约模型: anyhow::Result<T> + .with_context(...) │
│ - 职责: 面向人类用户,输出完整因果调用链与彩色排障提示 │
└───────────────────────────────────▲────────────────────────────────────┘
│ (使用 ? 自动转换或附加业务上下文)
┌───────────────────────────────────┴────────────────────────────────────┐
│ 服务层 / 聚合编排层 (packet-engine / session_tracker) │
│ - 契约模型: 专用服务错误枚举 (如 EngineError / DiagnosisError) │
│ - 职责: 封装业务规则,将底层多种细分错误收拢为粗粒度的领域服务状态 │
└───────────────────────────────────▲────────────────────────────────────┘
│ (使用 #[from] 自动映射)
┌───────────────────────────────────┴────────────────────────────────────┐
│ 领域层 / 基础设施驱动层 (packet-core / packet-capture) │
│ - 契约模型: 精确细分错误枚举 (thiserror 驱动, 如 ParseError, IoError) │
│ - 职责: 100% 强类型、包含具体出错参数 (如字节数、协议号),支持精准匹配 │
└────────────────────────────────────────────────────────────────────────┘
2. 第一层:领域层驱动错误(Domain Errors)
在最底层的协议解码模块 packet-core 中,错误必须极度精细,携带出错时的机器参数,且绝对不依赖任何上层服务逻辑:
// crates/packet-core/src/error.rs
use thiserror::Error;
#[derive(Error, Debug, PartialEq, Eq)]
pub enum DecodeError {
#[error("报文长度不足: 期望至少 {expected} 字节,实际仅有 {actual} 字节")]
HeaderUnderflow { expected: usize, actual: usize },
#[error("非法 IP 版本号: 0x{0:02X}")]
InvalidIpVersion(u8),
#[error("TCP 校验和计算不匹配: 计算值 0x{calc:04X}, 首部值 0x{header:04X}")]
BadChecksum { calc: u16, header: u16 },
}
3. 第二层:服务编排层错误(Service Errors)
在业务聚合层(如负责会话追踪和异常识别的 packet-filter 模块),上层服务不关心单个比特位具体是怎么错的,它关心的是“会话状态是否异常”、“存储是否写满”。
通过 thiserror 的 #[from],我们将领域层的底层错误无损映射为服务层状态:
// crates/packet-filter/src/error.rs
use packet_core::error::DecodeError;
use thiserror::Error;
#[derive(Error, Debug)]
pub enum SessionServiceError {
#[error("底层报文解码失败导致会话推进中断: {0}")]
CorruptedPacket(#[from] DecodeError),
#[error("会话连接已超时并被强制关闭: flow_id={0}")]
SessionExpired(u64),
#[error("特征规则编译失败: 规则表达式 '{expr}' 语法错误")]
InvalidFilterRule { expr: String },
#[error("异步队列背压溢出,丢弃未决报文")]
QueueOverflow,
}
关键收益:
服务层的公有 API 明确返回 Result<SessionState, SessionServiceError>,上层可以精准判断如果是 SessionExpired 则执行清理,如果是 CorruptedPacket 则记录告警。
4. 第三层:控制与终端展现层(Application / CLI Layer)
在最顶层的 src/main.rs 或 TUI 运行器中,我们不再关心具体的枚举类型,而是希望将错误以最清晰的链路呈现给运维人员。
此时全面切换为 anyhow::Result:
// src/main.rs
use anyhow::{Context, Result};
use packet_filter::error::SessionServiceError;
use std::path::Path;
fn execute_pcap_analysis(file_path: &Path) -> Result<()> {
let raw_bytes = std::fs::read(file_path)
.with_context(|| format!("读取本地抓包文件失败: '{:?}'", file_path))?;
let mut session_engine = packet_filter::Engine::new();
session_engine
.feed_bytes(&raw_bytes)
.with_context(|| format!("解析抓包文件 '{:?}' 中的流量会话流发生致命错误", file_path))?;
Ok(())
}
fn main() -> Result<()> {
let p = Path::new("test.pcap");
if let Err(err) = execute_pcap_analysis(p) {
// 打印带缩进的多层因果链路
eprintln!(" 任务执行失败:\n{:?}", err);
}
Ok(())
}
5. 跨层重构实践检查表(Checklist)
在每日代码自检时,对照以下清单核验架构防腐:
- [√] 领域模块(Crate Core)中没有任何
anyhow::Result; - [√] 服务层模块的公有 API 全部返回自定义枚举错误,且枚举实现了
std::error::Error; - [√] 所有跨模块的错误冒泡均通过
#[from]或明确的.map_err()进行类型转换; - [√] 顶层 Bin / CLI 中所有的 IO/系统调用均附带了
.with_context(...)上下文说明。
总结
优雅的错误分层设计是大型 Rust 系统生命力的核心:
- 底层追求“强类型与精确性”,便于机器匹配与单测断言;
- 中层追求“高内聚与服务边界”,隔离底层实现细节;
- 顶层追求“可读性与因果链路”,赋能开发者秒级排障。
378



被折叠的 条评论
为什么被折叠?



