装饰器在 Python 里是很特别的存在。一方面各种框架和库到处都在用它Web 框架的路由、测试框架的 fixture、缓存组件的底层全是装饰器的设计思路另一方面很多人学了好几年 Python真正要自己动手写装饰器的时候还是心里发虚要么照抄模板要么一碰到带参数的装饰器就犯迷糊。我这些年看过不少代码装饰器用得好的是真优雅用得乱的是真灾难。这篇文章我打算把对装饰器的理解完整梳理一遍从函数对象和闭包这些最基础的概念开始到三种典型写法再到内置装饰器和真实场景最后把我踩过的坑也一并交代清楚。适合刚接触 Python 的读者建立完整认知也适合已经写了几年但总觉得自己对装饰器“差点感觉”的开发者查漏补缺。看完你会发现装饰器不是什么高深魔法它就是一个普通的高阶函数只不过被 Python 的语法糖包装了一下。1. 装饰器的底层逻辑函数对象与闭包1.1 函数在 Python 里是一等公民要理解装饰器得先接受一个 Python 里很基本但很多人没当回事的事实函数是对象。在 Python 里def 定义的不只是一个“一堆可执行的代码”而是一个实实在在的对象和列表、字典一样可以赋值、可以放进容器、可以作为参数传递、也可以作为返回值。这听起来像废话但它的推论很关键。比如你可以这样def say_hello(name): return fHello, {name} f say_hello print(f(demo_user)) # Hello, demo_user函数被赋值给另一个变量后这个变量就指向同一个函数对象调用方式和原函数完全一样。更进一步函数还能作为参数传给另一个函数import time def time_it(func, *args, **kwargs): start time.perf_counter() result func(*args, **kwargs) cost time.perf_counter() - start print(f耗时 {cost:.6f} 秒) return result这里的 time_it 就是一个高阶函数——它接收一个函数作为参数在函数执行前后插入逻辑再把结果原样返回。装饰器的所有机制本质上都建立在这个能力之上。说白了装饰器就是“写一个函数去包装另一个函数”的语法糖。理解了这一层你后面看到任何花里胡哨的装饰器写法都不会再发怵因为它们都是在这个基础上做变形。1.2 闭包内层函数为什么能记住外层变量闭包是装饰器的另一个地基。所谓闭包简单说就是一个内层函数引用了外层函数的变量并且这个内层函数被返回到了外层函数之外去使用。Python 会把内层函数引用到的外层变量打包保存下来所以即使外层函数已经执行完毕内层函数仍然能访问那些变量而且每次调用拿到的都是同一个“记住的值”。def outer(x): def inner(y): return x y return inner add_10 outer(10) print(add_10(5)) # 15外层函数 outer 执行完返回 inner 之后x10 这个值并没有消失而是被 inner 记在了自己的闭包环境里。这就是闭包。装饰器里最典型的结构就是这种“外层函数接收参数或函数内层函数负责真正执行逻辑并访问外层变量”的组合。如果没搞懂闭包装饰器写起来很容易出现一些奇怪的问题比如变量被意外覆盖、多个被装饰函数共享同一个状态。我后面讲坑的时候会专门提到这一点。1.3 装饰器的本质一个接收函数并返回函数的函数把上面两点合在一起装饰器的本质就是一句话一个接收函数作为参数、并返回一个新函数的函数。用 语法只是让它在写法上更好看、更直观。def my_decorator(func): def wrapper(*args, **kwargs): print(调用前做点什么) result func(*args, **kwargs) print(调用后做点什么) return result return wrapper my_decorator def hello(): print(hello)这里的 my_decorator 完全等价于执行 hello my_decorator(hello)。如果你在脑子里把这个等式反复念几遍装饰器就没什么神秘的了——它不过是把原来的函数对象替换成一个新的包装函数调用 hello() 的时候真正跑的是 wrapper()而 wrapper 内部会去调用那个被藏起来的原函数。理解了这一层后面所有进阶玩法都是在这个基础模型上做变形带参数的装饰器是给“外层函数”再加一层参数接收类装饰器是把“接收函数返回函数”改成“接收类返回类”多个装饰器叠加是把一个函数的引用连续替换多次。接下来我按这个逻辑一步步把写法的变形过程讲清楚。2. 三种典型写法从无参到带参2.1 无参装饰器的标准模板无参数装饰器是最常用的形态标准模板我建议你直接背下来import functools def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): # 调用前逻辑 result func(*args, **kwargs) # 调用后逻辑 return result return wrapper这里有几个关键点。第一wrapper 的参数必须写成 *args 和 **kwargs因为装饰器根本不知道被包装的函数会接收什么参数只能用可变参数把它们“透明地”转发给原函数。第二调用完原函数之后一定要把 result 原样 return 出去否则被装饰函数的返回值就丢了调用方拿到的永远是 None。第三functools.wraps(func) 是用来修复函数元信息的作用我专门放到后面讲但你自己写装饰器时建议无条件加上。用一个最简单的耗时统计来演示这份模板基本就是实际工作的骨架import functools import time def measure(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.perf_counter() result func(*args, **kwargs) cost time.perf_counter() - start print(f{func.__name__} 耗时 {cost:.4f}s) return result return wrapper2.2 带参数装饰器为什么是三层嵌套无参装饰器只能在函数执行前后插入逻辑但很多场景需要额外的配置比如“重试三次”“超时五秒”“只有管理员才能调用”。这时候装饰器本身需要接收参数写法就从两层嵌套变成了三层。import functools import time def retry(max_times3, delay0.5): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for i in range(max_times): try: return func(*args, **kwargs) except Exception: if i max_times - 1: raise time.sleep(delay) return wrapper return decorator retry(max_times5, delay1) def fetch_data(): # 模拟一个偶尔失败的网络请求 pass很多人第一次看到三层嵌套就懵了。其实逻辑很简单retry(max_times5, delay1) 这一行会先执行 retry(max_times5, delay1)得到一个真正用于装饰的 decorator 函数然后再把 fetch_data 传给这个 decorator。换句话说带参装饰器 一层负责接收参数的函数 一层标准的无参装饰器。我给这三层分别起了个名字方便记忆最外层是“配置层”负责接收参数并把参数放进闭包供后面使用中间层是“装饰层”接收被装饰的函数最内层是“执行层”真正替换原函数去跑业务逻辑。只要把层次记清楚不管嵌套几层你随时能说出每层的作用。这里有个很容易犯的错把配置层和装饰层合并成一层就会出现“装饰器接收了参数但返回的又不是函数”的混乱导致 语法直接报错。2.3 functools.wraps为什么说它必不可少如果不加 functools.wraps被装饰后的函数会变成什么样函数原有的name、doc、module等元信息会全部变成 wrapper 的而不是原函数的。这在调试的时候非常难受def hello(): 我是 hello 的文档 pass decorated measure(hello) print(decorated.__name__) # wrapper而不是 hello print(decorated.__doc__) # None文档丢了functools.wraps 做的事情本质上就是把原函数的name、doc、qualname、module、dict等属性拷贝到 wrapper 上同时给 wrapper 设置一个wrapped属性指向原函数。加了它之后被装饰函数在外观上几乎等同于原函数而且以后你还能通过wrapped拿到最初的函数对象——这个特性在调试多层装饰器时极其好用。我见过不少项目没加 wraps结果调试器里显示的全是 wrapper日志打出来全是“wrapper 被调用”排查问题要多花好几倍时间。我的习惯是只要自己写装饰器第一行就往 functools.wraps(func) 写。这已经成为社区默认的最佳实践没有任何理由不加。3. 内置装饰器与标准库的配合3.1 property、staticmethod、classmethod 你其实每天都在用这几个是 Python 自带的内置装饰器它们的本质也是把函数替换成另一种对象只不过这个操作被 Python 解释器封装好了。property 把一个方法变成只读属性同时可以配 setter 做属性校验classmethod 让方法绑定到类而不是实例适合写工厂方法staticmethod 则把方法变成普通函数只是归在类的命名空间里和实例、类都无绑定关系。一个典型的场景是数据校验class Person: def __init__(self, name, age): self._name name self._age age property def age(self): return self._age age.setter def age(self, value): if value 0 or value 200: raise ValueError(age 不合法) self._age value这里 property 和 age.setter 是一对装饰器它们把 age 变成了一个“智能属性”而不是裸字段。外部访问 p.age 时就像一个普通属性不需要加括号同时内部可以做校验、懒加载、计算缓存等逻辑。以后字段规则变了只需要改装饰器内部调用方的代码一行都不用动。这类封装让类对外暴露的接口保持稳定是 Python 里很推荐的做法。3.2 用 lru_cache 做记忆化缓存标准库 functools 里藏着一个非常好用的缓存装饰器lru_cache。它可以把函数的计算结果缓存起来当相同的参数再次出现时直接返回缓存结果而不是重新执行函数体。对于递归计算、纯函数查询这类场景效果立竿见影。from functools import lru_cache lru_cache(maxsize128) def fib(n): if n 2: return n return fib(n - 1) fib(n - 2)朴素递归算 fib(50) 会慢到怀疑人生加上 lru_cache 之后几乎是瞬间出结果。原因是每个参数组合只计算一次其他调用全部命中缓存。maxsize 控制缓存条数设成 None 表示不限制。不过要注意lru_cache 要求函数参数是可哈希的因为它是把参数作为字典的 key 来存缓存的。如果你的参数里有列表、字典这类可变对象就得先转成元组或者某种不可变形式。还要提醒一点被缓存的函数如果有副作用要格外小心。比如一个函数依赖当前时间、依赖外部文件内容缓存结果就可能过期。遇到这种场景我的做法是在装饰器里加一个版本号参数或者干脆就不用缓存别为了性能把正确性搭进去。3.3 用 contextmanager 把资源管理压扁contextlib.contextmanager 是个很特别的装饰器它能把一个生成器函数变成上下文管理器。与其写一个实现了enter和exit的类不如用装饰器一行搞定代码量能少一半from contextlib import contextmanager contextmanager def open_db_connection(): conn create_connection() try: yield conn finally: conn.close()调用方只需要 with open_db_connection() as conn: 就能安全地使用连接结束时自动关闭。yield 之前的代码相当于enteryield 之后的代码相当于exit。这里的关键是 try/finally 结构因为只有这样才能保证在 with 块内部抛异常时资源也能被正确释放。这个装饰器让“需要成对出现的操作”变得非常优雅比如“开锁/关锁”“开启事务/提交或回滚”“临时改配置/恢复配置”都很适合用它来写。4. 高频实战场景六个我经常自己写的装饰器4.1 计时统计器上面写过一个简版实际项目里我会把计时器做得更实用一点支持开关而且用 perf_counter 而不是 time.time。import functools import time def timer(enabledTrue): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): if not enabled: return func(*args, **kwargs) start time.perf_counter() result func(*args, **kwargs) cost time.perf_counter() - start print(f[{func.__name__}] 耗时 {cost:.4f}s) return result return wrapper return decorator有一个细节值得专门说计时一定要用 time.perf_counter()不要用 time.time()。time.time() 是墙上时钟受系统时间调整、NTP 校正影响测得的结果可能跳变perf_counter 是单调时钟专门用来测量短时间间隔精度也更高。我见过有人用 time.time() 做性能对比结果因为时钟跳变测出负数耗时排查半天才发现是计时器选错了。4.2 重试机制网络请求、数据库连接这类操作经常需要遇错重试。重试装饰器可以说是项目的标配import functools import time def retry(max_times3, delay0.5, exceptions(Exception,)): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for attempt in range(1, max_times 1): try: return func(*args, **kwargs) except exceptions as e: if attempt max_times: raise time.sleep(delay * attempt) return wrapper return decorator这里我把 delay 设计成随重试次数递增也就是简单的指数退避避免服务刚恢复时所有客户端同时猛冲。exceptions 参数让调用方可以指定只对哪类异常重试比如只重试超时异常而不是所有异常——如果函数抛的是业务错误重试没有意义还可能造成数据重复写入。实际使用中重试装饰器特别需要注意“是否幂等”被重试的函数必须能安全地执行多次否则重试反而会带来脏数据。4.3 权限校验Web 项目里最常见的装饰器用法之一。我写过一个很精简的版本import functools def require_role(role): def decorator(func): functools.wraps(func) def wrapper(request, *args, **kwargs): user getattr(request, user, None) if user is None or user.role ! role: raise PermissionError(f需要角色 {role}) return func(request, *args, **kwargs) return wrapper return decorator这个装饰器把权限逻辑从业务函数里彻底抽离出来了。业务函数只负责自己的事“当前用户是谁、有没有权限”是装饰器的事。这样职责划分非常干净新加一个接口需要权限时一行装饰器就搞定不用复制粘贴权限判断代码。要注意的是wrapper 的第一个参数写成 request是因为被装饰函数签名的第一个参数就是 request如果你要装饰的函数签名不同这个位置要相应调整。另外权限校验失败的异常类型要选好在 Web 框架里通常会映射成 403 响应而不是 500。4.4 日志记录日志装饰器的坑主要在参数格式化。有的函数参数里带着密码、token 这类敏感信息直接全量打成日志就泄密了。我通常的做法是允许调用方传一个敏感参数名列表把对应的值打码import functools import logging logger logging.getLogger(__name__) def logged(sensitive()): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): args_desc , .join(str(a) for a in args) kwargs_desc , .join( f{k}{*** if k in sensitive else v} for k, v in kwargs.items() ) logger.info(调用 %s(%s, %s), func.__name__, args_desc, kwargs_desc) try: result func(*args, **kwargs) logger.info(完成 %s, func.__name__) return result except Exception: logger.exception(异常 %s, func.__name__) raise return wrapper return decorator特别提醒一点装饰器内部 logger.exception 里的堆栈信息非常有用但千万不要吞异常。装饰器里 catch 到异常之后应该 re-raise让上层调用者继续处理否则异常处理链就在装饰器这里断掉了外层怎么等都等不到这个异常。另外日志里打印参数时注意控制长度否则一个超大对象的 repr 就能把日志文件撑爆。4.5 注册表与插件系统装饰器不止能包装函数还能把函数“登记”起来。这就是注册表模式。我在写一个模拟策略系统的时候用过这个思路把不同策略函数用装饰器注册到一个全局字典运行时按名字取用strategies {} def register(name): def decorator(func): strategies[name] func return func return decorator register(fixed) def fixed_strategy(): 固定策略实现 pass register(adaptive) def adaptive_strategy(): 自适应策略实现 pass注意这个装饰器和前面几个不太一样它并没有替换原函数而是把原函数放进字典之后原样返回。所以策略函数被调用时没有任何额外开销。以后要加新策略只需要新增一个带装饰器的函数主流程代码一行都不用改。这种“插件式”的扩展方式在有多种实现可选、需要动态切换的场景里特别实用比如消息处理器、文件导入器、算法实现库都可以用注册表模式组织。4.6 超时控制超时是个比较难做的话题因为 Python 里没有一个简单方法能直接中断一个正在执行的同步函数。可行的方案之一是用 signal 模块通过发送 SIGALRM 信号来触发超时import functools import signal def timeout(seconds): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): def handler(signum, frame): raise TimeoutError(f{func.__name__} 超时 {seconds}s) signal.signal(signal.SIGALRM, handler) signal.alarm(seconds) try: return func(*args, **kwargs) finally: signal.alarm(0) return wrapper return decorator这个方案有两个明确限制第一只适用于 Unix/Linux 平台Windows 上没有 SIGALRM第二signal 只能在主线程里设置多线程环境下并不能对子线程里的函数生效。所以我的经验是在 Linux 后台任务里用这种信号方案很顺手但要是在 Windows 开发机上调试这段代码会直接报错别问我怎么知道的。跨平台的超时方案通常得配合多进程或者线程加 join(timeout) 来做代价更大但这是另一篇文章的内容了。5. 装饰器的坑与排查技巧5.1 叠加装饰器的执行顺序两个装饰器叠在一起时执行顺序经常让人困惑。看这段代码a b def f(): pass它等价于 f a(b(f))。也就是说先应用离函数最近的 b再应用 a。调用 f() 时实际执行顺序是先进入 a 的 wrapper然后调用 b 的 wrapper最后才到原函数 f函数返回时顺序反过来。这个顺序在项目里特别容易踩坑。比如你同时用了权限校验和重试如果权限装饰器在外层、重试装饰器在内层那么每次重试都会重新走一遍权限校验——这通常不是你想要的行为因为权限校验属于“前置条件”不该被重试。反过来如果重试在外层、权限校验在内层权限校验只执行一次重试只针对业务操作本身。叠加装饰器之前一定要想清楚哪个逻辑应该包在外面哪个应该贴住原函数。我的判断标准是“外层负责策略内层负责业务”。5.2 闭包变量共享的坑带参数的装饰器闭包结构较深很容易把变量放错层级导致多个被装饰函数共享同一个状态。举个例子def make_decorator(): state {count: 0} def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): state[count] 1 return func(*args, **kwargs) return wrapper return decorator decorator make_decorator() decorator def a(): pass decorator def b(): pass这里 a 和 b 共用同一个 decorator所以它们也共享同一个 state 字典。如果你本来想让每个函数各自计数那这就是个 bug。排查的思路是检查闭包捕获的变量到底属于“配置层”“装饰层”还是“执行层”。应该属于执行层的状态比如每次调用独立的计数器、临时变量就在 wrapper 内部创建该属于配置层的状态比如重试次数、超时秒数在配置层创建并明确说明是共享的如果需求是“每个函数独立状态”就要把状态创建移到 wrapper 内部或者用一个以函数对象为 key 的字典来存放。5.3 类装饰器与装饰类的选择装饰器不仅能装饰函数也能装饰类。类装饰器接收一个类返回一个新类通常用来给类批量添加方法或属性def add_repr(cls): def __repr__(self): return f{cls.__name__}({vars(self)}) cls.__repr__ __repr__ return cls add_repr class Point: def __init__(self, x, y): self.x x self.y y装饰函数和装饰类的选择我的经验是如果只是增强单个函数、方法的行为用函数装饰器如果需要给整个类统一补充能力、修改类的结构用类装饰器。还有一种方案是“装饰器内部返回类的实例”把函数包装成某个自定义类的对象实现函数和状态、属性的融合。这类玩法在写 DSL 和框架时会遇到日常项目用得不多但理解了“装饰器就是替换对象”的原理后你会发现它不过又是同一种思想的不同变形。5.4 常见问题速查表我把这几年在项目里实际遇到的装饰器问题整理成一张速查表放在团队文档里这里也分享出来症状常见原因处理办法被装饰函数名变成 wrapper没加 functools.wraps加上 wraps返回值丢失全是 Nonewrapper 内部没 return 原函数结果把 result 原样 return参数对不上、报 TypeErrorwrapper 签名写死成固定参数用 *args, **kwargs 透传多个装饰器行为顺序不对没搞清叠加顺序先应用离函数最近的装饰器多个函数意外共享状态闭包变量放错层级检查变量属于哪一层缓存不生效参数不可哈希或函数有外部依赖转成可哈希参数或加版本号异常堆栈看不到原函数未加 wraps堆栈全是 wrapper加 wraps或追wrapped装饰器配置写死不可变把配置放进了装饰层而不是配置层改成带参装饰器的三层结构这份表帮我在实际排查中省了很多时间。大多数装饰器问题本质上是“对函数对象的替换”这个模型没想透。一旦想透了很多坑都能一眼看穿。6. 进阶经验装饰器设计的一些个人建议6.1 保持装饰器的通用性写装饰器时wrapper 一定要用 *args 和 **kwargs 透传不要预设被装饰函数的签名。我见过有人写 wrapper(a, b, c) 去装饰一个只需要两个参数的函数结果一调用就直接 TypeError。装饰器的价值就在于透明包装原函数长什么样包装后还长什么样只是在执行前后多了一段逻辑。另外装饰器的配置尽量用函数参数来传递不要依赖全局变量。全局配置会让装饰器的行为难以预测尤其是在测试和并行场景下——你改了一个全局变量所有用了这个装饰器的函数行为全变了排查起来非常痛苦。我一般会把配置参数都设计成带默认值既方便调用方按需覆盖又不会让使用成本变高。6.2 装饰器的性能开销任何装饰器都会带来一层额外的函数调用开销。大多数业务场景里这个开销可以忽略不计但如果装饰器用在高频热路径上比如一个被调用百万次、本身执行又极快的短函数每次多一次函数调用、一次参数解包性能影响就会显现出来。我的经验是先测再优化。用 time.perf_counter 对比装饰前后的耗时确认瓶颈确实在装饰器开销上再动手。如果确实是瓶颈有几个方向可以考虑减少装饰器内部的操作比如把日志级别判断提前到装饰器创建时装饰器里不要做重量级操作比如每次调用都创建对象、打开文件对极端场景可以只在外部入口用装饰器内部循环保持朴素别让装饰器在循环里反复叠层。装饰器是给人便利的不是用来惩罚性能的。6.3 什么情况下不要用装饰器不是所有代码都适合装饰器。如果一个“装饰器”需要大量配置、大量分支逻辑、还得访问被装饰函数内部的局部变量那它可能已经超出了装饰器的适用范围应该改成显式的函数调用或者用上下文管理器来组织。我个人判断是否该用装饰器有三条标准第一逻辑是否足够通用——如果这个逻辑只服务一个函数直接写在函数内部更直接装饰器反而增加了跳跃成本第二是否保持透明——如果装饰器改变了函数的签名、返回值类型、异常类型那它就是在“意外地改变行为”很容易坑到调用方这种装饰器不如不用第三是否容易测试——装饰器嵌套超过两层我一般会重新考虑设计。代码是给人读的装饰器的“魔法感”只有在逻辑清晰的前提下才等于“优雅”否则就是“迷惑”。我在实际项目里踩过不少装饰器的坑最深的一次是给一个老项目统一加超时装饰器结果在 Windows 开发机上全部崩溃排查了好久才发现是 SIGALRM 的平台限制问题。从那以后我养成了一个习惯任何装饰器写完之后先拿三个测试用例验证——原函数元信息是否保留、返回值是否原样透传、异常是否原样抛出。这三关过了装饰器基本就稳了。最后再分享一个小技巧如果你在调试一个被装饰的函数想看看它最初长什么样可以用 func.wrapped前提是加上了 functools.wraps。很多棘手的堆栈问题靠这一招就能快速定位到真正的原始函数。装饰器不是魔法它只是一个被语法糖包装起来的高阶函数理解了它的本质你也能写出让别人觉得“优雅”的代码。