wrapt.decorator比functools.wraps更适合异常捕获装饰器，因其天然支持完整调用上下文拦截（含self/cls）、自动适配同步/异步函数、严格保留签名与元信息，避免参数错位、协程未等待等问题。
wrapt.decorator 为什么比 functools.wraps 更适合异常捕获装饰器
因为 wrapt.decorator 天然支持对被装饰函数的完整调用上下文（包括 args、kwargs、self 或 cls）进行拦截，而 functools.wraps 只是元信息复制工具，不提供执行时钩子。写异常捕获逻辑时，你必须在真正调用前拿到所有参数，否则无法做日志回溯或条件重试。
常见错误是直接套用 @wraps(func) 写一个普通闭包装饰器，结果遇到类方法时 self 丢失、args[0] 错位，或者异步函数报 RuntimeWarning: coroutine 'xxx' was never awaited。
-
wrapt.decorator自动识别并透传绑定上下文（self/cls），无需手动判断 - 它默认支持同步/异步函数混用——装饰器内部可统一用
await判断处理 - 签名保留严格：被装饰函数的
__signature__、__name__、__doc__全部原样继承
如何用 wrapt 写一个带重试 + 异常分类的日志装饰器
核心不是“捕获所有异常”，而是区分 Exception 和 BaseException，避免吞掉 KeyboardInterrupt 或 SystemExit；同时要允许按异常类型配置是否重试、是否告警、是否记录 traceback。
import wrapt
import time
import logging
<p>logger = logging.getLogger(<strong>name</strong>)</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/00968c3c2c15" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Python免费学习笔记（深入）</a>”；</p><p>@wrapt.decorator
def safe_call(wrapped, instance, args, kwargs):
max_retries = kwargs.pop('max_retries', 2) # 允许调用时覆盖
retry_delay = kwargs.pop('retry_delay', 1.0)</p><pre class="brush:php;toolbar:false;">for i in range(max_retries + 1):
try:
return wrapped(*args, **kwargs)
except (ConnectionError, TimeoutError) as e:
if i < max_retries:
logger.warning("Retry %d/%d after %s: %s", i+1, max_retries, type(e).__name__, str(e))
time.sleep(retry_delay)
continue
raise
except Exception as e:
logger.error("Unrecoverable error in %s: %s", wrapped.__name__, str(e), exc_info=True)
raise
except BaseException:
# 不捕获系统级退出信号，原样抛出
raise
注意：instance 参数在静态方法中为 None，在类方法中为实际 self，在类本身上装饰（如 @safe_call 放在 class 前）则为 cls——wrapt 已帮你分好，不用再写 if hasattr(wrapped, '__func__') 这类胶水代码。
wrapt 装饰器里怎么安全处理异步函数
不能直接在 try/except 里调用 await wrapped(...)，因为 wrapped 可能是同步函数。必须先判断协程对象类型，再统一用 asyncio.run() 或交由事件循环处理——但更合理的方式是让装饰器本身也支持 async/await 语义。
- 检查
inspect.iscoroutinefunction(wrapped)或asyncio.iscoroutine(wrapped(*args, **kwargs)) - 若为协程，用
await wrapped(*args, **kwargs)；否则用wrapped(*args, **kwargs) - 不要在装饰器里硬塞
asyncio.run()：会破坏调用方已有的事件循环上下文 - 真实项目中建议加一层
if sys.version_info >= (3, 8): import asyncio防止低版本报错
示例关键片段：
import asyncio
import inspect
<p>@wrapt.decorator
async def async_safe_call(wrapped, instance, args, kwargs):
is_coro = inspect.iscoroutinefunction(wrapped)
try:
if is_coro:
result = await wrapped(*args, *<em>kwargs)
else:
result = wrapped(</em>args, **kwargs)
return result
except Exception as e:
logger.exception("Async call failed: %s", wrapped.<strong>name</strong>)
raise
容易被忽略的 wrapt 初始化陷阱
wrapt 默认不会自动安装其 C 扩展模块，纯 Python 回退模式下性能下降约 40%，且某些高级特性（如装饰器嵌套时的栈帧还原）可能失效。开发机没问题，上线后压测才发现延迟突增，就很难定位。
- 安装时显式加
--no-binary wrapt强制编译：pip install --no-binary wrapt wrapt - 验证是否启用 C 模块：
import wrapt; print(wrapt._C)—— 输出<module from ...></module>表示成功 - 在
pyproject.toml中把wrapt加入[build-system]的requires，避免 CI 构建时漏掉编译步骤 - 如果用 PyO3 或 Rust 扩展（如
maturin构建的包），wrapt 的 C 模块可能因 ABI 冲突静默失败，此时需固定wrapt
异常捕获装饰器一旦部署进中间件链路，它的健壮性就取决于最底层的 wrapt 运行时——这点比装饰器逻辑本身还关键。
