Loguru项目中自定义异常无法序列化的解决方案

问题背景

在使用Python日志库Loguru时，开发者可能会遇到自定义异常无法被序列化的问题。具体表现为当尝试记录包含自定义异常的日志时，系统抛出_pickle.PicklingError错误，提示无法pickle自定义异常类。

错误现象

典型的错误信息如下：

_pickle.PicklingError: Can't pickle <class 'app_core.utils.exceptions.ReqNetError'>: attribute lookup ReqNetError on app_core.utils.exceptions failed

这种错误通常发生在以下场景：

1. 使用Loguru的异步日志记录功能（设置enqueue=True）
2. 尝试记录包含自定义异常的日志
3. 自定义异常类定义存在问题

问题根源

该问题的根本原因在于Python的pickle机制无法正确序列化自定义异常类。在Loguru的异步日志记录中，日志消息需要通过pickle序列化后在进程间传递。当自定义异常类不符合pickle的要求时，就会导致序列化失败。

常见的原因包括：

1. 异常类定义在动态生成的代码中
2. 异常类没有正确的__module__属性
3. 异常类定义在__init__.py文件中
4. 异常类使用了动态生成的方式（如使用type()或工厂函数创建）

解决方案

方案一：确保异常类可序列化

自定义异常类需要满足以下条件才能被正确序列化：

1. 定义在模块的顶层，而不是函数内部
2. 具有正确的__module__属性
3. 避免使用动态生成的方式创建异常类

对于使用工厂函数生成的异常类，可以修改为传统定义方式：

class ReqNetError(APIException):
    code = 1014
    msg = "网络请求错误"
    
    def __init__(self, msg=None, task_guid=None):
        self.msg = msg or self.msg
        super().__init__(self.msg)

方案二：升级Loguru版本

Loguru 0.7.2版本已经对这类问题做了优化处理。确保你使用的是最新版本：

pip install -U loguru

方案三：正确使用日志记录方法

避免直接将异常对象作为参数传递给日志方法：

# 错误用法 - 会导致序列化问题
try:
    raise ReqNetError("Message")
except Exception as err:
    logger.error("An error occurred: {}", err)  # err会被pickle

# 正确用法
try:
    raise ReqNetError("Message")
except Exception:
    logger.exception("An error occurred")  # 自动记录异常信息

最佳实践

1. 定义规范的异常类：确保异常类定义在模块顶层，使用传统类定义方式而非动态生成。

2. 测试异常可序列化：在定义异常类后，进行简单的序列化测试：

   import pickle
   pickle.loads(pickle.dumps(ReqNetError("Test")))
   

3. 合理使用日志记录：

   • 使用logger.exception()记录异常
   • 避免将异常对象作为参数传递
   • 对于需要记录的自定义信息，可以转换为字符串

4. 保持Loguru更新：定期更新到最新版本以获取更好的兼容性和功能。

总结

Loguru作为Python中强大的日志库，在异步记录时依赖pickle序列化机制。当遇到自定义异常无法序列化的问题时，开发者应从异常类定义和日志记录方式两方面入手解决。通过规范异常类定义、正确使用日志API以及保持库版本更新，可以有效避免这类问题的发生。

记住，良好的异常设计和日志实践不仅能解决技术问题，还能提高代码的可维护性和可读性。在项目初期就建立规范的异常处理机制，将为后续开发打下坚实基础。