Python写久了估计每个人都会撞上同一类尴尬日志记录、耗时统计、权限校验这些公共逻辑散落在二三十个函数里改一次需求就要把所有地方翻一遍。装饰器Decorator就是专门解决这件事的Python原生特性——不用改原函数一行代码就能把公共逻辑“贴”上去。我以前一直觉得装饰器挺玄乎像是某种“魔法”直到有回接手一个入口函数上百个、需要统一鉴权的后端项目才回过味来没有装饰器那些入口函数得逐个改到天亮有了装饰器一个注解就把鉴权逻辑全部接管。所谓“让代码更优雅”其实不是修辞是装饰器天然适合处理这类“横切”需求。这篇文章适合已经掌握Python基础语法、开始关心代码结构组织的读者。我会先用三个底层概念把装饰器彻底拆开再带大家从零手写无参、带参装饰器然后结合日志、缓存、鉴权、重试等实战场景给可直接复用的代码最后把踩过的坑整理成一份排查速查表。全文都是能直接落到项目里的内容不绕弯子。1. 装饰器的底层机制函数、闭包与语法糖1.1 为什么说“函数也是对象”是装饰器的地基先做一个思维切换Python里的def不是像C语言那样“定义一段固定代码”而是在执行时创建了一个函数对象绑定到函数名上。就好比x 1是把整数对象绑定到xdef greet(): ...是把函数对象绑定到greet。这带来三个非常实用的能力def greet(name): return Hello, name # 1. 函数可以赋值给其他变量 say_hello greet print(say_hello(小李)) # Hello, 小李 # 2. 函数可以作为参数传给另一个函数 def call_twice(func, arg): return func(func(arg)) print(call_twice(greet, 小李)) # Hello, Hello, 小李 # 3. 函数可以嵌套定义并返回 def make_prefix(prefix): def inner(name): return prefix name return inner注意第二步里的call_twice(greet, 小李)我们并没有修改greet的任何代码却让它的结果又被greet自己处理了一遍。装饰器的思路和这个完全一致在函数外部包装一层逻辑不碰原函数内部。这也是Python适合做框架和元编程的核心原因之一——函数本身可以被传递、被组合、被替换。这里有个极容易踩的细节传入函数时不能带括号。greet是函数对象greet()才是调用。如果写call_twice(greet(), 小李)代码会先执行greet(小李)再把它的返回值传出去行为就完全变了。看装饰器源码时一旦看到“函数名后面有没有括号”脑子要立刻区分出“这是在传对象”还是“这是在调用”。1.2 闭包让内层函数携带外层变量的机制装饰器的第二个地基是闭包Closure。这个概念听起来唬人其实一句话能说清楚外层函数里定义内层函数内层函数引用了外层函数的局部变量然后外层函数把内层函数返回返回之后那些“本该被销毁”的局部变量并没有消失而是被内层函数随身携带了。def outer(x): def inner(y): return x y return inner add5 outer(5) print(add5(10)) # 15outer(5)执行完毕局部变量x按理说应该被回收但因为inner引用了它Python就把这个变量打包进函数对象的闭包环境里保存下来。add5(10)执行时inner能准确读出当年那个x的值是5。想看得更具体可以在解释器里运行add5.__closure__会看到闭包单元格里存放的变量内容。闭包的价值并不是“让变量活得久一点”而是让“函数对象可以携带一份私有环境数据”。装饰器要做的就是把原函数和附加逻辑捆绑在一起闭包正是那根绑绳。任何一个装饰器拆开来看最核心的部分都是一个闭包外层函数接收原函数内层函数记录附加逻辑最后返回内层函数。1.3 装饰器语法糖的本质是把函数套进函数把前两节拼起来装饰器的秘密就没了。装饰器本质上是一个可调用对象它接收一个函数或类作为入参返回一个新函数或类。看一段最朴素的写法def my_decorator(func): def wrapper(): print(调用前) func() print(调用后) return wrapper my_decorator def hello(): print(Hello)这里的my_decorator只是语法糖完全等价于def hello(): print(Hello) hello my_decorator(hello)关键理解是装饰器并没有“修改”原函数它创建了一个新函数wrapper然后把这个新函数重新绑定到hello这个名字上。之后每次调用hello()实际执行的都是wrapper()再由wrapper内部去调用原来的函数对象。想通这一步很多问题就迎刃而解。比如你会问为什么装饰器内部一定要用*args, **kwargs因为wrapper在编写时并不知道原函数有多少个参数、是位置参数还是关键字参数只有用*args, **kwargs才能透明地把调用方传来的参数原封不动地转发给原函数。这个设计让同一个装饰器既能装饰无参函数也能装饰有一堆参数的函数。2. 从零手写装饰器无参、带参、保元信息2.1 5分钟写出第一个能用装饰器直接上一个能运行的版本给函数加上调用时间记录import time def log_time(func): def wrapper(*args, **kwargs): print(f调用时间: {time.strftime(%Y-%m-%d %H:%M:%S)}) result func(*args, **kwargs) print(f调用结束: {time.strftime(%Y-%m-%d %H:%M:%S)}) return result return wrapper log_time def add(a, b): return a b print(add(1, 2))三个细节特别值得说result func(*args, **kwargs)是灵魂一行。原函数add算出了3wrapper必须把返回值继续往上抛如果这里漏写return result外部拿到的一律是None。新手写装饰器返回值丢失十有八九是这个原因。*args收集所有位置参数**kwargs收集所有关键字参数再把它们原样展开传给原函数。这样原函数不用做任何改动就能适应任意调用方式。装饰后的add变量绑定的其实已经是wrapper对象原函数对象还静静躺在wrapper的内部引用里。2.2 不要丢掉函数身份的functools.wraps直接这样用一段时间你会撞上一个不大不小却很烦人的问题原本函数的__name__和__doc__都被覆盖了。log_time def add(a, b): 两数相加 return a b print(add.__name__) # wrapper print(add.__doc__) # None函数名丢失日志输出就分不清是哪条业务在跑文档注释丢失help()和IDE提示全废。某些框架在注册路由或任务队列时依赖函数名名字变成wrapper之后路由直接对不上。标准库functools里的wraps就是为这个问题准备的import functools def log_time(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.time() result func(*args, **kwargs) print(f耗时: {time.time() - start:.4f}s) return result return wrapper加上functools.wraps(func)之后add.__name__恢复成addadd.__doc__也回来了。它还悄悄把原函数对象存到了wrapper.__wrapped__属性里对后续调试非常有用。我的经验很简单所有自写装饰器内层函数统一从第一行就加functools.wraps(func)不要等出了问题再补救。2.3 带参数装饰器三层嵌套结构拆解有时装饰器需要自己的参数例如retry(times3)。这里的关键判断是retry(times3)并不是直接把retry当装饰器用而是先执行retry(times3)把它的返回值拿来做真正的装饰器。所以带参装饰器至少要写三层import functools def retry(times3): def decorator(func): # 真正接收函数的装饰器 functools.wraps(func) def wrapper(*args, **kwargs): # 包装原函数 for attempt in range(times): try: return func(*args, **kwargs) except Exception: if attempt times - 1: raise print(f第{attempt 1}次失败重试中...) return None return wrapper return decorator调用链路用一句话概括fetch_data retry(times3)(fetch_data)先调用retry(times3)拿到decorator再对fetch_data调用decorator拿到wrapper最后把wrapper绑回fetch_data。三个函数各司其职第一层retry(times3)接收装饰器自己的参数返回decorator。第二层decorator(func)接收被装饰函数返回wrapper。第三层wrapper(*args, **kwargs)接收原函数运行时的参数内部调用原函数。这种嵌套是新手最容易翻车的结构。如果写少了一层运行时经常报TypeError: str object is not callable。看到这类错误先数一遍你的装饰器是不是三层。3. 实战场景日志、缓存、鉴权、重试3.1 日志装饰器记录入参出参与耗时生产环境里出现频率最高的装饰器大概就是日志装饰器。它可以把“函数被调用、参数是什么、返回了什么、跑了多久”全部集中记录业务函数里一行日志都不用写。import logging import time import functools logging.basicConfig(levellogging.INFO) def log_call(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.perf_counter() result func(*args, **kwargs) cost time.perf_counter() - start logging.info( 函数 %s 被调用, 入参 %r %r, 返回值 %r, 耗时 %.4fs, func.__name__, args, kwargs, result, cost ) return result return wrapper两个实用细节一是计时要优先用time.perf_counter()而不是time.time()perf_counter是单调时钟不受系统时间调整影响专门用来测量时间间隔二是对敏感参数要脱敏登录接口如果直接打印kwargs账号密码就进了日志。常见做法是复制一份kwargs把password、token这些字段替换成***再打印。还有一点比实现更重要的经验日志装饰器的定位是“轻量”。如果每次调用都做大量字符串拼接、写文件、同步IO装饰器本身反而成了性能瓶颈。线上环境我一般只打印关键参数和耗时或者给装饰器加一个开关测试环境开完整参数生产环境只打耗时。3.2 缓存装饰器手写缓存到lru_cache有的函数用相同参数重复计算结果每次都从零算一遍很浪费。装饰器做结果缓存非常自然。先写一个最简版本import functools def memoize(func): cache {} functools.wraps(func) def wrapper(*args): if args not in cache: cache[args] func(*args) return cache[args] return wrapper memoize def fib(n): if n 2: return n return fib(n - 1) fib(n - 2)这个例子很能说明问题。普通递归求fib(35)要跑好几秒加上缓存之后几乎瞬间出结果原因是同一个fib(n)在没有缓存时会被重复计算成千上万次。手写缓存的思路简单但有两个明显弱点一是参数必须是可哈希类型传列表、字典进去直接报错二是缓存无限增长函数调用种类一多就会吃满内存。实际项目我更推荐直接用标准库的functools.lru_cachefunctools.lru_cache(maxsize128, typedFalse) def expensive_function(x): ...lru_cache采用“最近最少使用”淘汰策略缓存容量到上限后最久没被使用的条目会被自动清掉非常适合热点集中、结果集有限的场景。typedTrue时1和1.0会被当成两个参数分别缓存如果函数参数经常是新建的对象缓存永远命中不了这点最容易踩——你传给函数的参数如果是每次新建的字典或对象再大的缓存也没用。所以使用lru_cache时尽量让参数落在可哈希且重复率高的类型上。3.3 鉴权与参数校验装饰器怎么设计Web后端里最常见的“横切逻辑”就是登录态校验。普通写法是每个接口开头都写一遍“取用户、判空、抛异常”装饰器可以把这段完全抽出来def require_login(func): functools.wraps(func) def wrapper(*args, **kwargs): user get_current_user() if user is None: raise PermissionError(用户未登录) return func(*args, **kwargs) return wrapper require_login def get_profile(user_id): ...这种设计有一个容易被忽略的好处业务函数get_profile只管业务它根本不知道“自己被鉴权过”。测试时想绕开鉴权测纯业务直接调用get_profile.__wrapped__就行线上注册接口表里挂载的则是包装后的版本。分层干净测试也方便。参数校验同样可以做成装饰器但我要给一个反向提醒参数校验型装饰器不要滥用。如果每个函数都套一层校验装饰器叠加多了读代码的人反而无法一眼看出这个函数的约束边界。复杂的约束我通常放在主函数内部显式校验或者用数据校验库统一处理装饰器只处理那些“横切面”非常明确的规则。3.4 重试装饰器带抖动和异常过滤网络超时、数据库连接短暂抖动这类问题适合用重试装饰器统一处理。可以在基础版本上做两层增强限定重试的异常类型以及设置重试间隔。import functools import time import random def retry(exceptionsException, times3, delay0.5): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for attempt in range(times): try: return func(*args, **kwargs) except exceptions: if attempt times - 1: raise time.sleep(delay random.uniform(0, 0.5)) return wrapper return decorator retry(exceptions(TimeoutError, ConnectionError), times3, delay1) def fetch_remote(): ...重试不是无脑重试。几个原则要刻在脑子里重试间隔要带随机抖动否则多个进程同时失败后同时重试会把下游服务再次打崩。只对瞬时故障重试。参数错误、业务校验不通过重试多少次都没意义反而把问题掩盖了。一定要考虑幂等性。写操作如果重复执行会产生重复数据不是所有操作都适合无脑重试。必要时要让操作本身支持幂等比如携带唯一请求ID。4. 进阶玩法类装饰器、叠加顺序、内置装饰器4.1 类装饰器可保存调用次数函数装饰器依赖闭包保存状态写法够用但表达状态时不够直白。如果装饰器要记录状态用类实现会更清晰。一个常见例子是统计函数被调用了多少次import functools 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) CountCalls def greet(name): return fHello, {name} print(greet(某同学)) print(greet(另一个人)) print(greet.calls) # 2这里的机制是CountCalls把greet从“函数对象”替换成了一个CountCalls实例。之后每次greet(...)其实就是调用实例的__call__方法。实例天然有字段所以calls计数就存在实例里不需要额外管理闭包变量。注意第一行写了functools.update_wrapper(self, func)作用等价于函数装饰器里的functools.wraps(func)让greet.__name__这些元信息保持一致。类装饰器还可以用来装饰类本身。比如给一个类统一加上__repr__def add_repr(cls): def __repr__(self): attrs , .join(f{k}{v} for k, v in vars(self).items()) return f{cls.__name__}({attrs}) cls.__repr__ __repr__ return cls add_repr class Point: def __init__(self, x, y): self.x x self.y y p Point(3, 4) print(p) # Point(x3, y4)这种用法背后的原理同样是“Python类也是对象方法可以在运行时动态修改”。装饰器的威力并不仅限于函数。4.2 多个装饰器的执行顺序一个函数挂多个装饰器很常见顺序一旦搞错线上问题特别难排查。看这个例子a b def f(): ...它等价于f a(b(f))要分两个阶段理解装饰阶段从下往上。先执行b(f)得到包装函数再把这个包装函数传给a。调用阶段从上往下。调用f()时先进入a的包装逻辑再进入b的包装逻辑最后才执行原函数。用日志装饰器和缓存装饰器叠加演示log_call functools.lru_cache(maxsize128) def slow_task(x): ...执行第一次时顺序是log_call记录开始 →lru_cache查缓存没有命中 → 原函数计算 →lru_cache存缓存 →log_call记录结束。第二次相同参数进来时lru_cache直接命中原函数不再执行但log_call仍会记录进出日志只是耗时接近0。实战排错时如果发现缓存明明命中了日志却显示原函数又被执行了一遍基本可以断定是装饰器顺序放反了。哪类逻辑要包在外面、哪类贴近原函数判断标准是越靠外层的装饰器越先接管调用、越后收尾越靠内层的装饰器越贴近真实业务。4.3 property、classmethod、staticmethod一次讲完讲完自定义装饰器不能漏掉Python标准库内置的几个装饰器它们同样遵循“不改函数内部逻辑、附加行为”的思路。property把一个方法变成只读属性class Circle: def __init__(self, radius): self._radius radius property def area(self): return 3.14159 * self._radius ** 2 c Circle(2) print(c.area) # 12.56636不是 c.area()调用方不需要知道area是算出来的还是存着的。将来内部实现改了调用方代码不用动。property还可以配合area.setter写出带校验的属性赋值逻辑这是Python实现数据封装时非常顺手的一套工具。classmethod绑定的是类而不是实例常用于实现替代构造函数。staticmethod则把一个方法变成普通函数纯粹为了组织代码空间。这三个内置装饰器本身不复杂但它们和自定义装饰器一样解决的都是“在不破坏原函数结构的前提下附加行为”这件事。5. 常见坑、排查技巧与速查表5.1 忘记wraps的“隐形坑”装饰器写完能跑很多人就以为结束了。真正出问题往往是在后续维护阶段日志里看不到业务函数名、help()不显示文档、某些框架注册路由时发现函数名对不上。这些都是没加functools.wraps(func)埋下的雷。解法没有技巧就是给所有装饰器的内层函数统一加上functools.wraps(func)形成肌肉记忆。5.2 装饰器参数错位与“少一层”错误带参装饰器写成两层导致的问题最典型报错是TypeError: decorator() missing 1 required positional argument: func。本质原因是你在代码里写了decorator(参数)Python会先执行decorator(参数)然后把返回结果当装饰器继续接收被装饰函数如果你的decorator本身设计成直接接收函数那第一轮收到的就是字符串自然跑偏。排查时先确认装饰器定义是不是“参数层→装饰器层→wrapper层”三层结构再确认调用处是不是retry(times3)这种带括号写法。5.3 叠加顺序弄反的排查方法多个装饰器叠加顺序错误最常见的表现是日志顺序违背直觉。比如鉴权装饰器放在日志装饰器的外层未登录请求的日志里就会出现“进入业务函数”这类假象误导排查方向。遇到这种问题先把叠加的装饰器逐个拆开在脑子里或者草稿纸上写出等价代码func a(b(func))然后顺着调用链检查谁先进入、谁先退出。多拆几次顺序感自然就建立起来了。5.4 调试装饰器用对__wrapped__和签名工具functools.wraps有一个隐藏福利被装饰的原函数会被保存到wrapper.__wrapped__属性里。调试时想绕开装饰器直接看原函数行为直接在调试器里执行func.__wrapped__即可。inspect.signature()在用了wraps之后也能拿到原始函数签名这对写文档、做参数解析都有帮助。如果装饰器嵌套层数太多我的建议是暂时把装饰器拆成最小可复现场景一个一个加逻辑别在层层嵌套里盲目改代码。5.5 装饰器问题速查表我把实际遇到过的典型问题整理成一张表排错时直接对照查阅问题现象可能原因解决思路函数名变成了wrapper没加functools.wraps在wrapper上加functools.wraps(func)原函数返回值丢失wrapper漏写returnwrapper内必须return func(*args, **kwargs)带参数装饰器报not callable装饰器少了一层嵌套确认为参数层→decorator→wrapper三层结构日志重复打印同一装饰器被重复应用检查叠加装饰器是否有重复版本缓存不生效参数不可哈希或每次新建对象改用可哈希参数或用lru_cache的typed参数IDE不显示原函数签名未使用functools.wraps统一加wraps同时保留__wrapped__一句话的收尾技巧送给大家装饰器本质就是一个返回函数的高阶函数真正写起来之所以容易乱是因为嵌套层数多、职责不清。只要画清楚“谁接收参数、谁接收函数、谁接收业务参数”这三层的职责任何复杂装饰器都能一步步拆明白。