在 Python 项目中，异常处理很容易成为最容易被忽视却又最影响维护效率的部分。一个典型的场景是：底层数据访问模块直接抛出了内置的 RuntimeError 或 ValueError，上层服务模块捕获后不知道应该如何处理，只能笼统地记录日志后继续往上抛。随着模块数量增加，调用链越来越深，错误类型和错误来源逐渐失去对应关系。解决这个问题的关键在于建立一套跨模块的自定义异常体系，而不是在本地临时添加几个异常类。
为什么优先选择自定义异常而不是内置异常
内置异常类型虽然覆盖了 Python 语法和运行时的大部分问题，但它们的语义过于通用。例如 ValueError 可能来自参数校验，也可能来自配置文件解析失败；RuntimeError 更是一个万能兜底。当模块 A 抛出 ValueError，模块 B 捕获后无法判断这个错误是否可以安全重试，只能根据消息文本做脆弱的关键字匹配。消息文本一旦修改，上层逻辑就会失效。
自定义异常最直接的好处是让异常类型本身成为稳定的契约。异常类型不像消息文本那样频繁变化，它可以携带错误码、模块标识和业务上下文。一个独立的 AppError 基类可以让所有业务异常拥有统一的接口，上层只需捕获这个基类就能覆盖所有已知错误，同时仍然保留捕获具体子类的能力。下面是一个基础定义示例：
# core/exceptions.py
class AppError(Exception):
"""项目所有业务异常的统一基类"""
def __init__(self, message, code=None, module=None):
super().__init__(message)
self.code = code
self.module = module
class ConfigurationError(AppError):
"""配置相关错误"""
class DataAccessError(AppError):
"""数据访问层错误"""
class ServiceError(AppError):
"""业务服务层错误"""
这类结构一旦在项目早期确定下来，后续新增异常只需要增加一个子类，调用方的捕获逻辑不需要大规模调整。这也为跨模块协作提供了明确的边界：所有模块都知道从 core.exceptions 导入基类，而不是各自维护一套互不相干的异常。
如何划分异常基类和模块异常
异常体系设计的核心是组织方式。建议不要在业务模块内部直接定义异常类，而是统一放在一个独立的 exceptions 模块中。这样做的原因有两个：一是避免循环导入，比如服务模块需要从数据访问模块导入异常，而数据访问模块可能又引用了服务模块的常量；二是让异常层级集中展示，开发者可以快速了解项目中有哪些错误类别。
划分层级时，可以按照领域或架构层次来派生。数据访问层可以定义 DataAccessError 及其子类 RecordNotFoundError、ConnectionTimeoutError；配置层定义 ConfigurationError；业务服务层定义 ServiceError。每一层只抛出属于自己的异常，不应跨层抛出其他模块的具体异常。这样上层调用方只依赖底层模块的公开异常类型，不依赖底层实现细节。
# core/exceptions.py 中的进一步细分
class RecordNotFoundError(DataAccessError):
"""查询不到指定记录"""
class ConnectionTimeoutError(DataAccessError):
"""数据库或外部服务连接超时"""
模块之间传递异常时，应尽量使用统一的基类作为接口契约。比如数据访问模块公开的函数可以声明会抛出 DataAccessError，调用方只需要知道这个基类即可。具体是记录不存在还是连接超时，则通过捕获具体子类来分别处理。这种分层方式在大型项目中能显著减少耦合。
跨模块抛错与异常链的正确姿势
在跨模块调用中，仅仅定义异常类型还不够，必须正确保留异常链。Python 提供了 raise ... from ... 语法，可以把原始异常挂在新的业务异常上，形成完整的错误上下文。如果不使用 from，解释器会设置隐式异常上下文，但显式使用 from exc 能让意图更清晰，也能在日志中看到一条完整的因果链。
以下是一个服务模块调用数据访问模块的例子：
# services/order_service.py
from core.exceptions import DataAccessError, ServiceError
def load_order(order_id):
try:
return repository.find_order(order_id)
except DataAccessError as exc:
raise ServiceError("加载订单失败", module="order") from exc
上层捕获时，应当遵循从具体到通用的顺序。先捕获 DataAccessError 处理数据层问题，再捕获 AppError 处理其他业务错误。不要在所有地方都用 except Exception 一把抓，否则会吞掉 KeyboardInterrupt 和 SystemExit，也不要在捕获后只打印日志就返回 None，这会让调用方在不知情的情况下继续执行错误逻辑。
from core.exceptions import AppError, ConfigurationError, DataAccessError
try:
service.run()
except ConfigurationError as exc:
log.warning("配置问题: %s", exc)
except DataAccessError as exc:
log.error("数据访问失败: %s", exc)
except AppError as exc:
log.error("未分类业务异常: %s", exc)
记录日志时，建议同时输出 exc.__cause__，这样运维人员可以从日志中还原出最初是哪个底层错误触发了上层异常。也可以把 exc.code 和 exc.module 写入结构化的日志字段，便于按模块聚合错误。
一个可扩展的异常处理层实践
当项目服务端点增多时，可以在服务入口处建立一个统一处理层，把捕获到的 AppError 转换成统一的错误响应。这个处理层可以是一个装饰器或上下文管理器，核心职责是捕获所有已知业务异常，记录日志，并返回规范化的错误对象。未知异常则记录完整堆栈并返回内部错误提示。
下面展示一个简单的处理函数：
from core.exceptions import AppError
def handle_errors(func):
def wrapper(*args, **kwargs):
try:
return func(*args, **kwargs)
except AppError as exc:
log.error("业务异常 code=%s module=%s", exc.code, exc.module)
return {"ok": False, "error": str(exc)}
except Exception as exc:
log.exception("未预期异常")
return {"ok": False, "error": "内部错误"}
return wrapper
这段代码中捕获了 AppError 和通用 Exception 两种层级。注意这里的顺序不能颠倒：AppError 是 Exception 的子类，如果先捕获 Exception，后面的 AppError 就永远不会命中。通过这种方式，每个服务入口的异常处理逻辑可以被复用，后续增加新的业务异常时也不会影响已有接口。
整体来看，跨模块自定义异常处理的深度并不在于堆砌类，而在于建立清晰的错误分类、保持异常链完整、并在合适的位置集中处理。一个结构良好的异常体系可以减少大量重复的捕获代码，让错误在模块之间传递时依然可追踪、可恢复。
Python异常处理自定义异常跨模块修改时间：2026-09-26 13:08:03