自定义异常三层结构：基类BusinessError统一code/details，模块类（如UserError）仅作命名空间，具体类（如InvalidPhoneFormatError）带默认code/message；避免类名重构导致监控失效，错误码须固化而非动态生成。
为什么不能直接 raise Exception("业务出错")
这样写会让所有业务错误混在 Exception 里，调用方无法区分「用户手机号格式不对」和「支付系统超时」——两者恢复策略完全不同。更糟的是，日志里只看到一串字符串，没法做分类统计或告警路由。
自定义异常类的核心目的不是“显得高级”，而是让错误成为可识别、可捕获、可响应的信号。分层的关键在于：用类继承表达语义层级，用类名本身传递错误类型。
- 顶层基类（如
BusinessError）统一收口，方便全局 except 捕获兜底 - 中层按模块划分（如
UserError、PaymentError），便于服务间错误传播时保留上下文 - 底层具体错误（如
InvalidPhoneFormatError、InsufficientBalanceError），供上层精确重试或提示
如何设计三层继承结构并避免常见陷阱
别一上来就写十几个子类。先搭骨架，再按需生长。重点是让每层类承担明确职责：
- 基类
BusinessError应继承Exception，且必须重写__init__支持code和details字段（比如 HTTP 状态码、前端需要的错误码） - 模块类（如
UserError）不要加逻辑，纯作命名空间；否则后续想把某个错误挪到其他模块时，会因继承链卡死 - 具体错误类（如
DuplicateUserError）应带默认code和message，避免每次实例化都传重复参数
示例：
立即学习“Python免费学习笔记（深入）”；
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
class BusinessError(Exception):
def __init__(self, message: str, code: int = 500, details: dict = None):
super().__init__(message)
self.code = code
self.details = details or {}
class UserError(BusinessError):
pass
class DuplicateUserError(UserError):
def __init__(self, user_id: str):
super().__init__(
f"用户 {user_id} 已存在",
code=409,
details={"user_id": user_id}
)
在实际业务代码中怎么用才不破坏可读性
异常不是装饰品，抛出点要贴近真实失败原因。别在 DAO 层抛 PaymentTimeoutError，那是网关或支付 SDK 层该干的事。
- 领域服务内，优先用最具体的子类：比如注册流程校验手机号失败，抛
InvalidPhoneFormatError，而不是笼统的UserError - 跨服务调用（如调支付接口），包装原始异常时，用
raise PaymentError(...) from original_exc保留原始 traceback，别吞掉底层原因 - API 视图层统一捕获
BusinessError，转成 JSON 响应；其他未预期异常走 500，避免把系统错误暴露给前端
反例：if not user: raise UserError("找不到用户") —— 这里应该用更明确的 UserNotFoundError，否则下游无法判断是查无此人，还是数据库连不上。
为什么 logging.exception() 不够，还得加 error_code 字段
日志系统靠结构化字段做聚合分析。如果只依赖 exc.__class__.__name__，一旦类名重构（比如从 PayFailedError 改成 PaymentFailureError），历史告警规则全失效。
- 每个具体异常类必须有稳定、不变的
code属性（整数或字符串 ID），例如USER_PHONE_INVALID = 1001 - 日志记录时显式输出
error_code和error_class，二者互补：前者用于监控大盘，后者用于 debug 细节 - 注意：不要把
code设计成 HTTP 状态码（如 400/500），那属于传输层语义；业务错误码应独立编号，比如支付失败统一是PAY_001，不管它最终映射成 402 还是 503
真正容易被忽略的是：错误码必须在类定义时固化，不能靠构造函数动态生成。否则同一类异常可能打出不同 code，监控就失去意义。
