4. 自定义异常：让错误处理更懂你的业务

讲真，Python 内置的异常类型已经挺丰富了。但我在实际项目中慢慢发现，光靠这些「通用」异常，有时候真的不够用。

举个例子：你写了一个用户注册功能。密码太短抛 ValueError，邮箱格式不对也抛 ValueError。到了排查问题的时候，你看着一堆 ValueError，根本分不清到底是哪一步出了问题。

这时候，自定义异常就派上用场了。

4.1 为什么要自定义异常？

说白了，自定义异常就是给你的错误「贴标签」。让错误信息自带上下文，一看就知道问题出在哪。

我个人的习惯是：只要一个错误在业务中有明确的含义，我就给它单独定义一个异常类。这样做有三个好处：

• 可读性暴增：看到 PasswordTooShortError，不用看错误消息就知道发生了什么
• 精准捕获：可以针对特定异常做特定处理，而不是笼统地捕获所有异常
• 代码自文档化：异常类名本身就是一种文档

4.2 继承 Exception 类

所有自定义异常都必须继承自 Exception 类。这是 Python 的规矩，也是最佳实践。

为什么是 Exception 而不是 BaseException？嗯，这里要注意：BaseException 包含了 SystemExit、KeyboardInterrupt 这些系统级异常。你肯定不希望自己的业务异常和系统退出混为一谈。

class MyCustomError(Exception):
    """这是我的第一个自定义异常"""
    pass

# 使用
raise MyCustomError("出错了，但具体原因你自己猜")

你看，就这么简单。一个 pass 就搞定了一个自定义异常类。

4.3 自定义异常类设计

光有名字还不够。一个好的自定义异常，应该包含足够的信息来帮助排查问题。

我在项目中遇到过这样的情况：一个异常抛出来，只知道「数据校验失败」，但不知道是哪个字段、什么值、期望什么。排查起来简直要命。

所以，我建议你在设计自定义异常时，考虑以下几点：

设计要素	说明	示例
异常名称	清晰表达错误类型	PasswordTooShortError
错误消息	人类可读的描述	"密码长度不能少于8位"
错误代码	机器可读的标识	ERR_PWD_SHORT
上下文数据	出错的原始数据	{'password': '123', 'min_length': 8}

来看一个完整的例子：

class ValidationError(Exception):
    """数据校验异常基类"""
    def __init__(self, message, error_code=None, field=None, value=None):
        self.message = message
        self.error_code = error_code
        self.field = field
        self.value = value
        super().__init__(self.message)

    def __str__(self):
        if self.field:
            return f"[{self.error_code}] 字段 '{self.field}' 校验失败: {self.message}"
        return f"[{self.error_code}] {self.message}"

class PasswordTooShortError(ValidationError):
    """密码太短异常"""
    def __init__(self, password, min_length=8):
        message = f"密码长度不能少于{min_length}位，当前长度{len(password)}位"
        super().__init__(
            message=message,
            error_code="ERR_PWD_SHORT",
            field="password",
            value=password
        )

class EmailFormatError(ValidationError):
    """邮箱格式异常"""
    def __init__(self, email):
        message = f"邮箱格式不正确: {email}"
        super().__init__(
            message=message,
            error_code="ERR_EMAIL_FORMAT",
            field="email",
            value=email
        )

4.4 抛出自定义异常

定义好了异常类，接下来就是在合适的地方抛出它们。

你想想看，什么时候该抛异常？我的经验是：当函数无法完成它承诺的功能时，就应该抛异常。

def register_user(username, password, email):
    """用户注册函数"""
    # 校验密码
    if len(password) < 8:
        raise PasswordTooShortError(password, min_length=8)

    # 校验邮箱
    if '@' not in email or '.' not in email:
        raise EmailFormatError(email)

    # 校验用户名
    if len(username) < 2:
        raise ValidationError(
            message="用户名长度不能少于2位",
            error_code="ERR_USERNAME_SHORT",
            field="username",
            value=username
        )

    # 注册逻辑...
    print(f"用户 {username} 注册成功")
    return True

# 调用示例
try:
    register_user("小明", "123", "invalid-email")
except PasswordTooShortError as e:
    print(f"密码问题: {e}")
    print(f"错误代码: {e.error_code}")
    print(f"错误字段: {e.field}")
except EmailFormatError as e:
    print(f"邮箱问题: {e}")
except ValidationError as e:
    print(f"校验问题: {e}")

输出结果：

邮箱问题: [ERR_EMAIL_FORMAT] 邮箱格式不正确: invalid-email
错误代码: ERR_EMAIL_FORMAT
错误字段: email

4.5 异常继承体系设计

当项目大了，异常类会越来越多。这时候就需要一个清晰的继承体系。

我一般这样设计：

class AppError(Exception):
    """应用基础异常"""
    pass

class DatabaseError(AppError):
    """数据库相关异常"""
    pass

class ConnectionError(DatabaseError):
    """连接异常"""
    pass

class QueryError(DatabaseError):
    """查询异常"""
    pass

class BusinessError(AppError):
    """业务逻辑异常"""
    pass

class InsufficientBalanceError(BusinessError):
    """余额不足"""
    pass

class OrderStatusError(BusinessError):
    """订单状态异常"""
    pass

这样做的好处是：你可以按需捕获不同粒度的异常。

try:
    process_order(user_id, order_id)
except InsufficientBalanceError:
    # 余额不足 - 提示用户充值
    notify_user("余额不足，请充值")
except OrderStatusError:
    # 订单状态不对 - 提示用户联系客服
    notify_user("订单状态异常，请联系客服")
except BusinessError:
    # 其他业务异常 - 通用处理
    notify_user("业务处理失败，请重试")
except DatabaseError:
    # 数据库异常 - 记录日志并告警
    logger.error("数据库异常", exc_info=True)
    alert_ops_team()

4.6 知识体系总览

下面这张图，帮你理清自定义异常的核心逻辑：

4.7 总结一下

自定义异常不是什么高深的技术，但它能让你的代码质量上一个台阶。记住几个要点：

• 继承 Exception，别碰 BaseException
• 异常类名要清晰，一看就知道是什么问题
• 带上足够的上下文信息，方便排查
• 建立合理的继承体系，方便按粒度捕获
• 异常只负责传递信息，别在里面干别的活

嗯，做到这些，你的错误处理就已经超过大多数人了。

可可精品资料库