[Rust] Rust 错误处理实践：从源追踪到项目工具 tohum

tohum - 项目快速启动工具

tohum 是一个强大的命令行工具 (CLI)，它可以帮助开发者使用预定义的种子模板快速启动新项目，从而告别重复繁琐的项目配置工作。

主要特点

• 极速启动：基于 Rust 构建，可在数秒内完成新项目的创建，性能卓越。
• 种子仓库 (Silos)：通过仓库系统来组织项目模板，便于查找。支持使用官方仓库或为团队/组织创建自定义仓库。
• 跨平台支持：可在 Linux、macOS 和 Windows 上无缝运行，支持通过 Cargo 安装或源码构建。

快速开始

1. 安装工具

   需要提前安装 Rust 工具链。

   cargo install tohum

2. 查看可用模板

   tohum silo list

3. 创建新项目

   tohum plant @node/react-vite-ts my-awesome-app

可用模板示例

• @go/cli - Go CLI 应用程序模板
• @node/cli-ts - 配置了 TypeScript 的 Node.js 项目
• @node/react-vite-ts - 使用 TypeScript 和 Vite 的 React 项目

项目采用 MIT 许可证开源。

官网：https://tohum.rs/

---

为什么在 Rust 应用中使用结构化错误处理

主要观点

错误处理的心理负担

• Rust 的错误处理机制迫使开发者朝正确的方向前进，即需要思考并单独处理每个错误。
• 尽管理性上认为这很有价值，但由于缺乏对错误路径的充分测试，或者开发者倾向于忽略这些路径，编写样板代码常让人感觉“不值得”。
• 相比其他语言中可能随意抛出字符串异常的做法，Rust 强制执行了本应遵循但经常被忽视的最佳实践。

堆栈跟踪的价值讨论

• 使用结构化错误时，通过在不同上下文位置使用唯一的错误类型（例如明确指出“哪个文件未找到”），错误本身就能指向问题发生的具体位置。
• 开发者通常可以通过搜索错误消息中的上下文信息直接定位问题，这时详细的调用堆栈反而变得不那么重要。
• 堆栈跟踪主要在调试意外的 panic 时有用，因为 panic 通常没有手动附加的上下文信息。
• 对于精心设计的结构化错误，其错误消息中提供的上下文通常就足以进行有效调试。

样板代码的优势

• 结构化的错误类型可以替代手写的错误枚举文档。
• 因为有类型检查器的帮助，可以避免文档因代码迭代而快速过时。
• 实际上，所谓的“样板代码”正是开发者系统地枚举和处理可能出现的各种错误的过程。

工具推荐

• Snafu 库提供了 anyhow 和 thiserror 风格的最佳结合方式。
• 它提供了从简单的字符串类型错误迁移到具体错误类型的简便路径。
• 减少了为强类型错误添加上下文的样板代码量。

讨论原文：https://reddit.com/r/rust/comments/1kx0ak8/why_use_structured_errors_in_rust_applications/

---

Rust 错误源追踪示例

这是一个演示如何通过追踪错误源链来揭示隐藏在错误链中的宝贵诊断信息的 Rust 代码示例。

核心概念

什么是错误源 (Error Sources)？

• 在 Rust 的错误系统中，错误可以通过实现 Error::source() 方法来指向其底层原因，从而形成一条错误链。
• 例如：一个网络错误可能源于一个 IO 错误，而该 IO 错误又可能源于更底层的操作系统错误。
• 默认情况下，许多错误报告工具可能只显示最顶层的错误信息。
• 启用源追踪后，可以遍历完整的错误链，展示出完整的诊断信息全景。

主要功能

1. 问题场景
   • 许多错误类型（例如 reqwest::Error）会包装底层原因，但在报告时通常只显示顶层的通用消息。
   • 这导致真正重要的、用于定位问题的诊断信息被隐藏了起来。
2. 解决方案
   • 通过自定义 ContextFormatterHook 来启用源链追踪。
   • 设置 follow_source: true 来追踪完整的错误链。
   • 设置 follow_source_depth: None 来追踪全部深度，没有限制。
3. 示例对比
   • 不追踪源链：仅显示“error sending request”之类的顶层通用错误消息。
   • 追踪源链：显示从顶层请求错误一直到底层 DNS 解析失败（如 “failed to lookup address information”）的完整错误链路，包含了具体的域名信息。

实现要点

• 创建一个 ReqwestErrorFormatter 结构体来实现 ContextFormatterHook 接口。
• 通过 Hooks::new() 安装这个自定义的错误格式化钩子。
• 代码模拟了 HTTP 请求失败的场景（例如访问一个不存在的域名）。
• 开发者可以为自己的自定义错误类型实现类似的功能，以增强错误报告的可读性和可调试性。

应用价值

此方法能显著提升错误诊断的清晰度和可调试性，帮助开发者快速、准确地定位问题的根本原因，而不是停留在模糊的表面错误上。

示例代码仓库：https://github.com/rootcause-rs/rootcause/blob/main/examples/following_error_sources.rs

希望这些关于 Rust 错误处理的讨论和工具能对你的开发工作有所启发。如果你想与更多开发者交流类似的技术实践，欢迎来云栈社区逛逛。