如果只让我推荐一个“学会了能立刻提升代码品质”的 Python 特性我会毫不犹豫说装饰器。不因为语法看着高级而是它解决的恰恰是真实项目里最普遍也最头疼的问题——横切逻辑日志、鉴权、重试、缓存和业务逻辑纠缠不清。前阵子我重构一个内部告警服务十几个函数里有大量重复的“计时、异常重试、权限校验”重构后全改成装饰器业务函数平均从六七十行缩到十行以内。这篇文章我打算把装饰器从原理到实战完整拆一遍重点讲清楚它背后的闭包机制、语法糖执行链路然后给出可以直接抄的线上级组件代码最后把我这些年踩过的坑一条条列出来。适合所有写过 Python 基础函数的同学尤其是想在项目里把装饰器用对而不是用花了的读者。1. 先说清楚装饰器到底解决什么问题1.1 从需求反推装饰器的价值不聊语法之前先看一个场景。假设有一个查询用户信息的函数def fetch_user(user_id): result {user_id: user_id, name: 张三} return result需求来了要记录每次查询的耗时失败了要重试三次用户没权限要拒绝访问。如果直接在函数体里加逻辑代码会变成什么样加日志、加 try/except、加权限判断然后第二个函数做同样的事继续复制粘贴。这就是业内常说的“横切关注点严重侵入业务函数”读代码的人根本分不清哪些是业务规则、哪些是通用逻辑。装饰器的核心价值在于把这两类逻辑分开通用逻辑抽成“包装器”通过语法糖套在业务函数外面业务函数内部只保留真正跟业务相关的东西。我用一个不严谨但好记的类比装饰器像餐馆的外卖包装盒厨房负责炒菜包装盒负责保温、防洒、贴订单号。菜还是那道菜但外面多了一层统一处理的能力。你在项目里能看到的鉴权装饰器login_required、缓存装饰器lru_cache、路由注册装饰器app.route全部是同一套思想。1.2 函数是一等公民闭包是装饰器的地基想用对装饰器必须先接受三个事实第一Python 里函数是对象。它可以被赋值给变量、塞进列表、作为参数传给其他函数也可以作为返回值返回。第二函数可以嵌套定义。外层函数里可以再定义一个内层函数。第三内层函数能引用外层函数里的变量即使外层函数已经执行完毕返回了。这个被捕捉的“外层变量内层函数”组合就叫闭包。来看一段最典型的闭包演示代码def outer(x): def inner(y): return x y return inner add_5 outer(5) print(add_5(10)) # 15outer(5)执行完后局部变量x5按理说应该被回收了但因为inner还在引用它Python 会把x保存到一个叫 “cell” 的独立空间里。所以后面每次调用add_5它都能记得x5。装饰器就是靠这个机制“记住”被包装的原始函数。理解了闭包装饰器的本质就浮出水面了装饰器本身就是一个“接收函数、返回函数”的函数。原函数被包进一个闭包里外面加一层通用逻辑被包装后的函数仍然可以被正常调用只是它“带着皮肤”活了。2. 装饰器的核心原理语法糖背后的执行链路2.1 一个最简单的装饰器手把手拆开看先不用符号用手动包装的方式写一个最简单的装饰器def my_decorator(func): def wrapper(*args, **kwargs): print(调用前统一记录日志) result func(*args, **kwargs) print(调用后统计算法耗时) return result return wrapper def say_hello(): print(hello) say_hello my_decorator(say_hello)这里做了三件事把原始函数say_hello当作参数传给my_decoratormy_decorator内部定义wrapper在调用原始函数前后插入额外逻辑最终把wrapper返回给say_hello。从此以后我们调用的say_hello其实已经不是原来那个函数了而是披着原始函数外衣的wrapper原始函数保留在闭包里随时可以被调用。语法就是上面过程的简化写法my_decorator def say_hello(): print(hello)它和手动写法完全等价就是say_hello my_decorator(say_hello)的语法糖。但这里有个非常容易忽略的点装饰器在被装饰函数定义时就执行了不是在函数被调用时才执行。如果你在装饰器函数体里放一句print(装饰器开始包装)模块导入时这句话就会打印出来。这个特性本身不是坑但一旦装饰器里有昂贵的初始化逻辑就会直接影响模块导入性能后面避坑部分我再详细说。wrapper用*args, **kwargs接收任意参数再原样传给原始函数这样装饰器对参数个数完全不敏感这也是通用装饰器的标准写法。2.2 functools.wraps 不是可选项而是必选项wrapper有一个很隐蔽的问题它把原始函数的所有元信息都弄丢了。看下面这个例子def my_decorator(func): def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper my_decorator def get_user(): 根据ID查询用户信息 pass print(get_user.__name__) # wrapper print(get_user.__doc__) # None__name__变成了wrapper__doc__变成了None。听起来只是打印时不好看实际影响远不止IDE 悬停提示会显示错误的函数名基于__name__做监控统计的系统会把所有接口统计成同一个名字日志、单元测试、自动化文档工具都会跟着遭殃。标准解法是加functools.wraps(func)import functools def my_decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapperfunctools.wraps本质上是一个装饰器它调用functools.update_wrapper把被包装函数的__module__、__name__、__qualname__、__doc__、__annotations__复制到wrapper上同时给wrapper设置一个__wrapped__属性指向原始函数。有了__wrapped__调试时用inspect.unwrap就能一层层剥开包装壳拿到最初那个函数。所以我的习惯是每写一个函数装饰器第一行就写functools.wraps(func)没有例外。这里还藏着一个细节update_wrapper会默认把wrapper.__dict__更新成func.__dict__的浅拷贝。如果wrapper上需要挂自己的属性比如计数器直接给wrapper.calls赋值有可能覆盖原函数已有属性遇到这种场景需要用update_wrapper(wrapper, func, updated())控制不更新__dict__。2.3 带参数的装饰器三层嵌套的逻辑闭环如果装饰器本身就想要参数比如“重试三次”“延时一秒”就需要再包一层。以重试为例import time import functools def retry(max_attempts3, delay0.5): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for attempt in range(1, max_attempts 1): try: return func(*args, **kwargs) except Exception: if attempt max_attempts: raise time.sleep(delay) return wrapper return decorator retry(max_attempts5, delay0.1) def call_api(): pass很多人一开始被三层嵌套绕晕我提供一个记忆方法每一层接收的东西不一样。最外层接收装饰器参数比如重试次数中间层接收要包装的函数最内层接收函数被调用时传入的实参。执行过程拆开看是这样的retry(max_attempts5, delay0.1)先执行返回decoratordecorator自动把call_api传给decorator返回wrapper调用call_api()时执行wrapper内部按需调用原始函数。写带参装饰器最常犯的错就是漏掉一层 return。如果retry直接返回wrapper而不是decorator那么retry(3)里的retry(3)就变成了“接收被装饰函数”的那一层可实际上传给它的是一个整数运行直接报TypeError。遇到这种报错先别慌检查一下层级是不是少了。3. 实战写一套可复用的线上级装饰器组件3.1 先定需求日志、重试、带过期策略的缓存接下来我带着你做一套可以直接搬到项目里用的组件场景定为一个服务需要调用第三方天气 API按城市代码查询实时温度。三个要求很现实——每次调用都要有耗时日志遇到网络异常自动重试三次每次间隔 0.2 秒同一个城市在 5 分钟内不要重复请求直接返回缓存。这三个需求非常适合用装饰器实现而且能体现出装饰器“组合”的价值。核心业务函数保持极简def fetch_weather(city_code): # 假设这里真的在请求第三方接口 return {city: city_code, temperature: 25}我们不给fetch_weather里加任何一句和日志、重试、缓存有关的东西所有横切逻辑全部用装饰器叠加。3.2 完整实现与关键参数设计先写日志装饰器这是最基础也最常用的一类import functools import logging import time logger logging.getLogger(__name__) def log_execution(levellogging.INFO): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.perf_counter() try: result func(*args, **kwargs) return result finally: cost time.perf_counter() - start logger.log(level, f{func.__name__} 耗时 {cost:.4f}s) return wrapper return decorator这里有两个细节值得说。一个是time.perf_counter()而不是time.time()因为perf_counter专门用来测极短的耗时差受系统时间跳变影响小得多。另一个是用try/finally而不是在正常 return 后再写计时这样函数抛异常时也能记录耗时。再看重试装饰器def retry(max_attempts3, delay0.5, exceptions(Exception,)): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for attempt in range(1, max_attempts 1): try: return func(*args, **kwargs) except exceptions: if attempt max_attempts: raise time.sleep(delay) return wrapper return decoratorexceptions参数很重要它决定哪些异常值得重试。默认值(Exception,)看起来方便实际会让“参数校验错误”这类不值得重试的异常也被重试白等几秒。我更推荐调用方显式传入(ConnectionError, TimeoutError)。然后是带过期时间的缓存装饰器import threading def cache_with_ttl(ttl_seconds300): cache {} lock threading.Lock() def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): key (func.__name__, args, tuple(sorted(kwargs.items()))) now time.time() with lock: cached cache.get(key) if cached and now - cached[time] ttl_seconds: return cached[value] result func(*args, **kwargs) with lock: cache[key] {value: result, time: time.time()} return result return wrapper return decorator这里把cache和lock放在decorator外层意味着同一装饰器包装的所有函数共享一份缓存。不同函数之间用key里的func.__name__区分避免冲突。加锁是为了防止多线程下出现缓存击穿——多个线程同时发现缓存失效然后同时去调真实函数。3.3 组合顺序装饰器的洋葱模型怎么看、怎么验证三个装饰器都定义好了使用方式是这样的log_execution(levellogging.INFO) retry(max_attempts3, delay0.2, exceptions(ConnectionError, TimeoutError)) cache_with_ttl(ttl_seconds300) def fetch_weather(city_code): return {city: city_code, temperature: 25}新手第一次看到这种写法会问三个装饰器的执行顺序到底怎么算规则一句话就能说完叠加装饰器的包装顺序从下往上实际调用时的进出顺序从上往下。也就是说cache_with_ttl最先执行包装log_execution最后执行包装调用fetch_weather()时先经过log_execution的wrapper然后进入retry的wrapper再进入cache_with_ttl的wrapper最后才到达原始函数。用三个带打印语句的装饰器可以直观验证def a(func): print(a 开始包装) def wrapper(*args, **kwargs): print(a wrapper before) r func(*args, **kwargs) print(a wrapper after) return r return wrapper def b(func): print(b 开始包装) def wrapper(*args, **kwargs): print(b wrapper before) r func(*args, **kwargs) print(b wrapper after) return r return wrapper a b def f(): print(f 执行)定义阶段输出先看到b 开始包装再看到a 开始包装因为包装从下往上。调用阶段则是a wrapper before、b wrapper before、f 执行、b wrapper after、a wrapper after。这个“洋葱模型”弄明白后你就能预判装饰器组合后的真实行为。回到天气需求上我的顺序逻辑是先请求远程接口并用缓存挡住重复调用再对这个可能失败的调用做重试最后才记录整体耗时。如果把log放到最内层日志只记录原始函数的耗时不计重试时间统计口径就变了。4. 避坑指南这些年我在装饰器上踩过的坑4.1 元信息丢失引发的“幽灵 Bug”早年我在给一个服务加接口耗时统计时给所有 API 处理函数都加了一个自定义装饰器结果第二天看监控报表所有接口的名字都变成了wrapper数据全部混在一起。排查了大半天才意识到是装饰器里的wrapper把__name__覆盖了。这类问题在线上非常隐蔽因为代码运行不报错只是统计数据、日志、权限校验这些依赖函数名的系统会悄悄出错。从此我给自己立了条规矩任何函数装饰器都必须加functools.wraps(func)没有“这个装饰器很简单所以不用加”的例外。如果你在检查别人代码看到装饰器里没有wraps哪怕功能再简单也建议补上早晚会用到元信息。4.2 装饰器叠加顺序导致参数错位装饰器叠加不只是执行顺序问题还可能改变传给原始函数的参数。我见过一个真实案例开发者在所有接口上叠加了authenticate和get_user_info前一个装饰器把请求里的 token 解析成用户对象并用kwargs[user] user交给下一个装饰器后一个装饰器按kwargs[user]做操作。但因为顺序写反了authenticate跑到内层等get_user_info执行时kwargs里根本没有user接口 500 得莫名其妙。这种踩坑的本质是装饰器之间隐式约定了参数格式。我的建议是如果一组装饰器需要互相传递数据不要依赖 kwargs 里凭空出现的键最好用一个显式的上下文对象或者干脆把这种“强耦合”的多层装饰器合并成一个减少隐式契约。能合并不合并叠加越多理解成本越高。4.3 inspect.signature 的隐性坑参数签名不会自动保留就算加了functools.wrapswrapper的运行时签名依然还是(*args, **kwargs)。很多 Web 框架会通过inspect.signature读取处理函数的参数来完成依赖注入比如 FastAPI 要靠参数名识别Query、Body。如果框架内部没有做follow_wrapped处理而你又在它上面套了一层自定义装饰器就有可能出现“参数绑定失效”的怪问题。遇到这类问题的排查思路有几个第一优先确认框架是否支持通过__wrapped__找到原函数有的框架支持那wraps就够用了第二使用inspect.signature(func, follow_wrappedTrue)手动解包第三如果自己写库可考虑使用 Python 3.10 后的typing.ParamSpec做静态标注但运行时签名仍需要配合setattr(g[signature], ...)之类的手段才能真正改变inspect.signature的输出。说这些是想提醒装饰器在业务代码里用没什么问题但一旦你的装饰器会被框架消费就要对签名保留多留个心眼。4.4 类装饰器与装饰器类一字之差两个世界“类装饰器”和“装饰器类”是两个很容易被混为一谈的概念写法完全不同。类装饰器作用于“类”本身最常见的例子是单例def singleton(cls): instances {} functools.wraps(cls) def get_instance(*args, **kwargs): if cls not in instances: instances[cls] cls(*args, **kwargs) return instances[cls] return get_instance singleton class Config: pass注意这里有个隐藏大坑singleton之后Config不再是一个类而是一个函数。isinstance(obj, Config)会报错依赖Config类型的类型注解也会失效。类被装饰成函数类型语义变了这是“类装饰器返回函数”最需要警惕的点。装饰器类则是实现__call__的类用来装饰“函数”。它特别适合需要保存状态的函数装饰器class CountCalls: def __init__(self, func): functools.update_wrapper(self, func) self.func func self.calls 0 def __call__(self, *args, **kwargs): self.calls 1 return self.func(*args, **kwargs)两者到底选哪个我个人的经验是如果你只是想给类加全局注册逻辑路由表、插件注册、ORM模型登记用类装饰器但尽量返回一个新类而不是函数如果你想给函数包装并需要持久状态用装饰器类因为它天然支持状态属性。判断口诀——看被装饰对象是“类”还是“函数”决定了你写的到底是哪一类。4.5 性能陷阱装饰器在导入期执行会拖慢整个模块文章开头提到装饰器在被装饰函数定义时就会执行。很多人对此没有概念于是会在装饰器里顺手做一些昂贵操作比如加载模型文件、初始化数据库连接池。结果就是一个函数被装饰模块导入变慢几秒几十个函数被装饰整个服务启动时间直接膨胀。这种“导入期连锁反应”在大型项目里最隐蔽因为启动缓慢很难直接怀疑到某个装饰器上。还有一个性能层面的影响每次函数调用都会多一次wrapper的函数调用开销。单看一次调用可能只有几十纳秒到微秒级但如果被装饰函数在热循环里被调用几百万次这个差距就很可观。真遇到这种场景建议用cProfile先定位热点如果确实是装饰器造成的可以考虑把装饰器内部逻辑手动展开到热路径函数里保留装饰器给冷接口用。另外调试装饰器代码时堆栈会变深报错信息里夹着一层层wrapper第一次看会有点崩溃这是正常现象不是代码坏了。最后分享一个我现在的固定习惯单条装饰器只负责一件事语义用动词命名比如retry、log_execution、cache_with_ttl避免出现一个名叫handle_everything的万能装饰器每条都加functools.wraps凡是装饰器之间需要传递数据的写清楚参数契约并注释在装饰器定义处。按这几条约束下来装饰器在项目里就会成为非常可靠的抽象工具而不是让人头疼的魔法。