Python 装饰器把函数"搞丢"了?5 个必踩的坑与完整避坑对照表

简介: 装饰器的坑不是"不会写",而是写完原函数被悄悄换掉——名字、文档、签名、身份都可能变。functools.wraps 救得回大部分,救不了全部。5 个坑逐个给复现代码和修法,附完整对照表。

Python 装饰器把函数"搞丢"了?5 个必踩的坑与完整避坑对照表

先给结论:装饰器最大的坑不是"不会写",而是"写完之后原函数被悄悄换掉了"——名字、文档、签名、甚至它的身份都可能不是原来那个函数。functools.wraps 能救回大部分,但它救不了全部(坑 4 和坑 5 它就无能为力)。

下面 5 个坑,按"踩中频率 × 排查难度"排序,每个都给复现代码和修法。

坑 1:函数名和文档字符串凭空消失

症状:用了装饰器之后,help() 看不到原函数的文档,logging 打出来的函数名全是 wrapper。

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@log_calls
def add(a, b):
    """返回两数之和"""
    return a + b

print(add.__name__)  # wrapper  ← 不是 add!
print(add.__doc__)   # None     ← 文档没了

原因:@log_calls 等价于 add = log_calls(add)。变量 add 现在指向的是 wrapper 函数对象,原函数的元数据自然全丢了。

修法:加 @functools.wraps。

import functools

def log_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

print(add.__name__)  # add
print(add.__doc__)   # 返回两数之和

@wraps 会把原函数的 __name__、__doc__、__module__、__qualname__、__dict__ 复制到 wrapper 上,并设置 __wrapped__ 指向原函数。这是每个装饰器都该有的默认动作。

坑 2:以为 wraps 能让一切恢复原样(其实 signature 另说)

症状:加了 wraps 后,inspect.signature 拿到的还是 (*args, **kwargs),参数校验/依赖注入框架认不出你的参数。

import inspect, functools

def check(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@check
def mul(x: int, y: int = 2) -> int:
    return x * y

print(inspect.signature(mul))

这里 wraps 设置了 __wrapped__,而 inspect.signature 默认 follow_wrapped=True,会顺着 __wrapped__ 找到原函数,所以正常情况会打印 (x: int, y: int = 2) -> int。但如果你显式传了 follow_wrapped=False,或者装饰器是手写赋值而没设 __wrapped__,就会退化成 `(*args, kwargs)`。**

修法:要么依赖 wraps 的 __wrapped__(推荐),要么在需要精确签名的地方显式 inspect.signature(func, follow_wrapped=False) 并自己处理。

坑 3:装饰器在导入时就执行了,不是调用时

症状:你以为注册/计时逻辑要等函数被调用才跑,结果 import 完就已经跑了一遍;Flask 路由注册顺序诡异;进程启动时就打了一堆日志。

REGISTRY = {
   }

def register(func):
    REGISTRY[func.__name__] = func   # import 时就执行
    return func

@register
def task(): pass

print(REGISTRY)  # 模块刚 import 完,这里已经有内容了

原因:装饰器是模块加载阶段执行的——@register 在 def 定义完成的那一刻就被调用了,和函数体是否被执行无关。

修法:如果副作用必须延迟,把注册动作挪到 wrapper 内部(首次调用时执行),或者显式提供一个 init() 由调用方触发。记住这条判据:装饰器函数体的代码在 import 时跑,wrapper 函数体的代码在调用时跑。

坑 4:带参数的装饰器,少写一层

症状:想写 @retry(times=3),结果报错或者行为完全不对。

# 错误:只写了两层
def retry(times):
    def wrapper(*args, **kwargs):
        ...
    return wrapper   # 返回的是 wrapper,但它接收的是原函数的位置参数

原因:带参数的装饰器是三层结构:最外层接收装饰器参数,中间层接收被装饰函数,最内层才是真正的包装。

import functools

def retry(times=3, exceptions=(Exception,)):
    def decorator(func):                  # ← 第二层:收函数
        @functools.wraps(func)
        def wrapper(*args, **kwargs):     # ← 第三层:收参数
            for i in range(times):
                try:
                    return func(*args, **kwargs)
                except exceptions:
                    if i == times - 1:
                        raise
        return wrapper
    return decorator                      # ← 第一层返回 decorator

@retry(times=3)
def fetch(url): ...

记忆口诀:@retry 不带括号是两层,@retry(...) 带括号是三层。

坑 5:装饰器顺序,以及 lru_cache 的内存泄漏

症状 A:@staticmethod 和自定义装饰器叠在一起后,方法调用报参数个数不对。

class A:
    @staticmethod
    @log_calls
    def f(x): return x

A.f(1)      # 正常

class B:
    @log_calls
    @staticmethod
    def f(x): return x

B.f(1)      # 可能抛 TypeError:包装器吃掉/改变了绑定行为

修法:@staticmethod / @classmethod 永远放在最外层(最上面),让描述符协议最后生效。

症状 B:functools.lru_cache 装饰实例方法后,实例永远不被回收。

class Service:
    @functools.lru_cache(maxsize=None)
    def load(self, key): ...

原因:缓存的 key 里包含 self,缓存表强引用着所有调用过的实例,等于给每个实例钉了根钉子。另外 lru_cache 要求参数可哈希,传 list/dict 会直接 TypeError: unhashable type。

修法:实例方法别用 lru_cache(改用 functools.cached_property,或把缓存挂在实例上并手动管理生命周期);参数不可哈希时先转成 tuple/frozenset。

一张对照表收尾

现象 根因 修法
__name__ 变成 wrapper、文档丢失 装饰器返回了新函数对象 @functools.wraps(func)
框架读不到原参数签名 未设 __wrapped__,或 follow_wrapped=False 依赖 wraps;或显式传 follow_wrapped
import 完副作用就跑了 装饰器体在加载时执行 副作用挪进 wrapper,或显式 init()
@retry(times=3) 行为错乱 少写一层(应为三层) 工厂 → decorator → wrapper
方法调用参数个数错 staticmethod 被包在里面 staticmethod 放最外层
实例不释放 lru_cache key 持有 self 实例方法不用 lru_cache
unhashable type 参数不可哈希 转 tuple/frozenset

最后

"wraps 解决元数据,解决不了语义"——它能把名字和文档补回来,但补不回执行时机、参数绑定和内存生命周期。写装饰器时按这三问自查:① 加了 wraps 吗?② 副作用该在 import 时还是调用时?③ 有没有和描述符/缓存叠用?

你踩过最离谱的装饰器坑是哪个?评论区聊聊。

相关文章
|
4天前
|
Python
Python 的 yield from 到底转发了什么:拆开 send、throw 和那个 return 值
把生成器嵌套委托写对,关键是理解它转发的不止是产出值。本文用本机 CPython 3.13.14 实测 yield from 的 return 值透传、send/throw/close 三向内传、手写 for 循环为何丢掉 StopIteration.value、3.11 起已被移除的 YIELD_FROM 指令与 3.13 的 SEND/END_SEND 组合、PEP 479 的 RuntimeError,并给出与手写循环的八项对照表和七条排错清单
|
19天前
|
缓存 Java Python
Python 的 int 为什么不会溢出?拆开 PyLongObject 和它背后那串变长数组
很多人背过“字典查询是 O(1)”,但为什么是常数?CPython 3.13 实测 dict.get 在 100→10 万规模恒为 0.1 微秒,而 list.index 线性涨到 609 微秒(慢 4743 倍)。本文拆开开放寻址哈希表、扰动函数与 2/3 扩容阈值把 O(1) 钉死,也讲清“创建是 O(n)”这个常被混的点。
|
22天前
|
缓存 编译器 Sentinel
Python 里 is 和 == 到底差在哪?拆开小整数池、字符串驻留与 0ns 身份比较
is 比 == 快不是 Python 偷懒,而是它只比对象身份(指针),0ns 级别;== 要走 __eq__ 还可能触发哈希。但小整数池和字符串驻留会让 is 在「本不该相等」时也返回 True,这是 80% 初学者踩的坑。
|
30天前
|
存储 缓存 编译器
Python 的整数为什么永远不会溢出?拆开大整数对象,看 30 位一节的存储与运算代价
Python 整数不会溢出,靠的是把数字拆成 30 位小节用对象数组存:每个整数至少 28 字节,每多 30 位加 4 字节;加法近似线性、乘法超线性——30 万位乘法是 30 位的 29 万倍;str 转换默认 4300 位护栏,to_bytes 比 str 快约 300 倍。用 9 组实验算清「无限精度」的账单。
|
1月前
|
Java 索引 Python
Python 字典为什么这么快?一次查找背后的哈希表、扰动函数和开放寻址
Python 字典查找平均 O(1):算一次哈希直接跳到桶位,实测 1 万 key 取值 4.6ms,同规模列表成员判断要 55 秒,差 12000 倍;但哈希全碰撞时慢 2111 倍——用 4 组实验讲透开放寻址、扰动函数和空间换时间。
|
1月前
|
Python
Python 迭代器和生成器到底啥区别?3 个例子讲透,别再背概念了
迭代器和生成器不是并列关系——生成器是迭代器的一种“偷懒写法”。3 个例子讲透:迭代器是“会挨个吐值的对象”,生成器是用 yield 现写现用的那种,最大区别是它懒,要一个才生一个。
|
1月前
|
Python
Python 装饰器到底是个啥?从 @ 符号到手写一个,5 个例子讲透
装饰器(decorator)本质是一个「接收函数、返回函数」的高阶函数,@log 写在 def foo() 上等价于 foo = log(foo)。本文从最朴素的包装工厂讲起,用 5 个例子把 @ 语法、functools.wraps、带参数装饰器、类装饰器一次讲透。
|
1月前
|
Linux iOS开发 Python
Python 虚拟环境到底怎么选?venv / conda / pipenv / poetry 一张对比表 + 9 个真实踩坑
venv、conda、pipenv、poetry 到底怎么选?本文用一张对比表 + 9 个真实踩坑讲清楚:什么时候 venv 就够了、什么时候必须上 poetry、conda 真正解决的是什么问题,以及虚拟环境里最常见的路径与依赖冲突该怎么排查。
|
3天前
|
缓存 安全 Python
Python 的 isinstance 到底查了什么:拆开 __instancecheck__、ABC 缓存和 type 的区别
把类型判断写对,关键是理解 isinstance 会「问类的意见」而不是自己翻 MRO。本文用本机 CPython 3.13.14 实测 metaclass 上重写 __instancecheck__ 才生效、ABCMeta.register 的虚拟子类不进 __mro__、__subclasshook__ 只看方法存在性、伪造 __class__ 能改变 isinstance 结果、普通类与 ABC 路径 20 万次耗时差 4.4 倍,附对照表与七条排错清单
|
8月前
|
人工智能 Linux API
OpenClaw全自动小红书运营实战:从0到1全流程部署、技能配置与内容自动化发布指南
在内容自动化运营场景中,OpenClaw(Clawdbot)凭借高度可扩展的Skill体系与多任务执行能力,可实现从热点追踪、文案创作、封面生成到笔记发布、互动管理的全流程自动化。本文基于2026年最新环境,完整讲解如何通过阿里云轻量服务器或本地Windows11/macOS/Linux部署OpenClaw,安装并配置小红书运营Skill,完成Cookie登录、内容生成、笔记发布、数据监控,并接入阿里云百炼Coding Plan免费大模型与QMD记忆优化系统,实现低成本、7×24小时无人值守小红书运营。全文无营销词汇,所有命令可直接复制,零基础用户也能快速跑通全流程。
3589 9

热门文章

最新文章