📚 课程目录第2章 Python计算任务异常诊断基础

2. Python计算任务异常诊断基础

在数值计算、数据处理或批量任务中，程序报错几乎是必然事件。真正拉开排障效率差距的，不是“能不能看懂报错”，而是能否在几秒内判断异常属于哪一类、发生在哪一层、由什么输入触发。本节围绕四个基础能力展开：识别异常类型、解读堆栈信息、借助日志与断言定位问题、构建最小复现用例。

一、异常类型：先分类，再定位

Python 的异常体系有明确的继承关系，排障时先判断异常属于哪个“家族”，能大幅缩小排查范围。计算任务中最常见的几类如下：

语法与名称类：SyntaxError、NameError。前者在编译阶段就失败，说明代码本身写错；后者说明引用了未定义变量，常见于拼写错误或作用域误用。
类型与值类：TypeError、ValueError。前者是“对象类型不对”，如把字符串传给需要数值的函数；后者是“类型对但值不合法”，如 int("abc")。二者常出现在数据清洗环节。
索引与键类：IndexError、KeyError。多出现在数组越界、字典缺键、批次切分边界计算错误时。
算术与数值类：ZeroDivisionError、OverflowError，以及 NumPy 中常见的 FloatingPointError（需开启 np.seterr 才会抛出）。
资源与状态类：MemoryError、FileNotFoundError、TimeoutError。这类异常往往与数据规模、路径配置、外部依赖有关，而非算法逻辑本身。

一个实用判断原则：异常类型决定排查方向，异常消息决定排查位置。例如看到 KeyError: 'user_id'，方向是“字段缺失”，位置是“读取该字段的那一行”。

二、堆栈信息：从下往上读

Python 的 traceback 默认按“调用链由外到内”打印，最后一行才是真正的异常类型与消息。解读时应遵循“先看最后一行定类型，再从下往上找业务代码”的顺序。中间大量来自第三方库的帧可以快速略过，重点定位第一个属于自己项目的文件与行号。

Traceback (most recent call last):
  File "pipeline.py", line 42, in <module>
    run_batch(config)
  File "pipeline.py", line 28, in run_batch
    result = compute(records[i])
  File "compute.py", line 15, in compute
    return total / count
ZeroDivisionError: division by zero

这段堆栈中，最后一行说明是除零错误；从下往上第一个业务帧是 compute.py:15，即 total / count；再往上是 pipeline.py:28 的调用点。由此可推断：count 在某批数据中为 0，可能是空批次或过滤后无剩余记录。堆栈不仅告诉你“哪里崩了”，还告诉你“是谁调用到这里的”，这对判断输入来源至关重要。

三、日志与断言：让问题在崩溃前暴露

堆栈只在异常抛出时才有信息量。对于“不报错但结果不对”的计算任务，需要日志与断言主动暴露中间状态。日志的关键是记录可判断的上下文，而不是简单打印“开始处理”。例如在批处理循环中记录批次号、样本数、关键统计量：

import logging
logging.basicConfig(level=logging.INFO,
                    format="%(asctime)s %(levelname)s %(message)s")

for bid, batch in enumerate(batches):
    logging.info("batch=%d size=%d sum=%.3f", bid, len(batch), sum(batch))
    if not batch:
        logging.warning("batch=%d 为空，跳过", bid)
        continue

断言则用于表达“此处必须成立的前提”。它适合校验输入契约与中间不变量，例如 assert count > 0, f"count 应为正数，实际为 {count}"。需要注意：断言在 python -O 优化模式下会被移除，因此断言用于开发期自检，不能替代对用户输入的正式校验。生产代码中对外部数据的检查应使用显式的 if ... raise ValueError(...)。

日志级别建议：DEBUG 记录逐条数据细节，INFO 记录批次级进度与统计，WARNING 记录可跳过但异常的情况，ERROR 记录导致任务失败的问题。排障时先看 ERROR 与 WARNING，再回溯同批次的 INFO 记录。

四、最小复现用例：把问题压缩到可验证的规模

最小复现用例（Minimal Reproducible Example）是排障的核心产出：用尽可能少的代码和数据，稳定触发同一个异常。构建步骤可归纳为“剥离—固定—验证”：剥离与异常无关的模块、IO 和配置；固定随机种子与输入数据，使结果可重复；验证该用例确实抛出与原始任务相同的异常类型和消息。

# 原始任务：读取 CSV 后按列求和，某列全为空导致除零
# 最小复现：直接构造触发条件，去掉文件读取
records = [{"value": None}, {"value": None}]
values = [r["value"] for r in records if r["value"] is not None]
count = len(values)
total = sum(values)
print(total / count)   # ZeroDivisionError，与原始异常一致

这个用例去掉了 CSV 读取、路径配置和日志，只保留“过滤后列表为空”这一关键条件，几行代码即可稳定复现。它既是提交问题的最小证据，也是验证修复方案的最快手段：修复后在该用例上运行，异常消失且结果符合预期，才说明根因被真正解决。

把上述四项能力串起来，就形成一条稳定的排障路径：先由异常类型确定方向，再由堆栈锁定位置，再由日志与断言还原触发条件，最后用最小复现用例固化问题并验证修复。对于“有异常抛出”的任务，堆栈是主线索；对于“不报错但结果异常”的任务，日志与断言才是主线索，二者不可互相替代。

常见误区：只复制最后一行异常消息去搜索，而忽略堆栈中的业务帧；或在最小复现中保留了随机种子未固定的采样逻辑，导致问题时有时无。前者会错过真正的出错位置，后者会让复现本身失去可信度。

建议在项目初期就约定统一的日志格式与断言规范，并把每次排障产出的最小复现用例保留为回归测试。这样，同一个异常第二次出现时，团队不必重新走一遍完整诊断链，而是直接运行用例确认是否复发。