装饰器本质是函数套函数，@语法糖即传函数并用返回值替换原函数；需确保装饰器及返回值均可调用，正确透传args/*kwargs，末尾return wrapper；带参装饰器需三层嵌套；必须用@functools.wraps修复元信息；类装饰器适用于需状态或初始化的场景。
装饰器本质就是函数套函数，别被@吓住
Python 的 @ 语法糖只是语法快捷写法，背后就是把一个函数作为参数传给另一个函数，再用返回值替换原函数。你写的装饰器本身必须是可调用对象（通常是函数），且返回值也得是可调用对象（通常是闭包或原函数的包装）。
常见错误现象：TypeError: 'NoneType' object is not callable——这是装饰器函数没写 return，或者返回了 None；TypeError: wrapper() takes 0 positional arguments but 1 was given——闭包里没正确接收和转发参数。
- 装饰器函数接收一个函数作为参数，比如
func - 内部定义的包装函数（如
wrapper）必须能接收任意位置/关键字参数：*args, **kwargs - 包装函数里记得调用原始函数：
return func(*args, **kwargs)，否则功能就丢了 - 装饰器函数末尾必须
return wrapper，不能只写wrapper或漏掉
带参数的装饰器要多套一层函数
当你想让装饰器接收配置（比如重试次数、日志级别），就不能直接套在目标函数上，因为 @retry(max_times=3) 这种写法实际调用的是 retry(max_times=3)，它得返回一个真正的装饰器（即接收函数并返回包装函数的那个）。
使用场景：统一加超时、按环境开关日志、权限校验的 role 参数等。
立即学习“Python免费学习笔记（深入）”；
- 最外层函数（如
retry）只收装饰器参数，不收被装饰函数，返回中间层函数 - 中间层函数（如
decorator）接收被装饰的函数func，返回最内层包装函数 - 最内层（如
wrapper）才真正执行逻辑，并调用func - 漏掉任何一层都会报错：
TypeError: 'function' object is not callable或missing 1 required positional argument: 'func'
示例骨架：
def retry(max_times=2):<br> def decorator(func):<br> def wrapper(*args, **kwargs):<br> for i in range(max_times):<br> try:<br> return func(*args, **kwargs)<br> except Exception:<br> if i == max_times - 1:<br> raise<br> return wrapper<br> return decorator
@functools.wraps 是为了修“身份证”，不是可选项
不加 @functools.wraps(func)，被装饰函数的 __name__、__doc__、__module__ 全都变成包装函数的，这对调试、IDE 提示、文档生成（如 Sphinx）、甚至某些框架的反射逻辑（比如 FastAPI 的依赖注入）都是硬伤。
性能影响几乎为零，但兼容性影响极大——尤其在用 inspect.signature() 获取参数签名时，会直接崩。
- 必须在包装函数定义后、
return前加：@functools.wraps(func) - 导入不能省：
import functools或from functools import wraps - 参数必须是原始函数对象，不是字符串或名字，写成
@wraps('func')就失效
类装饰器适合需要状态或复杂初始化的场景
当你要在装饰器里维护状态（比如计数、缓存、连接池），或者初始化成本高（读配置、建连接），类装饰器比嵌套函数更清晰。它的核心是实现 __call__ 方法，让实例可调用。
容易踩的坑：忘了在 __init__ 里保存 func，或在 __call__ 里没正确转发参数和返回值。
- 类的
__init__接收被装饰函数（func）和其他配置参数 - 类的
__call__方法接收*args, **kwargs，处理逻辑后调用self.func(*args, **kwargs) - 同样要修元信息：在
__init__后加functools.update_wrapper(self, func)，不然help()看不到原函数文档 - 类装饰器不能像函数装饰器那样链式调用
@dec1 @dec2后还能保持顺序，除非你自己控制__call__的执行流
装饰器看着轻巧，但参数透传、元信息修复、多层嵌套的返回路径，三处任一出错都会让调用现场莫名其妙挂掉——尤其是加了日志或监控后发现函数名全变成 wrapper，或者断点根本进不到原函数里。
