装饰器不是Python里的炫技玩具它是函数式编程思维在语言层面的一次优雅落地。当你写下login_required或time_it时真正发生的事是目标函数被当作参数传入装饰器装饰器返回一个新的可调用对象然后这个名字被重新绑定。这条简单规则解释了一切——装饰器是函数替换不是代码注入也不是魔法。透彻理解这句话才能避开书写装饰器时最常见的那些坑。闭包是装饰器的地基任何装饰器都离不开闭包。内层函数捕获外层函数中的变量比如被装饰的函数对象或者装饰器工厂传入的参数并延长这些变量的生命周期。没有闭包装饰器就是个空壳。写一个会记录日志的装饰器最朴素的形式长这样def log(func): def wrapper(args, kwargs): print(f调用 {func.__name__}) return func(args, kwargs) return wrapper内层的wrapper引用了外层的func于是func在log返回后依然存在。这就是闭包的价值。但问题立刻浮现wrapper没有func的名字和文档字符串很多调试工具和框架会因此困惑。几乎所有装饰器缺陷都源于对闭包变量作用域和函数元信息的忽视。用functools.wraps保住函数的灵魂上面那个log装饰器虽然能用但它毁掉了原函数的签名信息。在交互环境里输入help(wrapper)你只能看到一串没意义的内容。更糟的是像inspect.signature这样的内省工具会误判函数参数导致ORM映射或Web路由框架工作失常。解决之道是标准库里的functools.wrapsimport functools def log(func): functools.wraps(func) def wrapper(args, kwargs): print(f调用 {func.__name__}) return func(args, kwargs) return wrapperwraps做了件很漂亮的事它把原函数的__name__、__doc__、__module__、__qualname__等属性拷贝到wrapper上并尝试更新__dict__。这相当于给装饰器穿上了一层“官方马甲”。永远不要在一个不调用functools.wraps的装饰器上谈论最佳实践。除非你有极其特殊的原因否则它就是一条铁律。装饰器工厂让行为可配置有时你希望装饰器能接受参数比如指定日志级别或者设定重试次数。直接写retry办不到因为retry收到的不是函数而是一个参数。此时需要再包一层函数——装饰器工厂。它返回真正的装饰器由后者接收被装饰的函数。def retry(max_attempts3): def decorator(func): functools.wraps(func) def wrapper(args, kwargs): for attempt in range(max_attempts): try: return func(args, kwargs) except Exception as e: if attempt max_attempts - 1: raise time.sleep(0.5) return None return wrapper return decorator retry(max_attempts5) def connect(): ...这层嵌套结构常让人头晕但拆解后很清晰retry(5)先执行返回decorator接着decorator(connect)执行返回wrapper。装饰器工厂的本质是把参数绑定推迟到真正装饰的时刻。实现的时候别忘了给最内层wrapper加上functools.wraps否则你的重试装饰器本身就需要重试。类装饰器与可调用实例函数不是唯一的装饰器来源。类也可以扮演装饰器因为类是可调用的。当你写register时register可以是一个类它的构造函数接收被装饰的函数。这种方式的优势在于可以利用类的状态保存更多上下文。class CountCalls: def __init__(self, func): self.func func self.calls 0 def __call__(self, args, kwargs): self.calls 1 return self.func(args, kwargs) CountCalls def f(): return hi这里f会变成CountCalls的实例每次调用f()触发的其实是__call__。类装饰器把“状态”和“行为”捆绑在一起比闭包变量更清晰。但要注意类装饰器实例一旦创建原函数信息同样需要复制最好在__init__里调用functools.update_wrapper(self, func)。另外如果类装饰器还需要参数那就要构造一个返回装饰器类的工厂那层嵌套就不会比函数版本更轻松。堆叠装饰器的顺序陷阱装饰器可以叠加代码读起来像自上而下的流水线。但执行顺序恰恰相反离函数最近的装饰器最先执行然后逐层向外包裹。举个例子auth log def view(): pass实际过程是view auth(log(view))。请求到达view时先经过最外层的auth它通过后才会进入log包装的调用链。这个方向很容易被人记反导致权限校验实际发生在日志记录之后产生安全漏洞。理解装饰器堆叠顺序的唯一可靠方法是记住“洋葱模型”。画一张横截面图最里层是原函数每贴一个装饰器就包一圈。现在再看装饰器代码从下往上读就是执行顺序。装饰器与参数签名伪造的边界有些装饰器会修改函数签名比如添加可选参数或者去除某个参数。这让inspect.signature变得棘手。即使有functools.wraps它也只是复制原签名不会自动反应新加的参数。如果你的装饰器改变了调用约定你需要通过__wrapped__属性暴露原函数让需要真实签名的框架钻到内部去。标准库functools提供了update_wrapper来设置这个属性wraps默认也会做。当装饰器打算改变函数签名时请务必明确设置__wrapped__否则内省工具将被误导。一些灵活的参数控制通过args, kwargs轻松实现但这会让IDE的自动补全失效。要同时保持外部签名不变Python 3.10以后出现了一个利器inspect.signature的follow_wrapped参数以及函数上的__signature__属性。你可以给wrapper设置一个自定义的__signature__对象强行校准签名。这是很高阶的用法多数项目不必涉及。如果真到了这一步先停下来问自己是否应该用其他手段替代装饰器装饰器常被滥用的地方装饰器天生适合横切关注点比如计时、缓存、重试、权限校验、事务边界。但很多开发者习惯用它去修改业务逻辑内部的计算方式这就走偏了。曾有同事写了一个装饰器把返回值里的所有字符串自动转成大写结果下游模块全都跟着遭殃。装饰器应当关注函数之外的“切面”而不是改变函数本身的核心语义。一个黄金法则是如果装饰器的目的不能用一个动词短语简明描述比如“记录耗时”“验证权限”那它很可能在强行塞职责。此外装饰器执行顺序带来的副作用也容易被忽略。装饰器在模块加载时立即执行而不是在函数调用时。这意味着装饰器内部任何顶层代码——甚至只是print——都会在import阶段触发。在装饰器工厂里执行I/O或网络请求是灾难性的即使只是在模块顶层创建装饰器对象如果执行代价高也会拖慢导入速度。用装饰器建立可组合的管线装饰器强大在于能够把多个横切逻辑优雅地组合起来。想象一个Web服务一个视图函数可能需要被限流、需要记录慢查询、需要做幂等控制。与其把一堆try/except堆进函数体不如把每一条职责做成独立装饰器按需堆叠。这样函数体干净得就像一篇散文每个装饰器又都经过独立测试。这种设计的哲学是把重复的样板代码提升为声明式的元数据让函数忠于业务。但组合越多调用链越长性能损耗和调试难度也会随之积累。滥用装饰器组合会让调用栈深得令人窒息。对经验尚浅的团队与其设计一个灵活的“装饰器框架”不如限制装饰器的数量。可以在代码评审中约定同一个函数上堆叠的装饰器不超过3个。超出时考虑把多个职责合成为一个装饰器或者改用其他模式比如中间件。毕竟装饰器的嵌套表达力虽不至于像lambda那么难读但五六层包裹后阅读者只能靠猜来还原执行流程。最佳实践清单让装饰器健康长寿综合来看写出“不会害人”的装饰器需要遵守一些朴素原则。第一条永远用functools.wraps保留原函数元信息这是最低成本的保险。第二条装饰器的进出都要保持同一个接口接受任意参数返回被装饰函数的调用结果不要擅自吞掉异常或修改返回值类型除非职责明确。第三条装饰器的名称要能准确揭示行为避免取名process或handle这样模糊的名字。第四条优先使用类装饰器表达带状态逻辑但让类实现__call__后返回类装饰器更容易维护内部可变状态。还要谨慎对待装饰器中的异常。一个计时装饰器成功运行后如果原函数抛了异常你是打印日志后继续抛出还是记录完后静默吞掉吞异常会让最严重的问题消失得无声无息。装饰器应当在无副作用地记录失败后原样抛出原异常。类似地如果你想在装饰器里做缓存一定要考虑可变对象的拷贝问题别让缓存对象被业务代码修改否则下一次调用就会读到脏数据。另一个关键点是文档。装饰器自身要有docstring但装饰器包装后的函数也可能因为wraps带上原函数docstring。这会导致help显示混乱。业界倾向在装饰器工厂的docstring中写下明确的“签名说明”和“行为变更”并用functools.wraps让内层函数显示被包装函数的文档。对于用户来说更好的做法是遵循PEP 318的哲学装饰器只是语法糖不要在文档里隐藏太多奇迹。测试装饰器必须测试也必须会绕过装饰器和被装饰函数横切缠结测试时首先要验证的不只是原函数逻辑还有包装后的逻辑。一种简单做法是分别调用装饰器内外两层用decorator(func)直接生成包装函数然后测试它。同时在测试里设置functools.wraps设置的__wrapped__属性通过func.__wrapped__访问原始函数这样就能绕过装饰器只测核心。__wrapped__属性不只是留给框架的也是留给测试的逃生通道。当装饰器依赖外部状态比如当前登录用户测试中必须能够替换这些状态。可以把依赖设计成带默认参数的形式或用上下文变量来传递。不要用装饰器去捕获全局单例而应通过参数注入。这类设计问题通常会在写测试时暴露无遗——如果测试很难构造一个不受污染的调用环境那么装饰器的耦合性已经亮起了红灯。性能损耗真的可以忽略吗每次函数调用经过新的包装层必然带来额外开销。一个裸函数调用要压栈、弹栈经过装饰器后还要多几次属性查找和函数调用。对于高频调用的手段比如循环内百万次操作装饰器可能成为明显的瓶颈。把计时装饰器用在每个请求上并无大碍但如果用它包裹一个每毫秒执行几十次的小函数性能问题就会被放大。优化装饰器性能的思路不是去掉装饰器而是让装饰器越薄越好——尽量在闭包中提前绑定变量、避免在每次调用时处理不必要的数据。Python 3的functools.lru_cache自带缓存功能内部使用字典比手写的快速很多。写装饰器时优先考虑标准库方案而不是重复造轮子。如果你的装饰器需要判断参数类型或做繁重的摘要计算先想想能否把这些计算放到装饰器工厂阶段而不是每次调用都执行。记住装饰器工厂在导入时执行内层包装在每次调用时执行善用这个区别能省下大量CPU周期。深入理解时的最后一个领域参数注入与上下文体还有一种装饰器设计模式叫“参数注入”它会检查原函数请求哪些关键字参数并为其填充默认上下文。典型例子是Flask的app.route并不是这种但Web框架里的get_current_user却常用到。实现这种装饰器需要对参数名做静态分析签名较脆弱。Python 3的inspect.signature可以绑定(bind)参数但用在装饰器内部时要谨慎处理与原函数参数冲突。参数注入装饰器会重构函数签名因此它是最克制、最难优雅化的装饰器类型。如果业务能改用显式参数没人会选择这种隐式的魔法。但当下很多现代框架比如FastAPI利用inspect加上装饰器把参数注入变成强大功能。这就是权衡的展示装饰器适合做框架和业务之间的桥梁但不适合做业务内部的数据流管道。认清这种边界你才算真正深入理解了Python的装饰器。它们是从一个函数变换成另一个函数的工具简洁、抽象、容易被误用。当你肯花时间研究functools.wraps、闭包变量、堆叠顺序、签名内省这些问题时说明你已经开始自觉地从“能写”走向“会写”。 
长河君 · 2026/9/4 1:16:00 · 阅读 1.2k 深入理解Python装饰器：用法与最佳实践
装饰器不是Python里的炫技玩具它是函数式编程思维在语言层面的一次优雅落地。当你写下login_required或time_it时真正发生的事是目标函数被当作参数传入装饰器装饰器返回一个新的可调用对象然后这个名字被重新绑定。这条简单规则解释了一切——装饰器是函数替换不是代码注入也不是魔法。透彻理解这句话才能避开书写装饰器时最常见的那些坑。闭包是装饰器的地基任何装饰器都离不开闭包。内层函数捕获外层函数中的变量比如被装饰的函数对象或者装饰器工厂传入的参数并延长这些变量的生命周期。没有闭包装饰器就是个空壳。写一个会记录日志的装饰器最朴素的形式长这样def log(func): def wrapper(args, kwargs): print(f调用 {func.__name__}) return func(args, kwargs) return wrapper内层的wrapper引用了外层的func于是func在log返回后依然存在。这就是闭包的价值。但问题立刻浮现wrapper没有func的名字和文档字符串很多调试工具和框架会因此困惑。几乎所有装饰器缺陷都源于对闭包变量作用域和函数元信息的忽视。用functools.wraps保住函数的灵魂上面那个log装饰器虽然能用但它毁掉了原函数的签名信息。在交互环境里输入help(wrapper)你只能看到一串没意义的内容。更糟的是像inspect.signature这样的内省工具会误判函数参数导致ORM映射或Web路由框架工作失常。解决之道是标准库里的functools.wrapsimport functools def log(func): functools.wraps(func) def wrapper(args, kwargs): print(f调用 {func.__name__}) return func(args, kwargs) return wrapperwraps做了件很漂亮的事它把原函数的__name__、__doc__、__module__、__qualname__等属性拷贝到wrapper上并尝试更新__dict__。这相当于给装饰器穿上了一层“官方马甲”。永远不要在一个不调用functools.wraps的装饰器上谈论最佳实践。除非你有极其特殊的原因否则它就是一条铁律。装饰器工厂让行为可配置有时你希望装饰器能接受参数比如指定日志级别或者设定重试次数。直接写retry办不到因为retry收到的不是函数而是一个参数。此时需要再包一层函数——装饰器工厂。它返回真正的装饰器由后者接收被装饰的函数。def retry(max_attempts3): def decorator(func): functools.wraps(func) def wrapper(args, kwargs): for attempt in range(max_attempts): try: return func(args, kwargs) except Exception as e: if attempt max_attempts - 1: raise time.sleep(0.5) return None return wrapper return decorator retry(max_attempts5) def connect(): ...这层嵌套结构常让人头晕但拆解后很清晰retry(5)先执行返回decorator接着decorator(connect)执行返回wrapper。装饰器工厂的本质是把参数绑定推迟到真正装饰的时刻。实现的时候别忘了给最内层wrapper加上functools.wraps否则你的重试装饰器本身就需要重试。类装饰器与可调用实例函数不是唯一的装饰器来源。类也可以扮演装饰器因为类是可调用的。当你写register时register可以是一个类它的构造函数接收被装饰的函数。这种方式的优势在于可以利用类的状态保存更多上下文。class CountCalls: def __init__(self, func): self.func func self.calls 0 def __call__(self, args, kwargs): self.calls 1 return self.func(args, kwargs) CountCalls def f(): return hi这里f会变成CountCalls的实例每次调用f()触发的其实是__call__。类装饰器把“状态”和“行为”捆绑在一起比闭包变量更清晰。但要注意类装饰器实例一旦创建原函数信息同样需要复制最好在__init__里调用functools.update_wrapper(self, func)。另外如果类装饰器还需要参数那就要构造一个返回装饰器类的工厂那层嵌套就不会比函数版本更轻松。堆叠装饰器的顺序陷阱装饰器可以叠加代码读起来像自上而下的流水线。但执行顺序恰恰相反离函数最近的装饰器最先执行然后逐层向外包裹。举个例子auth log def view(): pass实际过程是view auth(log(view))。请求到达view时先经过最外层的auth它通过后才会进入log包装的调用链。这个方向很容易被人记反导致权限校验实际发生在日志记录之后产生安全漏洞。理解装饰器堆叠顺序的唯一可靠方法是记住“洋葱模型”。画一张横截面图最里层是原函数每贴一个装饰器就包一圈。现在再看装饰器代码从下往上读就是执行顺序。装饰器与参数签名伪造的边界有些装饰器会修改函数签名比如添加可选参数或者去除某个参数。这让inspect.signature变得棘手。即使有functools.wraps它也只是复制原签名不会自动反应新加的参数。如果你的装饰器改变了调用约定你需要通过__wrapped__属性暴露原函数让需要真实签名的框架钻到内部去。标准库functools提供了update_wrapper来设置这个属性wraps默认也会做。当装饰器打算改变函数签名时请务必明确设置__wrapped__否则内省工具将被误导。一些灵活的参数控制通过args, kwargs轻松实现但这会让IDE的自动补全失效。要同时保持外部签名不变Python 3.10以后出现了一个利器inspect.signature的follow_wrapped参数以及函数上的__signature__属性。你可以给wrapper设置一个自定义的__signature__对象强行校准签名。这是很高阶的用法多数项目不必涉及。如果真到了这一步先停下来问自己是否应该用其他手段替代装饰器装饰器常被滥用的地方装饰器天生适合横切关注点比如计时、缓存、重试、权限校验、事务边界。但很多开发者习惯用它去修改业务逻辑内部的计算方式这就走偏了。曾有同事写了一个装饰器把返回值里的所有字符串自动转成大写结果下游模块全都跟着遭殃。装饰器应当关注函数之外的“切面”而不是改变函数本身的核心语义。一个黄金法则是如果装饰器的目的不能用一个动词短语简明描述比如“记录耗时”“验证权限”那它很可能在强行塞职责。此外装饰器执行顺序带来的副作用也容易被忽略。装饰器在模块加载时立即执行而不是在函数调用时。这意味着装饰器内部任何顶层代码——甚至只是print——都会在import阶段触发。在装饰器工厂里执行I/O或网络请求是灾难性的即使只是在模块顶层创建装饰器对象如果执行代价高也会拖慢导入速度。用装饰器建立可组合的管线装饰器强大在于能够把多个横切逻辑优雅地组合起来。想象一个Web服务一个视图函数可能需要被限流、需要记录慢查询、需要做幂等控制。与其把一堆try/except堆进函数体不如把每一条职责做成独立装饰器按需堆叠。这样函数体干净得就像一篇散文每个装饰器又都经过独立测试。这种设计的哲学是把重复的样板代码提升为声明式的元数据让函数忠于业务。但组合越多调用链越长性能损耗和调试难度也会随之积累。滥用装饰器组合会让调用栈深得令人窒息。对经验尚浅的团队与其设计一个灵活的“装饰器框架”不如限制装饰器的数量。可以在代码评审中约定同一个函数上堆叠的装饰器不超过3个。超出时考虑把多个职责合成为一个装饰器或者改用其他模式比如中间件。毕竟装饰器的嵌套表达力虽不至于像lambda那么难读但五六层包裹后阅读者只能靠猜来还原执行流程。最佳实践清单让装饰器健康长寿综合来看写出“不会害人”的装饰器需要遵守一些朴素原则。第一条永远用functools.wraps保留原函数元信息这是最低成本的保险。第二条装饰器的进出都要保持同一个接口接受任意参数返回被装饰函数的调用结果不要擅自吞掉异常或修改返回值类型除非职责明确。第三条装饰器的名称要能准确揭示行为避免取名process或handle这样模糊的名字。第四条优先使用类装饰器表达带状态逻辑但让类实现__call__后返回类装饰器更容易维护内部可变状态。还要谨慎对待装饰器中的异常。一个计时装饰器成功运行后如果原函数抛了异常你是打印日志后继续抛出还是记录完后静默吞掉吞异常会让最严重的问题消失得无声无息。装饰器应当在无副作用地记录失败后原样抛出原异常。类似地如果你想在装饰器里做缓存一定要考虑可变对象的拷贝问题别让缓存对象被业务代码修改否则下一次调用就会读到脏数据。另一个关键点是文档。装饰器自身要有docstring但装饰器包装后的函数也可能因为wraps带上原函数docstring。这会导致help显示混乱。业界倾向在装饰器工厂的docstring中写下明确的“签名说明”和“行为变更”并用functools.wraps让内层函数显示被包装函数的文档。对于用户来说更好的做法是遵循PEP 318的哲学装饰器只是语法糖不要在文档里隐藏太多奇迹。测试装饰器必须测试也必须会绕过装饰器和被装饰函数横切缠结测试时首先要验证的不只是原函数逻辑还有包装后的逻辑。一种简单做法是分别调用装饰器内外两层用decorator(func)直接生成包装函数然后测试它。同时在测试里设置functools.wraps设置的__wrapped__属性通过func.__wrapped__访问原始函数这样就能绕过装饰器只测核心。__wrapped__属性不只是留给框架的也是留给测试的逃生通道。当装饰器依赖外部状态比如当前登录用户测试中必须能够替换这些状态。可以把依赖设计成带默认参数的形式或用上下文变量来传递。不要用装饰器去捕获全局单例而应通过参数注入。这类设计问题通常会在写测试时暴露无遗——如果测试很难构造一个不受污染的调用环境那么装饰器的耦合性已经亮起了红灯。性能损耗真的可以忽略吗每次函数调用经过新的包装层必然带来额外开销。一个裸函数调用要压栈、弹栈经过装饰器后还要多几次属性查找和函数调用。对于高频调用的手段比如循环内百万次操作装饰器可能成为明显的瓶颈。把计时装饰器用在每个请求上并无大碍但如果用它包裹一个每毫秒执行几十次的小函数性能问题就会被放大。优化装饰器性能的思路不是去掉装饰器而是让装饰器越薄越好——尽量在闭包中提前绑定变量、避免在每次调用时处理不必要的数据。Python 3的functools.lru_cache自带缓存功能内部使用字典比手写的快速很多。写装饰器时优先考虑标准库方案而不是重复造轮子。如果你的装饰器需要判断参数类型或做繁重的摘要计算先想想能否把这些计算放到装饰器工厂阶段而不是每次调用都执行。记住装饰器工厂在导入时执行内层包装在每次调用时执行善用这个区别能省下大量CPU周期。深入理解时的最后一个领域参数注入与上下文体还有一种装饰器设计模式叫“参数注入”它会检查原函数请求哪些关键字参数并为其填充默认上下文。典型例子是Flask的app.route并不是这种但Web框架里的get_current_user却常用到。实现这种装饰器需要对参数名做静态分析签名较脆弱。Python 3的inspect.signature可以绑定(bind)参数但用在装饰器内部时要谨慎处理与原函数参数冲突。参数注入装饰器会重构函数签名因此它是最克制、最难优雅化的装饰器类型。如果业务能改用显式参数没人会选择这种隐式的魔法。但当下很多现代框架比如FastAPI利用inspect加上装饰器把参数注入变成强大功能。这就是权衡的展示装饰器适合做框架和业务之间的桥梁但不适合做业务内部的数据流管道。认清这种边界你才算真正深入理解了Python的装饰器。它们是从一个函数变换成另一个函数的工具简洁、抽象、容易被误用。当你肯花时间研究functools.wraps、闭包变量、堆叠顺序、签名内省这些问题时说明你已经开始自觉地从“能写”走向“会写”。