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 末尾会出现：
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”，而是独立于异常语义的诊断附言——写的时候想清楚：这段话是给未来查问题的人看的，不是给程序逻辑读的。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
