直接抛Exception("订单不存在")会导致调用方无法区分业务拒绝（如余额不足）与系统故障（如数据库连接失败），HTTP层可能统一返回500，但“库存不足”应返回400，“Redis超时”应返回503，违背错误分类响应、精准捕获和可追溯日志的核心原则。
为什么不能直接用 Exception 抛业务错误
直接 raise Exception("订单不存在") 会导致调用方无法区分是系统故障（如数据库连接失败）还是业务规则拒绝（如余额不足）。HTTP 层可能把所有异常都转成 500，但“库存不足”理应返回 400，而“Redis 连接超时”才该是 503。
统一异常模型的核心目的不是“多定义几个类”，而是让错误能被精准捕获、分类响应、可追溯日志上下文。常见踩坑是只按 HTTP 状态码分层（BadRequestError / ServerError），却忽略业务域语义——比如支付失败和下单失败都可能是 400，但重试策略、告警级别、前端提示文案完全不同。
BaseAppException 必须携带结构化元数据
所有自定义异常应继承一个基类，它至少包含三个字段：error_code（字符串，如 "ORDER_NOT_FOUND"）、http_status（整数）、log_context（字典，用于注入 request_id、user_id 等）。不要用 message 拼接敏感信息，更不要在异常里存对象引用（如 self.order = order），容易引发循环引用或内存泄漏。
示例关键片段：
立即学习“Python免费学习笔记（深入）”；
class BaseAppException(Exception):
def __init__(self, error_code: str, http_status: int = 400,
message: str = "", log_context: dict = None):
super().__init__(message)
self.error_code = error_code
self.http_status = http_status
self.log_context = log_context or {}
-
error_code全大写 + 下划线，不带空格，便于日志聚合和监控告警匹配 - 避免在
__str__中动态拼接 message，防止日志中出现未格式化的占位符（如"User {uid} not found"却没传uid） - 构造时禁止传入可变默认参数（如
log_context={}），否则多个异常实例会共享同一字典
分层拦截：从 domain → service → api 的异常转化链
Domain 层抛出的异常只表达业务规则（如 InsufficientBalanceError），不应含任何 HTTP 或序列化逻辑；Service 层可包装为带事务语义的异常（如 PaymentFailedError）；API 层（如 FastAPI 的 exception handler）才负责映射到 HTTP 响应。中间层若擅自转换，会破坏异常语义的完整性。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
典型错误做法：
- 在 repository 层 raise
HTTPException(status_code=404)—— 数据访问层不该感知传输协议 - service 方法 catch 所有
Exception再统一转成BusinessError—— 吞掉了原始 traceback，调试困难 - 用 try/except 包裹整个 API 路由函数，却没 re-raise 原始异常 —— 导致
logging.exception()打印的是 handler 的栈，而非出错位置
正确姿势是：domain 和 service 层只抛继承自 BaseAppException 的异常；API 层用全局 handler 统一处理，且确保 logger.exception() 记录的是原始异常（非 handler 自己抛的新异常）。
如何避免异常类爆炸和维护失焦
项目初期就定义 20+ 个异常类，90% 永远不会被抛出。真正需要独立类的只有三类场景：需差异化处理（如是否重试）、需独立监控指标（如 "PAYMENT_TIMEOUT" 单独告警）、或需附带特定字段（如 RefundAmountError 需带 actual_amount 和 expected_amount）。
其余情况用工厂函数生成实例更轻量：
def create_validation_error(field: str, reason: str) -> BaseAppException:
return BaseAppException(
error_code="VALIDATION_FAILED",
http_status=400,
message=f"Invalid {field}: {reason}",
log_context={"field": field, "reason": reason}
)
比定义 UsernameValidationError、EmailValidationError 等十几个类更可控。后续真有特殊需求再拆也不迟。
最易被忽略的是异常的生命周期管理：日志中是否记录了足够上下文？前端是否能安全展示 error_code 而不暴露内部细节？监控系统能否基于 error_code 做聚合分析？这些不是加几个类就能解决的，得从第一个异常实例开始就对齐日志、监控、API 响应三端的字段含义。
