Python 3.11中如何为异常添加上下文备注信息_使用add_note方法

add_note方法仅在Python 3.11+中可用，且仅适用于Exception子类；它为异常添加人类可读备注，不改变异常类型、消息或传播逻辑，需在抛出前调用，多次调用会按序追加并以换行分隔。

add_note方法只在Python 3.11+可用，且仅对Exception子类有效

add_note 是 Python 3.11 引入的新方法，用于为异常对象附加人类可读的备注信息，它不会影响异常类型、消息或回溯链，只是额外挂载一段字符串。注意：它**不能**被调用在 BaseException 的非 Exception 子类上（比如 SystemExit、KeyboardInterrupt），否则会抛出 AttributeError。

常见错误现象：AttributeError: 'SystemExit' object has no attribute 'add_note' —— 这不是 bug，是设计限制。

• 仅适用于继承自 Exception 的异常（如 ValueError、RuntimeError、自定义异常）
• 必须在异常实例化后、抛出前调用，抛出后无法再修改（因为异常对象通常被冻结在 traceback 中）
• 多次调用 add_note 会按顺序追加，内容用换行分隔

如何正确添加多条备注并观察输出效果

备注本身不自动显示在默认 traceback 中，只有在显式打印异常、或使用 traceback.print_exception 等工具时才会呈现（Python 3.11+ 默认格式已支持）。直接 raise 后终端看到的 traceback 末尾会多出 Notes: 区块。

try:
    raise ValueError("invalid input")
except ValueError as e:
    e.add_note("来源：用户上传的CSV第42行")
    e.add_note("建议：检查字段类型是否匹配schema")
    raise

运行后 traceback 末尾会出现：

Python 3.14.3

微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。

Notes:
  来源：用户上传的CSV第42行
  建议：检查字段类型是否匹配schema

• 备注内容不参与 str(e) 或 e.args，所以 print(e) 不会显示它
• 若用 logging.exception() 记录，Python 3.11+ 的默认 handler 会包含 Notes:；旧版 logging 需手动提取 e.__notes__
• e.__notes__ 是只读列表，不可直接赋值，只能通过 add_note 添加

与__cause__和__context__的本质区别

add_note 和异常链（__cause__ / __context__）解决的是不同问题：后者表达「这个异常是怎么来的」，前者表达「这个异常需要你注意什么」。它们互不干扰，可以共存。

• raise new_exc from old_exc 设置 __cause__，影响 traceback 的 The above exception was the direct cause of the following exception 提示
• add_note 只增加说明文字，不改变异常传播逻辑或嵌套结构
• 调试时，__notes__ 更适合放临时诊断线索（如“此时 cache_size=128”），而 __cause__ 应严格用于真实因果链

生产环境使用时容易忽略的兼容性陷阱

如果你的代码需支持 Python add_note 会导致 AttributeError。不能靠 hasattr(e, 'add_note') 安全兜底——因为旧版本异常对象确实没有该方法，但检查后调用仍可能失败（比如在 except 块外捕获到异常再处理）。

• 推荐做法：封装一个兼容函数，例如 safe_add_note(exc, note)，内部用 sys.version_info >= (3, 11) 判断
• 不要依赖 __notes__ 做逻辑分支（比如 if len(e.__notes__) > 0），它在旧版本不存在，访问会报错
• 单元测试中若 mock 异常，需确保 mock 对象也实现了 add_note 方法，否则测试在 3.11 环境下会失败

真正要用好 add_note，得记住它不是“更漂亮的 message”，而是独立于异常语义的诊断附言——写的时候想清楚：这段话是给未来查问题的人看的，不是给程序逻辑读的。