Python包中意外异常日志记录的最佳实践

你计划在__main__.py加顶层异常捕获的思路是合理的，但现有写法存在明显缺陷，不属于最优实现，以下是具体判断和该场景下的通用标准实践。

现有方案的核心问题 #

你构思的「捕获Exception后打日志再raise」的逻辑，存在三个明显问题：

• 日志冗余重复：未捕获异常被raise到Python解释器层后，解释器默认会把完整异常栈打印到stderr，你手动用logging.exception打一遍再抛出，会导致同一份异常栈同时出现在日志文件、控制台，重复输出会干扰问题排查。
• 覆盖范围不全：如果异常出现在参数解析、分析对象初始化阶段，还没走到analysis.analyze()的try块范围，就不会被捕获，出现日志漏记。
• 退出逻辑不统一：所有异常最终都抛给解释器，没法统一控制退出码、执行临时文件清理这类收尾操作。

标准最佳实践 #

1. 按职责分层处理异常 #

不要把所有异常处理逻辑都堆在顶层，按代码职责分两层处理：

• 业务逻辑层（main_steps.py、code_1.py、code_2.py等模块）：只处理可预判的预期异常，比如文件不存在、参数格式错误、数据字段缺失这类问题。捕获后补充当前步骤的业务上下文打日志，再抛出封装了明确业务信息的异常即可，不要输出无意义的通用错误信息。
  示例写法：

  try:
      self.raw_data = pd.read_csv(data_file)
  except FileNotFoundError:
      # 补充业务上下文，比裸抛的"文件不存在"排查效率高很多
      logging.exception(f"步骤1读取输入数据失败，目标路径不存在：{data_file}")
      raise
  

• 入口层（__main__.py）：只做全局兜底，处理所有业务层没拦住的未知异常，捕获后打完整日志、完成资源清理，直接以非0状态码退出即可，不需要再把异常raise给解释器，避免重复打印栈信息。

2. 用系统异常钩子实现零侵入全局捕获 #

比在main函数里套一层try-except更通用、覆盖更全的写法，是注册Python的全局未捕获异常钩子，所有没被业务层捕获的异常都会自动走到钩子逻辑里打日志，不需要给业务代码套额外的try块，连参数解析、模块导入阶段抛出的异常都能覆盖到。
你可以在__main__.py配置完logging之后加这段代码：

import sys
import logging

def global_exception_handler(exc_type, exc_value, exc_traceback):
    # 放过用户主动触发的中断（Ctrl+C）、正常退出逻辑，不打错误日志
    if issubclass(exc_type, (KeyboardInterrupt, SystemExit)):
        sys.__excepthook__(exc_type, exc_value, exc_traceback)
        return
    # 所有其他未捕获异常，打完整调用栈到日志
    logging.critical("流程触发未预期异常，终止运行", exc_info=(exc_type, exc_value, exc_traceback))
    # 统一返回错误退出码，可按需添加临时文件清理等收尾逻辑
    sys.exit(1)

# 注册全局异常钩子
sys.excepthook = global_exception_handler

3. 常见避坑点 #

• 不要裸捕获BaseException：会把用户主动中断、程序正常退出的事件也当成错误拦截，不符合命令行工具的交互预期。
• 打异常日志必须带完整调用栈：要么用logging.exception（自动携带当前异常栈），要么传exc_info=True参数，否则日志里只有一行错误信息，没有调用链根本没法定位根因。
• 不要在顶层打无上下文的"Unexpected exception"：预期异常尽量在靠近出错点的位置补充业务信息再抛出，顶层只负责兜底，不要承担业务异常的信息记录职责。

内容的提问来源于stack exchange，提问作者Elkan