在Python项目中，错误处理往往随着业务复杂度上升而变得混乱。很多团队初期直接抛出内置的Exception或ValueError，导致调用层只能用宽泛的捕获逻辑，无法区分是网络问题、参数问题还是业务规则问题。自定义异常的层级设计，本质是利用面向对象的继承机制，把错误类型组织成树状结构，让异常处理既有粒度又有层次。
为什么需要自定义异常层级
Python内置异常体系虽然完整，但都是语言层面的通用错误，例如FileNotFoundError、KeyError。业务系统里，我们常遇到“用户余额不足”“订单状态非法”这类领域错误，它们不属于标准库语义。如果直接复用内置异常，调用方在捕获时容易误伤其他底层错误，也难以附加业务上下文。
通过自定义异常层级，我们可以让异常携带错误码、提示信息、原始数据等字段，并且按照“能否重试”“是否致命”等维度分类。这样上层框架可以统一拦截根异常记录日志，业务代码可以精确捕获子类做降级。层级设计还提升了代码可读性，新成员看异常类图就能理解系统错误模型。
基础层级设计模式
最常见的模式是定义一个项目级根异常，所有自定义异常都继承它，然后再按模块或错误类别分支。根异常一般继承Exception，不要继承BaseException，因为后者包含KeyboardInterrupt等系统退出信号，不应被业务捕获。
下面是一个简洁的层级示例，包含根异常、模块基类和具体错误：
class AppError(Exception):
def __init__(self, message, code=500):
super().__init__(message)
self.message = message
self.code = code
class PaymentError(AppError):
def __init__(self, message, code=4001):
super().__init__(message, code)
class InsufficientBalanceError(PaymentError):
def __init__(self, user_id, balance, need):
msg = f"用户{user_id}余额{balance}不足，需{need}"
super().__init__(msg, code=4002)
self.user_id = user_id
self.balance = balance
self.need = need
class ChannelTimeoutError(PaymentError):
def __init__(self, channel):
super().__init__(f"支付渠道{channel}超时", code=4003)
self.channel = channel
上述代码中，AppError作为统一根，PaymentError聚合支付域错误，再向下细分。调用方若想处理所有支付问题，可捕获PaymentError；若只关心余额，就捕获InsufficientBalanceError。这种结构在微服务或大型应用中尤其有用。
按错误性质横向划分
除了按业务模块，还可以按错误性质做横向基类，例如ClientError（客户端可重试或参数错误）、ServerError（服务端故障）。它们同属AppError，但语义不同，中间件可依据类型决定返回HTTP状态码。
示例展示横向划分如何与模块划分共存：
class ClientError(AppError):
def __init__(self, message, code=400):
super().__init__(message, code)
class ValidationError(ClientError):
def __init__(self, field):
super().__init__(f"字段{field}校验失败", code=422)
class ServerError(AppError):
def __init__(self, message, code=500):
super().__init__(message, code)
class DatabaseError(ServerError):
def __init__(self, table):
super().__init__(f"数据表{table}访问异常", code=5001)
这种混合层级让异常处理既支持“捕获某模块所有错”，也支持“捕获某类性质错”。但需注意不要交叉继承过深，否则类之间的关系会难以维护。一般建议根、性质层、模块层、具体错层，总计不超过四层。
捕获与重抛的最佳实践
在业务函数中，应当抛出最具体的子类，而在边界（如API视图、任务入口）捕获根异常做统一包装。这样内部细节不泄露，外部又能拿到结构化错误。
看一段调用示例：
def pay(user_id, amount):
if amount <= 0:
raise ValidationError("amount")
try:
do_gateway_call(user_id, amount)
except GatewayDown as e:
raise ChannelTimeoutError("alipay") from e
def api_entry(user_id, amount):
try:
pay(user_id, amount)
except AppError as e:
return {"code": e.code, "msg": e.message}
except Exception as e:
return {"code": 500, "msg": "系统异常"}
使用raise ... from e能保留异常链，方便排查原始错误。api_entry只认AppError和兜底Exception，避免把Python内部错误如TypeError直接透传给用户。这样的层级配合捕获策略，使系统健壮性明显提升。
常见误区与规避
一个典型误区是定义大量平级异常却不设共同基类，导致调用方必须写多个except。另一个误区是异常类里塞入过多逻辑，如网络请求，这违背了异常只承载错误信息的初衷。
应保持异常轻量，只在init中赋值字段；层级上定期重构，把重复子类合并。若项目使用日志框架，可在根异常中统一实现__str__方法，输出包含code和message的规范文本，便于运维检索。
| 设计方式 | 优点 | 风险 |
|---|---|---|
| 单一根+模块子类 | 结构清晰，易捕获全域错误 | 模块间错误性质混淆 |
| 根+性质层+模块层 | 兼顾分类与模块 | 层级略深，需约束层数 |
| 无基类平级异常 | 初期简单 | 后期捕获冗余，难维护 |
合理的Python自定义异常层级，是项目可维护性的隐形支柱。从根异常出发，结合模块与性质两个维度，控制继承深度，并在边界统一处理，就能构建出既灵活又稳定的错误模型。