rust-error-observability

Rust 错误可观测性

使用此技能，让 Rust 服务故障对运维人员清晰易懂，同时确保面向用户的响应安全。将错误处理与遥测视为同一个设计范畴。

核心工作流

1. 梳理错误流：处理程序返回类型、服务／存储库错误、工作进程错误、中间件、日志和 tracing 配置。
2. 按用途对每个错误分类：
   • 领域或验证结果。
   • 可恢复的控制流。
   • 运维诊断信息。
   • 面向用户的 HTTP 响应。
3. 保持领域错误为强类型。对于调用方应当匹配的预期分支，使用 thiserror。
4. 在基础设施边界添加上下文。如果调用方不应匹配每种依赖故障，则使用 anyhow 或不透明的应用错误。
5. 在每个框架中集中一处将错误映射为 HTTP 响应：ResponseError、Axum IntoResponse，或一个小型适配函数。
6. 优先添加结构化 span，而不是增加更多日志行。包含稳定的诊断字段，不要包含原始载荷或机密。
7. 确保错误只记录一次。优先在可获取请求上下文的外层边界记录。
8. 行为变更时，同时测试公开响应和诊断路径。

错误边界规则

• 领域模块返回领域错误，而不是 HTTP 状态码。
• 存储库模块附加查询或操作上下文，但不要记录每个错误。
• 处理程序将领域结果转换为响应类型，并让意外故障统一返回 500。
• 后台工作进程记录失败的作业 ID、尝试次数和后续操作。
• 在服务路径中避免使用 unwrap、expect 或基于字符串的 map_err，除非不变量仅在本地成立，且 panic 消息确有帮助。

选择 thiserror、anyhow、不透明错误和框架响应适配器时，请阅读 references/error-boundaries.md。

Tracing 规则

• 在请求处理程序、服务方法、出站客户端、数据库操作和工作进程作业的边界处添加埋点。
• 对请求正文、连接池、客户端、密码、令牌和大型值使用 #[tracing::instrument(skip(...))]。
• 在安全的情况下，附加请求 ID、用户 ID、租户 ID、作业 ID、上游名称和幂等键等字段。
• 不要记录机密、Cookie、密码哈希、Bearer 令牌或完整的个人身份信息。

有关 span、subscriber 配置和测试日志，请阅读 references/tracing.md。 处理包含机密的值之前，请阅读 references/secrets-and-pii.md。

HTTP 响应模式

保持响应错误稳定且明确：

pub enum SubscribeError {
    Validation(SubscribeValidationError),
    Unexpected(anyhow::Error),
}

impl actix_web::ResponseError for SubscribeError {
    fn status_code(&self) -> actix_web::http::StatusCode {
        match self {
            Self::Validation(_) => actix_web::http::StatusCode::BAD_REQUEST,
            Self::Unexpected(_) => actix_web::http::StatusCode::INTERNAL_SERVER_ERROR,
        }
    }
}

响应正文应对用户安全。trace 事件应包含运维人员所需的诊断上下文。

参考文件

• references/error-boundaries.md：选择错误类型和响应适配器。
• references/tracing.md：span、字段、subscriber 配置和测试输出。
• references/secrets-and-pii.md：机密和敏感用户数据的脱敏规则。