装饰器本质是函数替换，定义时立即执行并覆盖原函数；带参装饰器需三层结构；必须用@wraps保留元信息；类装饰器适用于需状态管理的场景。
@decorator 的本质是函数替换，不是语法糖包装——它在被装饰函数定义时就立即执行，返回值直接覆盖原函数名指向的对象。
装饰器执行时机：定义时而非调用时
很多人误以为 @log_calls 是在 my_func() 被调用时才触发日志逻辑，其实不然。装饰器在模块加载、函数对象创建后**立刻运行**，my_func 这个名字绑定的已经是装饰器返回的新函数了。
验证方式：
def log_calls(func):
print(f"[DEBUG] Decorating {func.__name__}")
def wrapper(*args, **kwargs):
print(f"→ Calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
@log_calls
def add(a, b):
return a + b
输出：[DEBUG] Decorating add
此时 add 已是 wrapper，不是原始函数
return wrapper
常见错误：在装饰器里写耗时初始化（如连接数据库），却没意识到它会在导入模块时就执行，导致启动变慢或连接失败。
带参数的装饰器必须是三层函数
@retry(max_attempts=3) 看似带参，实则是「装饰器工厂」：外层函数接收参数，返回真正的装饰器（第二层），再由它接收被装饰函数（第三层）。
- 第一层：
retry(max_attempts=3)→ 返回一个装饰器函数 - 第二层：返回的装饰器接收
func→ 返回包装函数 - 第三层：包装函数处理实际调用逻辑
漏掉任意一层都会报错：TypeError: 'int' object is not callable 或 missing 1 required positional argument: 'func'。
def retry(max_attempts=2):
def decorator(func): # ← 第二层：真正装饰器
def wrapper(*args, **kwargs):
for i in range(max_attempts):
try:
return func(*args, **kwargs)
except Exception as e:
if i == max_attempts - 1:
raise
return wrapper
return decorator # ← 必须返回 decorator，不能直接 return wrapperfunctools.wraps 是为了保留元信息，不是可选项
不加 @wraps(func)，被装饰函数的 __name__、__doc__、__annotations__ 全部变成包装函数的（比如 wrapper），这对调试、IDE 提示、文档生成（Sphinx）、类型检查（mypy）都是硬伤。
典型现象：
-
help(add)显示的是wrapper的帮助，不是add的 - Flask 路由函数名丢失，导致
url_for('add')找不到端点 - pytest 收集测试函数时跳过，因为
test_add.__name__变成wrapper
from functools import wrapsdef log_calls(func): @wraps(func) # ← 关键：把 func 的 name、doc 等复制给 wrapper def wrapper(*args, *kwargs): print(f"Calling {func.name}") return func(args, **kwargs) return wrapper
类装饰器：当状态管理或复杂配置成为刚需
函数装饰器适合无状态逻辑（如日志、计时），但遇到需要跨调用保存状态（如统计调用次数、缓存最近 N 次结果）、或需复用配置时，类更自然。
注意点：
- 类必须实现
__call__方法，否则@MyDecorator会报TypeError: 'MyDecorator' object is not callable - 类实例在装饰时创建一次，所有对该函数的调用共享该实例状态
- 若需每个被装饰函数独立状态，得在
__init__中按func做隔离（如用weakref.WeakKeyDictionary）
class CallCounter:
def __init__(self, func):
self.func = func
self.count = 0
# 用 wraps 保持原函数信息
from functools import wraps
self.__wrapped__ = func
wraps(func)(self)
def __call__(self, *args, **kwargs):
self.count += 1
print(f"{self.func.__name__} called {self.count} times")
return self.func(*args, **kwargs)@CallCounter
def say_hello():
return "hello"
类装饰器的 __init__ 和 __call__ 分离清晰，但容易忽略 __wrapped__ 和 @wraps 的配合，导致调试时找不到原始函数。
装饰器最易出问题的地方不在语法，而在执行时序和对象生命周期——它改写的是函数定义那一刻的命名空间绑定，不是调用栈里的某个环节。写完记得检查 my_func.name 和 my_func.code.co_filename 是否如预期。
