1 / 4概念
Error
Python 用异常表示失败,但异常不只是控制流:它携带类型、消息、traceback、因果链与备注。判断一段错误处理是否可靠,要看三件事——捕获的范围是否最小、根因是否保留、清理是否在每条路径上都执行。
1 概念
1.1 一句话定义
异常是对象,raise 把它抛出并沿调用栈向上寻找匹配的 except;try/except/else/finally 负责捕获、分支与清理,with 把资源释放绑定到 __exit__,3.11 起 ExceptionGroup 与 except* 承载多个并发失败。
1.2 它解决什么问题
- 失败与正常路径分离:错误不被返回值逐层透传,主流程保持线性。
- 根因可追溯:
raise ... from与隐式上下文把“为什么失败”保留在 traceback 里。 - 清理确定执行:
finally与with保证文件、锁、事务在异常路径上也会释放。 - 失败可聚合:并发任务的多重失败用异常组一次报告,而不是只留第一个。
- 边界可翻译:底层
OSError、JSONDecodeError在模块边界翻译成领域异常,调用方不必认识实现细节。
代价是异常会隐藏控制流、捕获过宽会吞掉故障、异常成本高于返回值。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
对象生命周期、引用计数与 __del__ | Type |
| 上下文管理器的实现与叠加顺序 | AOP |
协程取消、TaskGroup 与超时 | Async |
| 日志、指标、告警与 trace 后端 | 可观测性章节 |
| 进程退出码、健康检查与部署 | 部署章节 |
| 类型错误与静态检查 | Syntax、OOP |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
BaseException | 所有异常的根 | SystemExit、KeyboardInterrupt、GeneratorExit 不是 Exception |
| 异常层次 | 按继承关系匹配 | 父类 handler 会兜住所有子类 |
| bare raise | 重新抛出当前异常 | 不在 except 里会抛 RuntimeError |
__cause__ | raise ... from 设置的显式原因 | 与 __context__ 是两条链 |
__context__ | 处理期间隐式产生的异常 | 默认会被打印出来 |
else | try 无异常时执行 | 自身的异常不会被同一 except 捕获 |
finally | 无论是否异常都执行 | 其中的 return 或 raise 会覆盖原异常 |
ExceptionGroup | 聚合多个异常的容器 | 3.11 起可用,本身是 Exception 子类 |
except* | 按类型拆分异常组 | 不能与 except 混用在同一个 try |
__notes__ | 3.11 的异常备注 | 通过 add_note 追加,显示在 traceback 里 |
2 机制
2.1 心智模型
把异常想成一次受控的栈展开:raise 之后,解释器从当前帧开始,逐层退出,每层先执行 finally 与 __exit__,再检查这一层的 except 是否匹配。匹配成功就跳到 handler,栈停止展开;没有任何 handler 匹配,线程终止,解释器打印 traceback。
异常对象本身携带 args、__traceback__、__cause__、__context__、__suppress_context__ 与 __notes__。捕获只是拿到对象,清理与链式信息才是排障时真正有用的部分。
2.2 机制拆解
- 异常层次:
BaseException之下分为SystemExit、KeyboardInterrupt、GeneratorExit与Exception。业务代码只捕获Exception及其子类;捕获BaseException会连进程退出与 Ctrl-C 一起吞掉。3.8 起asyncio.CancelledError继承BaseException,正是为了避免被except Exception顺手吞掉。 - 抛出形式:
raise ValueError("bad")创建并抛出;raise不带参数重新抛出当前异常,只能在except或finally的异常上下文中使用;raise ... from exc设置__cause__并把__suppress_context__置真;raise ... from None只抑制上下文展示。 - 两条链:显式
from形成__cause__,隐式“处理 A 时又抛 B”形成__context__。traceback 会打印The above exception was the direct cause of ...或During handling of the above exception, another exception occurred,两者语义不同:前者是主动翻译,后者是意外叠加。 - try 的执行顺序:先执行
try块;无异常则执行else;无论是否异常都执行finally。else里的异常不会被同一个try的except捕获,这是它与“把代码放进 try”最关键的差别。finally中的return、break、raise会覆盖正在传播的异常,甚至让异常消失。 - 匹配规则:
except按书写顺序依次比较,子类必须写在父类之前,否则父类分支永远先命中;except (A, B)匹配任一类型;as exc绑定的名字在except块结束时被删除,以打断异常对象与帧之间的引用环。 - 异常组:
ExceptionGroup("msg", [exc1, exc2])是Exception的子类,BaseExceptionGroup则是BaseException的子类;except*按类型把组拆开,每个分支拿到匹配的子组,未匹配部分在最后重新抛出。split()、subgroup()、derive()提供程序化拆组;except与except*不能在同一个try里混用。
2.3 完整枚举
| 机制 | 用途 | 关键语义 | 版本 |
|---|---|---|---|
raise | 抛出异常 | 新建对象或重抛当前对象 | 全版本 |
raise ... from exc | 显式翻译 | 设置 __cause__,抑制隐式上下文展示 | 3.0 |
except | 按类型捕获 | 顺序敏感,子类在前 | 全版本 |
else | 无异常分支 | 自身异常不被同一 try 捕获 | 全版本 |
finally | 无条件清理 | 覆盖返回值与异常 | 全版本 |
with | 资源配对 | __exit__ 返回值决定是否吞异常 | 全版本 |
contextlib.suppress | 精确忽略 | 只吞列出的类型 | 3.4 |
ExceptionGroup | 聚合失败 | 可嵌套,split 可拆分 | 3.11 |
except* | 分组捕获 | 只匹配组,分支互不干扰 | 3.11 |
add_note | 追加备注 | 写入 __notes__,随 traceback 显示 | 3.11 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
try 块无异常开销 | 接近零 | 3.11 起零成本异常 |
| 抛出并捕获一次 | 1–10 µs | 含 traceback 构造,比返回码贵 |
| 异常对象内存 | 数百字节起 | 随 traceback 帧数增长 |
assert 开销 | 未开启 -O 时可忽略 | 生产环境可能被整体移除 |
ExceptionGroup 最低版本 | 3.11 | 3.10 及以下需自行聚合 |
| 重试退避 | 秒级起步 | 指数退避避免放大故障 |
| 日志记录开销 | 每条约几十 µs | 含格式化与 I/O,别在热路径刷 |
3 实践
3.1 最小示例
import json
from contextlib import contextmanager
class AppError(Exception):
"""业务错误基类。"""
class ConfigError(AppError):
def __init__(self, path, reason):
super().__init__(f"config {path}: {reason}")
self.path = path
self.reason = reason
@contextmanager
def translated(path):
try:
yield
except OSError as exc:
raise ConfigError(path, exc.strerror) from exc
def load(path):
with translated(path):
with open(path, encoding="utf-8") as handle:
raw = handle.read()
try:
return json.loads(raw)
except json.JSONDecodeError as exc:
raise ConfigError(path, "invalid json") from exc
try:
print(load("missing.json"))
except ConfigError as exc:
print("cause:", type(exc.__cause__).__name__)
else:
print("loaded")
finally:
print("done")
translated 把 OSError 翻译成 ConfigError 并保留 __cause__;load 把 JSON 解析错误映射到同一层。外层 try 的 else 只在成功时打印,finally 两条路径都会执行。
3.11 起可以把多个失败一次报告,并用 except* 分别处理:
def validate(rows):
errors = []
for index, row in enumerate(rows):
if row["age"] < 0:
errors.append(ValueError(f"row {index}: negative age"))
if errors:
raise ExceptionGroup("invalid rows", errors)
try:
validate([{"age": 1}, {"age": -1}])
except* ValueError as group:
print(len(group.exceptions), "invalid")
3.2 常用操作与参数
| 操作 | 调用 | 说明 |
|---|---|---|
| 捕获并绑定 | except OSError as exc | 绑定的名字在块末被删除 |
| 翻译异常 | raise NewError(...) from exc | 保留根因,调用方只认识领域异常 |
| 隐藏细节 | raise NewError(...) from None | 只用于不希望暴露内部实现的边界 |
| 精确忽略 | with suppress(FileNotFoundError): | 比裸 except 安全 |
| 动态清理 | ExitStack().enter_context(cm) | 资源数量在运行期决定 |
| 记录完整栈 | logger.exception("...") | 只能在异常上下文中调用 |
3.3 标准流程
- 为每个包定义一个异常基类,子类只表达调用方能处理的差异,并携带必要上下文。
- 在模块边界做翻译:底层库异常转成领域异常,加
from保留根因,不把实现细节透给上层。 - 只捕获能处理的异常;不能处理的让它继续传播,最多在中间层加日志或备注。
- 清理统一交给
with与finally,不要在多个分支里重复close()。 - 每个失败路径都有测试:断言异常类型、
__cause__、清理是否执行,以及重试是否幂等。
3.4 与相邻技术的组合
- pydantic:校验失败抛
ValidationError,在 API 边界转换成 4xx 响应,内部错误保留为 5xx。 - 数据库事务:异常路径必须回滚;
with conn.transaction()把提交与回滚绑定到退出路径。 - asyncio:
TaskGroup失败时取消其余任务并抛ExceptionGroup,与except*配合使用。 - 可观测性:日志只记一次完整 traceback,指标按异常类型计数,trace 记录错误状态而不是重复打印。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 失败是否预期 | 预期 / 意外 | 预期用返回值或校验,意外用异常 |
| 调用方能否处理 | 能 / 不能 | 不能处理就翻译后上抛 |
| 失败数量 | 单个 / 多个 | 多个用异常组聚合 |
| 恢复策略 | 重试 / 降级 / 终止 | 决定异常类型与携带信息 |
3.6 决策规则
- 只捕获你准备处理的异常;捕获后要么恢复,要么翻译,要么加备注再抛,不要什么都不做。
- 翻译必须带
from;只有确实要隐藏内部实现时才用from None。 - 资源释放用
with,不要依赖__del__或 GC 时机。 - 并发任务用
TaskGroup加except*,不要用gather(return_exceptions=True)手工筛异常。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 返回值 / 错误码 | 控制流显式、跨进程友好 | 每层都要检查,易漏 | 协议层、C 接口、批处理 |
Result 类型 | 类型系统强制处理 | 需要额外抽象,生态弱 | 需要显式建模失败的库 |
| 异常 | 无法忽略、自动展开 | 有性能成本、控制流隐式 | 大多数应用代码 |
ExceptionGroup | 一次报告多个失败 | 需要 3.11,处理方式不同 | 并发、批量校验 |
3.8 何时不该用
- 高频正常分支(例如逐行解析可选字段):用返回值或哨兵,异常会成为性能热点。
- 用户输入校验的常规路径:先校验再进入业务,不要靠捕获异常驱动流程。
- 跨进程或跨语言边界:异常对象不可序列化,改用错误码加结构化消息。
- 用异常做循环退出或跳转:
break、return或生成器更清晰。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 线上故障没有任何日志 | 裸 except 或 except Exception: pass | 指定类型并至少记录一次 |
| 根因在 traceback 里消失 | 翻译时没写 from | 加 raise ... from exc |
finally 里的异常覆盖了原异常 | finally 中抛错或 return | 清理代码避免抛异常,必要时记录 |
| 父类分支先命中,子类逻辑不执行 | except 顺序错误 | 子类写在父类之前 |
| 重试把非幂等操作执行多次 | 未确认幂等性 | 只重试幂等操作,或加去重键 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
裸 except: | 吞掉退出、取消与真实故障 | 指定类型,必要时 except Exception |
捕获后 pass | 故障静默,指标失真 | 记录并上抛,或显式降级 |
| 用异常控制正常流程 | 性能差、栈信息噪音大 | 返回值、哨兵或 Optional |
在 finally 里 return | 覆盖异常与返回值 | 只做清理,不改变控制流 |
| 重试所有异常 | 放大故障、重复副作用 | 只重试瞬时错误,限制次数 |
4.3 可观测信号
错误处理的信号分三层:traceback 里的因果链文本(direct cause 与 During handling 的比例反映翻译质量);指标里的异常类型分布与重试次数(某类型突增通常先于可用性下降);日志里的“记录次数 / 实际失败次数”比值(大于 1 说明重复记录,小于 1 说明被吞)。再补 sys.excepthook 与 threading.excepthook 的上报,确认线程与析构期异常没有漏掉。
4.4 安全 / 性能 / 一致性边界
- 安全边界:错误消息会进入日志、响应体与工单,不能包含路径、SQL、密钥与内部主机名;边界统一翻译成稳定错误码。
- 性能边界:异常适合“异常”而非高频分支;3.11 的零成本只免除
try的常态开销,抛出仍要构造 traceback。 - 一致性边界:异常本身不保证回滚;事务、锁与消息确认必须绑定到
with或显式补偿逻辑。 - 版本边界:
ExceptionGroup、except*、add_note需要 3.11;低版本库要用sys.version_info分支或退回聚合器。