Python 自定义异常类的最佳实践

Python自定义异常类应继承具体内置异常、以Error结尾、构造函数简洁支持上下文、建立分层继承树。如参数错误用ValueError，文件未找到用FileNotFoundError，业务异常继承Exception并加前缀如PaymentError，命名统一为XxxError，大型项目可设AppError根异常再分层。

Python 自定义异常类的核心是让错误语义清晰、层级合理、易于捕获和调试，而不是简单继承 Exception 就完事。

继承合适的基类，优先用内置异常的子类

大多数情况下，应继承更具体的内置异常，而非直接继承 Exception。比如：

• 参数不合法 → 继承 ValueError
• 找不到资源 → 继承 FileNotFoundError 或 KeyError
• 操作不被支持 → 继承 NotImplementedError

  

  或 TypeError
• 业务逻辑失败（无对应内置类）→ 再考虑继承 Exception，并确保有明确命名前缀（如 PaymentError、ConfigError）

这样能让调用方用通用异常类型做粗粒度捕获，也方便与标准库行为保持一致。

命名规范：用 Error 结尾，避免 Exception

PEP 8 明确建议异常类名以 Error 结尾（如 ValidationError），而非 Exception。这既是约定，也体现语义——它代表一个“出错状态”，不是泛指“异常机制”本身。

不要写 class UserException(Exception):，而应写：
class UserError(Exception):

构造函数保持简洁，必要时支持额外上下文

默认复用父类 __init__ 即可。如需携带结构化信息（如错误码、字段名、原始值），推荐用关键字参数，并在文档中说明：

class ValidationError(Exception):
    def __init__(self, message, field=None, value=None, code=None):
        super().__init__(message)
        self.field = field
        self.value = value
        self.code = code

避免重载 __str__ 或 __repr__ 除非有强理由——默认行为已足够清晰。调试时可通过 exc.field 等属性获取上下文，比解析字符串更可靠。

建立合理的异常继承树，反映领域语义

大型项目中，可定义一个根异常统一管理，再按模块或场景分层：

class AppError(Exception):  # 根异常，用于顶层兜底
    pass
class AuthError(AppError):
pass
class InvalidTokenError(AuthError):
pass
class PermissionDeniedError(AuthError):
pass

这样既能用 except AuthError: 捕获所有认证相关异常，也能用 except InvalidTokenError: 处理特定情况，兼顾灵活性与精确性。