在Python里“装饰器”是让人又爱又恨的东西。爱它是因为它能把日志、鉴权、重试、缓存这些横切逻辑从业务代码里剥离出来让核心函数干净得像刚洗过的白衬衫恨它是因为一旦拆开符号你会发现自己突然站在了语法糖和元编程的分界线上——装饰器不是一个单纯的“语法特性”它是一扇门。推开这扇门函数不再是写死的代码块而是可以被包装、被注册、被改写、被注入规则的一等公民。这篇文章不只讲的用法我会从最底层的函数对象说起一路拆到闭包、三层嵌套、类装饰器、参数校验、事件总线和property最后把几个自己实际踩过的坑全部抖出来。适合刚学完Python基础、想真正理解装饰器原理的人也适合写了几年业务代码、但对装饰器依旧只敢“照着抄”的人。1. 装饰器到底是什么从一个最简单的例子开始1.1 先理解函数是一等公民在Python里函数是对象。这五个字是装饰器存在的全部理由。所谓“一等公民”意思是函数能像整数、字符串一样被传递赋值给一个变量、塞进列表、作为参数传给另一个函数、作为返回值从另一个函数里蹦出来。def say_hello(): return hello f say_hello # 函数赋值给变量 print(f.__name__) # say_hello print(f()) # hello def call_twice(func): return func() func() print(call_twice(say_hello)) # hellohello这里没有任何魔法。f只是在名字上绑定了say_hello指向的那个函数对象call_twice接收的也是一个函数对象然后在内部调用它。我们真正操作的是函数对象本身而不是“源代码文本”。这一点为什么重要因为装饰器的本质工作模式是接收一个函数对象对它做一些事情再返回一个函数对象。如果你脑子里没有“函数是对象”这层认知后面看任何装饰器代码都会觉得在变戏法。很多初学者卡在装饰器上并不是卡在语法而是卡在“函数为什么能当作参数传来传去”这个底层前提上。先把这个想明白装饰器等于懂了一半。1.2 手写第一个装饰器先不碰我们先不碰符号完全用手动赋值写一个装饰器。这样能看清它到底做了什么。def my_decorator(func): def wrapper(): print(before calling) result func() print(after calling) return result return wrapper def greet(): print(hi, Im a function) greet my_decorator(greet) # 手动套一层 greet()这段代码做的事情用大白话说就是把原来的greet替换成一个新函数wrapperwrapper在调用前后各打印一行日志然后在中间调用原来的greet。原本函数的逻辑一点没改只是它的上下被加上了额外的行为。拆开来看my_decorator是外层函数接收被装饰函数func它内部定义了一个wrapper这个wrapper通过闭包持有func的引用所以即使在my_decorator返回之后wrapper依然能调用原来的函数。最后外层函数把wrapper返回出去。这就是装饰器的核心结构外层函数接收函数、返回闭包闭包内部调用被装饰函数。1.3 语法糖展开的真相 符号到底做了什么把上面的手动替换改成这样my_decorator def greet(): print(hi, Im a function)符号只是让Python自动执行greet my_decorator(greet)省去手动写那一行赋值。它不引入新的语言机制纯粹是语法糖。这一点非常重要它决定了你调试装饰器时的思路只要心里把装饰器替换成函数 装饰器(函数)一切都能解释。这里顺带回答一个经常被问的问题后面为什么不能直接跟装饰器参数比如retry(3)为什么可以因为后面要求的是一个“装饰器”也就是一个能接收函数并返回函数的对象。retry(3)是先调用retry函数得到的一个“结果”只要这个结果本身也是一个“能接收函数并返回函数”的东西那么retry(3)就能正常工作。这就引出了下一节要说的三层嵌套。2. 带参数的装饰器为什么需要三层嵌套2.1 先从需求说起装饰器要按参数变化大多数真实场景里装饰器不是简单地在函数前后打两行日志而是要按配置变化。比如我想做一个带重试功能的装饰器不同接口的失败重试次数不一样retry(times3) def fetch_data(): ...如果只写一层装饰器retry会把fetch_data本身当作times参数传入结果times变成一个函数对象代码内部一执行range(times)就直接报错。所以带参装饰器必须把“接收参数”和“装饰函数”拆成两步。2.2 三层结构的完整拆解带参数的装饰器标准写法是三层嵌套import time def retry(times, delay0.1): def decorator(func): def wrapper(*args, **kwargs): for i in range(times): try: return func(*args, **kwargs) except Exception as e: if i times - 1: raise time.sleep(delay) return wrapper return decorator retry(times3) def unstable_api(): return ok这里有三层每一层职责不一样retry(times, delay0.1)接收配置参数返回decorator。它存在的意义是让retry(times3)这种语法成立——Python先把retry(times3)计算出一个结果再用这个结果去装饰函数。decorator(func)接收被装饰函数返回wrapper。它是真正意义上的“装饰器”。wrapper(*args, **kwargs)接收被装饰函数的所有实参真正执行重试逻辑。执行顺序是retry(times3)中的retry(times3)先执行返回decorator然后Python把unstable_api传给decorator得到wrapper最后unstable_api这个名字被重新绑定到wrapper上。只要记住这个执行顺序三层嵌套就不再难懂。用生活类比来说三层嵌套就像一个快递代收点。retry是站长负责设定规则收几个件、延误等多久decorator是快递员负责找到对应的包裹你的函数wrapper是拦截员每次取件时都先检查一遍规则再决定放不放行。2.3 functools.wraps 为什么必须加如果你没有做额外处理装饰后的函数会丢掉元数据def deco(func): def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper deco def add(a, b): 求两个数之和 return a b print(add.__name__) # wrapper print(add.__doc__) # None函数名变成wrapper、文档字符串直接丢掉。这在写框架、做序列化、看日志的时候都很难受。functools.wraps就是来解决这个问题的from functools import wraps def deco(func): wraps(func) def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapperwraps(func)会把原函数的__name__、__doc__、__module__、__qualname__等属性复制到wrapper上同时额外设置wrapper.__wrapped__ func。后者在调试和反序列化时有实际用途比如有些测试工具会根据__wrapped__找到原始函数签名。我的建议是以后写所有装饰器第一行wraps(func)直接写上不需要犹豫。它没有性能负担但对代码的可维护性影响极大。很多人写装饰器不挂wraps排查问题时看堆栈里的函数名全是wrapper痛苦得很。这不是风格问题是基本卫生问题。3. 类装饰器用call改变游戏规则3.1 可调用对象类也能当装饰器装饰器不一定要写成函数也可以写成一个类。只要这个类的实例是可调用的——也就是实现了__call__方法——它就能装饰别的函数。类装饰器的写法如下import time class Timer: def __init__(self, func): self.func func def __call__(self, *args, **kwargs): start time.perf_counter() result self.func(*args, **kwargs) elapsed time.perf_counter() - start print(f函数 {self.func.__name__} 耗时 {elapsed:.6f} 秒) return result Timer def slow_thing(): time.sleep(0.2) slow_thing()这里的逻辑和函数装饰器完全一致__init__接收被装饰函数__call__替换原来的调用。因为slow_thing现在实际上是一个Timer实例每次调用都会触发__call__。类装饰器带来的一个明显好处是“状态可以挂在self上”。函数装饰器要用闭包变量才能保存状态类装饰器可以直接用实例属性读起来更直白也更方便后续扩展。3.2 类装饰器保存状态统计调用次数举一个统计函数调用次数的例子class Counter: def __init__(self, func): self.func func self.count 0 self.__name__ func.__name__ def __call__(self, *args, **kwargs): self.count 1 print(f第 {self.count} 次调用) return self.func(*args, **kwargs) Counter def ping(): return pong ping() ping()类装饰器的优势在场景稍微复杂一点的时候会更加明显。比如监控系统想知道某个关键接口被调用了多少次后续可能还需要提供重置计数、查看总数等方法直接在类里加方法就行def reset(self): self.count 0函数装饰器虽然也能通过给wrapper添加属性来实现类似效果但写起来别扭而且属性一多可读性急剧下降。类装饰器把“装饰器本身”变成一个可观察的对象这是它与函数装饰器最本质的差别。3.3 实战场景注册表模式与单例模式先看注册表模式。它不修改函数行为只是把函数登记到某个数据结构里registry {} def register(name): def decorator(func): registry[name] func return func return decorator register(greet_cn) def greet_cn(): print(你好) register(greet_en) def greet_en(): print(hi) print(registry.keys()) # dict_keys([greet_cn, greet_en])这里装饰器返回的还是原函数没有包装但函数被“登记”了。Flask的app.route(/)、Celery的celery.task本质上都是注册表模式——声明式地告诉框架“这个函数是路由”或者“这个函数是定时任务”。业务代码不需要手动往框架里塞东西只需要在定义处打一个标记。单例模式也是装饰器的经典用法def singleton(cls): instances {} def getinstance(*args, **kwargs): if cls not in instances: instances[cls] cls(*args, **kwargs) return instances[cls] return getinstance singleton class Database: def __init__(self, url): self.url url db1 Database(postgres://...) db2 Database(postgres://...) print(db1 is db2) # True装饰器的优雅之处在这里体现得很充分在类的定义处加上singleton所有实例化逻辑自动被接管业务代码完全无感知。这个例子已经有点元编程的味道了——你在“类的创建和获取”链条上插入了一层逻辑不是在改业务数据而是在改对象的行为规则。4. 装饰器与元编程当你开始修改代码本身4.1 什么是元编程装饰器为什么属于它元编程是指编写“操作代码的代码”。普通程序处理数据元程序处理逻辑本身。装饰器就是个典型的元编程工具它拿到的不是业务数据而是一个函数对象并通过包装改变这个函数的调用行为。有人觉得元编程很高深其实日常开发里到处都是。拿property来说class User: def __init__(self, name): self._name name property def name(self): return self._name name.setter def name(self, value): self._name value.strip()你写的是user.name读和写却变成了方法调用。表面看只是语法糖底层却是描述符协议在起作用。property的本质是拦截“属性访问”这个语言级操作然后交给函数执行——这是非常典型的元编程行为。它把属性访问从“直接取字段”改成了“必须经过一段逻辑”。所以我一直把装饰器叫作“跃迁之门”从语法糖这端看它只是符号的缩写从元编程那端看它让你获得了在运行时检查和修改函数对象的能力。4.2 用装饰器做参数校验横切关注点收敛一个很实用又很常见的元编程场景是参数校验。假设服务里有大量接口函数每个函数都要求某些参数不能为Nonefrom functools import wraps def check_not_none(arg_name): def decorator(func): wraps(func) def wrapper(*args, **kwargs): if arg_name in kwargs and kwargs[arg_name] is None: raise ValueError(f参数 {arg_name} 不能为 None) return func(*args, **kwargs) return wrapper return decorator再进一步配合inspect.signature还能做自动类型校验根据函数的类型注解判断是否强制类型转换。这种能力把重复的“防御性检查”从每个函数体里解放出来统一收敛到装饰器里。实际业务中这类横切逻辑非常适合装饰器日志、鉴权、重试、限流、审计、缓存。它们有一个共同点——不关心业务逻辑本身只关心“在调用前后做什么”。把横切关注点和核心业务分离是装饰器最重要的工程价值。4.3 用装饰器构建事件总线声明式编程注册表模式再往前走一步就是事件系统。一个迷你事件总线可以这样实现class EventBus: def __init__(self): self.handlers {} def on(self, event): def decorator(func): self.handlers.setdefault(event, []).append(func) return func return decorator def emit(self, event, *args, **kwargs): for handler in self.handlers.get(event, []): handler(*args, **kwargs) bus EventBus() bus.on(user.login) def handle_login(user, device): print(f{user} 从 {device} 登录了) bus.on(user.logout) def handle_logout(user): print(f{user} 注销了) bus.emit(user.login, 张三, iPhone)用装饰器声明事件处理器业务代码不需要手动注册也不需要关心事件总线的调度逻辑只需要表达意图我是来监听某个事件的。声明式编程带来的可读性提升非常明显。这也从另一个角度说明装饰器已经不只是“包装函数”那么简单而是在搭建框架层的语义。4.4 装饰器的边界与描述符、元类的接壤处装饰器虽然强大但它只是Python元编程的一种手段。它的边界在于它能操作函数或类对象但改不了类本身的创建过程。如果你想让一个类的所有方法在定义时自动加上日志装饰器写起来就很绕。这时应该考虑元类在__new__里遍历类的属性并批量应用装饰器。再比如依赖注入框架里的inject实际实现往往要结合函数签名分析、参数绑定、作用域管理——这些已经完全属于完整的元编程范畴了。理解了这颗边界之后你会开始用“代码可以生成代码、代码可以修改代码”的视角去看Python的一切。这也是为什么装饰器是很多高级Python话题的前置知识不理解装饰器就很难真正读懂上下文管理器的高级用法、Flask的请求上下文机制、以及各种ORM模型类的声明式写法。5. 常见问题与排查技巧实录5.1 装饰器顺序离函数越近执行越早多个装饰器叠放时执行顺序经常被搞混log auth def view(): ...等价于view log(auth(view))。先执行auth(view)返回一个新函数再把这个新函数传给log。所以调用view()时最先执行的是log的包装再进入auth的包装最后才进入原函数view。也就是说离函数越近的装饰器越靠近“内层”越先进入但外层装饰器是后一步包装它的。这个顺序在写鉴权、日志组合时很关键。比如你想记录用户请求日志但不想把未登录用户的请求也写进日志就得把auth放内层log放外层。因为外层log会先执行此时未登录请求已经被拦截日志自然不会记录到。5.2 装饰后函数信息丢失不加wraps的后果前面已经说过。还有一个隐藏问题有些框架基于函数签名生成API文档如果装饰器不把原函数签名传递过去生成的文档里参数名全是*args, **kwargs。解决方案除了functools.wraps必要时还可以用inspect.signature做签名修复但绝大多数场景下wraps就够了。我建议把from functools import wraps作为所有装饰器的默认开场白。它不会有任何副作用却能在未来节省大量排查时间。5.3 装饰器性能开销每调用一次包装后的函数都会额外多几层函数调用wrapper调用、闭包里的判断、装饰器内部逻辑。每一层调用都有开销。在热点路径上一个不做任何事、只是空转的装饰器也可能让函数慢一倍以上。如果确实需要极致性能可以考虑用functools.lru_cache这类缓存装饰器来降低实际计算量或者把多个装饰器合并成一个减少中间层数。此外定义在模块顶层的装饰器创建成本本身很低不用担心大量函数被装饰时导入变慢。5.4 漏写括号的典型坑带参数的装饰器极易漏括号。写retry而不是retry(3)时retry会把函数本身当成times参数传入内部执行range(times)时直接报出TypeError: function object cannot be interpreted as an integer。这个报错信息很迷惑人尤其当你盯着retry看了半天也没发现问题时。排查方法其实很简单把装饰器的三层结构打印出来或者直接在retry内部加一行调试输出看看times到底是什么类型。这种问题不是逻辑难而是语法糖带来的视觉掩蔽——你看到的是一行retry实际执行的却是retry(func)。5.5 常见问题速查表问题现象可能原因解决办法函数名变成wrapper没加functools.wraps在 wrapper 上挂wraps(func)retry调用时报TypeError: function object cannot be interpreted as an integer带参装饰器漏写括号改成retry(3)并确认返回的是装饰器多个装饰器效果顺序不对把执行顺序搞反了记住view log(auth(view))离函数近的先执行装饰后的函数签名消失元信息被覆盖用wraps必要时结合inspect.signature修复性能下降明显装饰器增加过多调用层合并装饰器或用缓存装饰器减少计算最后分享一点我自己的体会。刚开始写装饰器时我也觉得很玄学后来逼自己把每个装饰器都先在脑子里展开成func decorator(func)这种赋值再复杂的嵌套都能拆明白。装饰器这个知识点难点不在语法而在想明白它发生在运行时、操作的是函数对象本身。如果你正在学习或复习Python我强烈建议做一个练习自己实现一个带重试、带缓存、带日志的装饰器组合并在每个函数上观察help()输出的变化。把这个练习做完再看FastAPI的依赖注入、Flask的路由、Celery的任务声明你会觉得那些框架突然亲切了很多。