全链路错误码与用户可读提示设计：构建生产级诊断字典

在开发面向生产环境的系统级命令行工具（如抓包分析器）时，当程序遇到异常（例如网卡权限不足、BPF 表达式语法错误、TCP 校验和损坏、云端 AI 诊断超时），最业余的做法莫过于：

• 反面教材 A：直接把底层的操作系统 errno（如 os error 13）或一段几十行的堆栈乱码砸在用户脸上；
• 反面教材 B：输出一句话毫无营养的模糊提示：“解析失败，请重试”。

无论是专业的运维专家还是初级开发者，在面对工具报错时，最需要知道三件事：

1. 全局唯一的标准错误代码（Error Code）：方便在知识库或 GitHub Issues 中精确检索；
2. 直观的中文根因概括（Human-readable Summary）；
3. 立即可执行的处置修复建议（Actionable Solution）。

今天这篇文章，我们在 packet-core 中实战设计一套兼具强类型枚举、全局错误码规范与彩色排障诊断指引的生产级错误字典系统。

---

1. 错误码编码规范设计（Error Code Taxonomy）

我们采用类似 HTTP 状态码与 Linux 内核错误结合的四位分段编码规范：

  ERR - [ 领域模块 (1位) ] [ 错误类别 (1位) ] [ 具体细分编号 (2位) ]
         │                │
         ├── 1: 物理网卡捕获 ├── 0: 权限与配置
         ├── 2: 协议解码    ├── 1: 格式与越界
         ├── 3: 会话与过滤  ├── 2: 校验与完整性
         └── 4: AI 诊断网关  └── 3: 超时与限流

经典错误码字典规划：

• ERR-1001：缺少操作系统原始套接字操作权限（Raw Socket Permission Denied）；
• ERR-1002：指定的网络接口（Interface）不存在或处于 Down 状态；
• ERR-2101：报文头部截断不足最小协议长度（Header Underflow）；
• ERR-2201：TCP 校验和计算不匹配（Checksum Mismatch）；
• ERR-3101：BPF 过滤规则语法解析失败（Invalid Filter Expression）；
• ERR-4301：云端大模型诊断请求超时（AI Gateway Timeout）；
• ERR-4302：触发突发流量令牌桶限流（Rate Limit Exceeded）。

---

2. 定义带自描述元数据的错误 Trait 与枚举

在 crates/packet-core/src/diagnostic_error.rs 中：

// crates/packet-core/src/diagnostic_error.rs
use std::fmt;

/// 系统诊断错误元数据特征
pub trait DiagnosticInfo: std::error::Error {
    /// 全局错误码 (如 "ERR-1001")
    fn code(&self) -> &'static str;
    /// 用户可读的根因概括
    fn summary(&self) -> String;
    /// 具体的处置修复建议
    fn actionable_advice(&self) -> &'static str;
}

#[derive(Debug, Clone)]
pub enum PacketSystemError {
    PermissionDenied { iface: String },
    InterfaceNotFound { iface: String },
    HeaderTruncated { expected: usize, actual: usize },
    InvalidFilterSyntax { expr: String, reason: String },
    AiTimeout { timeout_secs: u64 },
    RateLimited,
}

impl DiagnosticInfo for PacketSystemError {
    fn code(&self) -> &'static str {
        match self {
            Self::PermissionDenied { .. } => "ERR-1001",
            Self::InterfaceNotFound { .. } => "ERR-1002",
            Self::HeaderTruncated { .. } => "ERR-2101",
            Self::InvalidFilterSyntax { .. } => "ERR-3101",
            Self::AiTimeout { .. } => "ERR-4301",
            Self::RateLimited => "ERR-4302",
        }
    }

    fn summary(&self) -> String {
        match self {
            Self::PermissionDenied { iface } => {
                format!("无法在网卡 '{}' 上开启混杂捕获模式：当前进程缺少操作系统原始套接字特权。", iface)
            }
            Self::InterfaceNotFound { iface } => {
                format!("未在宿主机上找到指定的物理网络接口 '{}'。", iface)
            }
            Self::HeaderTruncated { expected, actual } => {
                format!("报文物理截断异常：协议首部期望至少 {} 字节，实际仅收到 {} 字节。", expected, actual)
            }
            Self::InvalidFilterSyntax { expr, reason } => {
                format!("BPF 过滤表达式 '{}' 语法非法: {}", expr, reason)
            }
            Self::AiTimeout { timeout_secs } => {
                format!("向云端 AI 发起的流式因果推断超时（超过 {} 秒未响应）。", timeout_secs)
            }
            Self::RateLimited => {
                "当前突发异常事件频次已触发本地令牌桶流控保护阈值。".to_string()
            }
        }
    }

    fn actionable_advice(&self) -> &'static str {
        match self {
            Self::PermissionDenied { .. } => {
                "请使用 sudo 运行，或在 Linux 下赋予能力: sudo setcap cap_net_raw,cap_net_admin=eip <bin_path>"
            }
            Self::InterfaceNotFound { .. } => {
                "请执行 'ip link' (Linux) 或 'ifconfig' (macOS) 查看系统中活跃的网卡名称并重新指定。"
            }
            Self::HeaderTruncated { .. } => {
                "请检查抓包驱动的 SnapLen 配置，建议设置 snaplen=65535 以捕获完整数据帧。"
            }
            Self::InvalidFilterSyntax { .. } => {
                "请参考 BPF 标准语法，检查是否遗漏了逻辑操作符，例如: --filter 'tcp and port 80'"
            }
            Self::AiTimeout { .. } => {
                "请检查公网连通性，或在启动时通过 --provider ollama 切换至纯本地离线小模型推理。"
            }
            Self::RateLimited => {
                "系统已自动平滑降级为本地规则提示。如需提高并发限制，请修改配置参数 --max-ai-concurrency。"
            }
        }
    }
}

impl fmt::Display for PacketSystemError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "[{}] {}", self.code(), self.summary())
    }
}

impl std::error::Error for PacketSystemError {}

---

3. 彩色终端格式化报告打印器

在 crates/packet-core/src/error_formatter.rs 中：

// crates/packet-core/src/error_formatter.rs
use crate::diagnostic_error::DiagnosticInfo;
use crossterm::style::Stylize;

pub struct PrettyErrorPrinter;

impl PrettyErrorPrinter {
    /// 在终端打印出工业级规范的错误卡片
    pub fn print_diagnostic(err: &dyn DiagnosticInfo) {
        eprintln!("\n{}", "════════════════════════════════════════════════════════════════════════════════".red());
        eprintln!("  {}  {}", " 诊断故障告警 ".on_red().white().bold(), err.code().yellow().bold());
        eprintln!("{}", "────────────────────────────────────────────────────────────────────────────────".dark_grey());
        eprintln!("  {} {}", "故障定性:".bold(), err.summary());
        eprintln!();
        eprintln!("  {} {}", "处置建议:".cyan().bold(), err.actionable_advice());
        eprintln!("{}", "════════════════════════════════════════════════════════════════════════════════\n".red());
    }
}

---

4. 终端实际展示效果

当普通用户未加权限直接启动抓包时：

let err = PacketSystemError::PermissionDenied { iface: "en0".to_string() };
PrettyErrorPrinter::print_diagnostic(&err);

终端以极其抢眼且规范的彩色卡片输出：

════════════════════════════════════════════════════════════════════════════════
   诊断故障告警   ERR-1001
────────────────────────────────────────────────────────────────────────────────
  故障定性: 无法在网卡 'en0' 上开启混杂捕获模式：当前进程缺少操作系统原始套接字特权。

  处置建议: 请使用 sudo 运行，或在 Linux 下赋予能力: sudo setcap cap_net_raw,cap_net_admin=eip <bin_path>
════════════════════════════════════════════════════════════════════════════════

无论发生何种错误，用户一眼就能看到错误编号、清晰的原因与立即可复制运行的修复命令！

---

总结

生产级错误字典设计的核心价值：

• 从“抛出技术异常”升级为“交付解决方案”；
• 标准化的错误码体系为知识库建设与自动化监控提供了坚实的锚点；
• 极大提升了工具在开源社区与企业客户心中的工业级可靠性形象。