自定义异常类型与结构化日志记录是提升Python代码健壮性和可维护性的关键。通过继承Exception定义业务语义明确的异常类（如InsufficientBalanceError），配合detail字段和统一日志输出，可实现精准捕获、快速定位与高效协作。
Python异常处理不只是用try...except捕获错误，真正提升代码健壮性和可维护性的关键，在于自定义异常类型 + 结构化日志记录。这两者结合，能让问题定位更快、协作更清晰、线上故障响应更高效。
为什么需要自定义异常？
内置异常（如ValueError、TypeError）语义宽泛，无法准确表达业务逻辑中的特定失败场景。比如“用户余额不足”和“订单已过期”都抛ValueError，调用方无法区分处理逻辑。
自定义异常让错误意图明确、层级清晰、便于捕获和测试：
- 继承
Exception或其子类（如RuntimeError），命名体现业务含义（如InsufficientBalanceError） - 支持传入动态信息（如用户ID、订单号），方便日志和调试
- 可在模块顶层集中定义，形成团队统一的错误规范
如何设计实用的自定义异常类？
避免过度设计，从一个简洁、可扩展的基础结构开始：
立即学习“Python免费学习笔记（深入）”；
ImageMagick 批处理处理器
下载
使用 ImageMagick 的 convert 和 mogrify 命令进行批量图像处理，支持调整大小、裁剪、水印和格式转换。与 libvips 集成以实现高性能缩略图生成。
class BizError(Exception):
"""所有业务异常的基类"""
def __init__(self, message: str, code: int = 500, detail: dict = None):
super().__init__(message)
self.message = message
self.code = code
self.detail = detail or {}
<p>class InsufficientBalanceError(BizError):
def <strong>init</strong>(self, user_id: int, required: float, available: float):
msg = f"User {user_id} has insufficient balance"
detail = {"user_id": user_id, "required": required, "available": available}
super().<strong>init</strong>(msg, code=402, detail=detail)
这样设计后，上层可精准捕获：except InsufficientBalanceError as e:，也能统一处理所有业务异常：except BizError as e:。
把异常和日志真正打通
光抛异常不够，关键是要在抛出/捕获时自动记录上下文。推荐在异常基类中集成日志能力，或在统一异常处理器中完成：
- 使用
logging.exception()记录完整堆栈（仅在except块内有效） - 在自定义异常的
__str__或专用方法中生成结构化日志字段（如to_log_dict()） - 配合
structlog或loguru等库，将e.detail直接注入日志输出
示例（标准库写法）：
import logging
logger = logging.getLogger(__name__)
<p>try:
charge_payment(user_id=1001, amount=99.9)
except InsufficientBalanceError as e:
logger.error(
"Payment failed due to insufficient balance",
extra={"error": e.to_log_dict()} # 假设已实现该方法
)
raise # 通常需重新抛出，由上层决定是否吞掉
生产环境建议：异常处理三原则
不裸抛：所有自定义异常必须带明确 message 和可选 code/detail，禁止raise BizError()这种空异常。
不静默：除非有强理由（如重试前的临时失败），否则不要用空except:吞掉异常。
不跨层掩盖：底层抛DatabaseConnectionError，中间层不应转成ServiceUnavailableError再抛——除非语义确实升级（如重试多次后才判定服务不可用），否则应保留原始异常链（用raise ... from e）。
