用途
Error Handling & Logging Patterns 是一套面向生产系统的错误处理与日志实践模式，目标是让系统在生产环境中可调试、可追踪、可告警。它通过结构化日志与有意的错误处理设计，把散落的 print 与裸 except 替换为可被日志聚合系统消费的规范输出。
主要能力
错误层级设计
提供自定义异常类基类 AppError，包含 message、code、status 三个属性，并派生出 NotFoundError（404）、ValidationError（400）、ExternalServiceError（502）等子类，使错误在抛出时即携带语义化的错误码与 HTTP 状态。
错误分类
以表格形式给出错误分类与处理策略的对应关系，包括：验证错误（不重试、WARNING、不告警）、未找到（不重试、INFO、不告警）、认证失败（不重试、WARNING、基于速率告警）、瞬时外部错误（重试、WARNING、重试后告警）、持久外部错误（不重试、ERROR、告警）、内部缺陷（不重试、CRITICAL、立即告警）。
结构化日志
基于 structlog 提供 configure_logging 配置函数，支持 JSON 输出与开发控制台输出两种渲染方式，处理器链包含上下文变量合并、日志级别、ISO 时间戳与堆栈信息渲染。同时给出按用途划分的日志级别约定（DEBUG/INFO/WARNING/ERROR/CRITICAL）及示例。
上下文日志
使用 contextvars 绑定 request_id、user_id 等上下文，使同一请求内的所有日志自动携带这些字段，无需逐条传入。
请求中间件与错误响应
提供 FastAPI 的 CorrelationMiddleware 示例，从 X-Request-ID 请求头读取或生成 UUID，绑定到日志上下文，记录请求开始与完成，并在响应头回写 X-Request-ID。同时提供 AppError 与未处理异常的 exception_handler，统一返回结构化错误 JSON。
日志模式
包含操作日志（开始/完成/失败三段式）、敏感数据过滤（对 password、token、secret、api_key、authorization 等键做 REDACTED 替换）、性能日志（log_duration 上下文管理器记录耗时毫秒数）。
日志聚合集成
给出可被日志聚合系统摄入的 JSON 格式示例，并约定常用字段：始终包含 timestamp、level、event、service、request_id；可选 user_id、organ、duration_ms、error。
使用方式
资料以 Python 代码示例呈现，主要依赖 structlog 与 FastAPI/Starlette。使用步骤包括：定义异常层级、调用 configure_logging 初始化日志、在请求中间件中绑定关联 ID、注册异常处理器、在业务代码中按模式记录日志。具体安装命令与完整项目集成步骤暂未提供。
适用场景
适用于需要生产可观测性的后端服务，尤其是使用 Python 与 FastAPI 构建、需要跨服务追踪请求、需要区分错误类型并据此决定重试与告警策略的系统。
限制
资料中的代码示例以 Python 为主，未提供其他语言的实现。反模式部分列出了应避免的做法：记录 PII 或密钥、在日志调用中使用字符串插值、捕获并静默异常、日志级别不一致、缺少关联 ID、在紧密循环中记录日志。具体性能开销、日志存储方案与告警平台集成细节暂未提供。