用途:为错误处理提供统一模式与策略,把错误视为系统设计的一等公民,目标是安全失败、给出可操作反馈并支持恢复。
主要能力:区分两类错误。操作性错误(网络、数据库、文件系统故障,无效输入,资源耗尽,超时,限流)应优雅处理、记录日志、反馈用户并实现恢复;程序员错误(运行时类型错误、必需值空访问、断言失败、内部状态无效)应快速失败、记录完整上下文并告警开发者,不尝试恢复。
核心模式:输入校验在系统边界尽早、完整执行,一次返回全部校验错误,包含字段名、实际值与期望格式,不信任外部数据;校验清单涵盖必填、类型、范围、格式与业务规则。错误消息区分受众:面向用户需清晰可操作、无技术术语、格式一致、可本地化;内部日志需完整技术上下文、请求/关联 ID、时间戳与服务标识、堆栈及脱敏数据。恢复策略包括带抖动的指数退避重试(限瞬时故障,设最大次数与熔断)、降级回退(缓存或默认值)、补偿(撤销部分操作、Saga 模式)。日志级别分 ERROR、WARN、INFO、DEBUG;应记录关联 ID、脱敏用户上下文、操作、错误类型与耗时,禁止记录密码、令牌、密钥、完整卡号、PII 及含敏感数据的原始请求响应体。
最佳实践:程序员错误快速失败,操作性错误优雅恢复;提供关联 ID 便于跨服务追踪;使用 JSON 结构化日志;集中错误处理逻辑;像测试成功路径一样严格测试错误路径;监控错误率并设异常告警。
反模式:静默捕获所有异常、日志泄露敏感数据、返回无上下文的通用错误、无保护地重试非幂等操作、混淆校验错误与系统错误、不区分可恢复性。
限制:资料未提供具体安装命令、代码示例细节、收费或平台信息;参考文件 examples/error-patterns.md 仅提及,未展开内容。