1. 从一段看不懂却离不开的代码说起去年我在接手一个老项目时打开业务层代码满屏都是login_required、cache、log这样的装饰器。当时我还没完全吃透装饰器的原理只敢照着既有代码往上套结果有一次给一个函数加装饰器时因为顺序写反线上接口直接返回了 401。排查了一下午最后才发现是装饰器叠加顺序的问题。那次经历之后我下定决心把装饰器彻底啃透。说实话一旦真正理解了装饰器的底层机制你会有一种原来如此的通透感——它并不神秘本质就是一个接收函数、返回函数的普通函数。而所谓魔法其实只是 Python 语法糖在背后帮你做了一次函数替换。这篇文章我打算从最基础的函数对象讲起一步步拆解装饰器的实现原理、常见写法、实际场景和排错思路。不管你是刚学 Python 的初学者还是已经写了一段时间但总觉得装饰器差点意思的开发者这篇文章都适合你。我会尽量把话说明白让每个概念都落地而不是飘在语法层面。2. 装饰器的基础认知函数、闭包与包装思想2.1 函数在 Python 中是一等公民要理解装饰器首先得接受一个观念在 Python 里函数和整数、字符串、列表一样都是对象。这意味着你可以把函数赋值给变量把函数作为参数传给另一个函数也可以让一个函数返回另一个函数。def greet(name): return fHello, {name} # 函数可以赋值给变量 say_hello greet print(say_hello(Alice)) # Hello, Alice # 函数可以作为参数传入 def call_twice(func, arg): return func(func(arg)) print(call_twice(greet, Bob)) # Hello, Hello, Bob注意call_twice这种写法它接收一个函数作为参数在内部调用它并且把调用结果再次传给同一个函数。这种函数操作函数的能力正是装饰器能够存在的前提。2.2 闭包让内层函数记住外层环境装饰器还依赖另一个关键机制——闭包。简单说闭包就是一个内层函数记住了它外层函数里的变量即使外层函数已经执行完毕这些变量依然存活。def outer(x): def inner(y): return x y return inner add_5 outer(5) print(add_5(10)) # 15 print(add_5(20)) # 25这里的inner函数访问了outer里的x当outer(5)执行完返回inner后x 5这个状态被inner牢牢记住。所以add_5每次都等价于给传入值加 5。这个机制非常像制作一个带预设参数的函数模板。装饰器正是借助闭包把被装饰的函数和附加的逻辑捆绑在一起形成一个新的函数。2.3 装饰器的本质一个替换操作现在我们可以给出装饰器的核心定义了。所谓装饰器就是接收一个函数作为参数返回一个新函数新函数内部通常调用原函数并在调用前后插入额外逻辑用不用语法糖其实效果完全一样。下面两种写法等价def my_decorator(func): def wrapper(): print(before) func() print(after) return wrapper def say_hi(): print(hi) # 写法一手动调用 say_hi my_decorator(say_hi) # 写法二语法糖 my_decorator def say_hi(): print(hi)第二种写法不过是在函数定义完成后自动执行了say_hi my_decorator(say_hi)这个赋值操作。我建议初学者在理解装饰器时先在脑子里把符号还原成这种赋值语句很多疑问都会迎刃而解。提示装饰器不一定非得用语法糖你在任何地方手动调用func decorator(func)都能达到同样的效果。但让代码更清晰也更容易让人一眼看出这个函数的增强属性。3. 手写第一个实用装饰器从计时器开始拆解3.1 一个最简计时装饰器的完整演进纸上学来终觉浅。我建议每个想掌握装饰器的人都亲手写一个函数运行时间统计器。这个例子麻雀虽小五脏俱全而且在实际开发中真的能用到——排查接口慢、定位性能瓶颈时给可疑函数加上它比用 profiling 工具更轻量。先写第一版什么都不考虑只求跑通import time def timer(func): def wrapper(*args, **kwargs): start time.perf_counter() result func(*args, **kwargs) end time.perf_counter() print(f{func.__name__} 耗时 {end - start:.4f} 秒) return result return wrapper timer def slow_add(a, b): time.sleep(0.2) return a b print(slow_add(1, 2)) # slow_add 耗时 0.2002 秒 # 3这段代码里有几个细节值得展开说说。第一wrapper的参数写成*args, **kwargs这是装饰器能够适配任意签名函数的关键。原函数可能有 2 个参数、3 个参数、甚至全是关键字参数wrapper都能原样接收并透传。第二result func(*args, **kwargs)这一行是真正的灵魂。装饰器不能吞掉原函数的返回值所以一定要把原函数调用的结果存下来并在wrapper末尾返回。如果你忘了写return result被装饰的函数会静默地返回None——这是新手最容易踩的坑而且难排查因为业务代码不一定会立刻报错。第三用time.perf_counter()而不是time.time()。前者专门用于测量短时间间隔精度更高受系统时间调整的影响更小。3.2 给装饰器加参数两层包装的意义上面的timer装饰器用法固定没法配置。如果想要一个可以指定是否打印详细日志的装饰器比如timer(verboseTrue)该怎么办答案是再在外面包一层函数。这层的职责是接收装饰器的配置参数返回一个真正的装饰器。def timer(verboseFalse): def decorator(func): def wrapper(*args, **kwargs): start time.perf_counter() result func(*args, **kwargs) end time.perf_counter() if verbose: print(f[verbose] {func.__name__} 参数{args} {kwargs} 耗时{end - start:.4f}s) else: print(f{func.__name__} 耗时 {end - start:.4f}s) return result return wrapper return decorator timer(verboseTrue) def compute(x, y): time.sleep(0.1) return x * y print(compute(3, 4))注意这里的函数层级timer(verboseTrue)先执行返回decorator然后decorator生效把compute传给decoratordecorator返回wrapper最终compute这个名字指向的是wrapper。用工厂来理解这个结构很贴切timer是一个装饰器工厂它根据不同的配置参数生产出不同行为的装饰器。这是 Python 装饰器中非常常见的一种设计模式在 Flask、FastAPI、Django 的源码里都能看到类似的三层结构。3.3 保留原函数的身份信息functools.wraps如果你在装饰器里直接返回wrapper会有一个隐患原函数的名字、文档字符串、参数签名等信息全部被wrapper覆盖了。timer def slow_add(a, b): Adds two numbers slowly. pass print(slow_add.__name__) # wrapper print(slow_add.__doc__) # None在调试、使用 Sphinx 生成文档、或者依赖函数元信息的框架中这会造成不小的困扰。解决办法也很简单——用functools.wrapsimport functools def timer(func): functools.wraps(func) def wrapper(*args, **kwargs): # ... return func(*args, **kwargs) return wrapperfunctools.wraps是一个内部帮你拷贝__name__、__doc__、__module__、__annotations__等属性的辅助装饰器。我个人的习惯是只要写装饰器就默认加上functools.wraps(func)没有例外。这是写正经装饰器和玩具装饰器的分水岭。4. 进阶写法类装饰器与 Python 内置装饰器4.1 用类实现装饰器__call__的妙用函数装饰器写起来很顺手但有时候你希望装饰器内部能维护状态比如统计函数被调用了多少次。这时用类来实现装饰器会更自然——类实例可以持有属性状态存得住。class Counter: def __init__(self, func): functools.update_wrapper(self, func) self.func func self.count 0 def __call__(self, *args, **kwargs): self.count 1 print(f{self.func.__name__} 第 {self.count} 次调用) return self.func(*args, **kwargs) Counter def hello(name): print(fHello, {name}) hello(Alice) hello(Bob) # hello 第 1 次调用 # Hello, Alice # hello 第 2 次调用 # Hello, Bob关键点在于__call__方法它让一个类的实例可以像函数一样被调用。Python 在背后做了这样的转换hello Counter(hello)之后每次调用hello(...)实际上都在调用Counter实例的__call__方法。类装饰器还有一个隐藏优势你可以轻松地为装饰器增加公开方法或属性。比如上面的Counter如果想在外部查看调用次数直接访问hello.count即可。4.2 内置装饰器三兄弟staticmethod、classmethod、propertyPython 自带的几个内置装饰器其实也是装饰器思想的具体应用。理解它们能帮你更深入地体会装饰器在不同层面的用法。staticmethod把普通函数变成类中的静态方法它不接收self或cls。classmethod接收cls作为第一个参数常用于定义备选构造函数。property则把一个方法伪装成属性让你可以像访问属性一样访问它同时还能在背后做校验或计算。class Circle: def __init__(self, radius): self._radius radius property def area(self): return 3.14159 * self._radius ** 2 classmethod def from_diameter(cls, diameter): return cls(diameter / 2) c Circle.from_diameter(10) print(c.area) # 78.53975注意 area 没有加括号这里property核心价值在于提供了访问时实时计算的能力但调用方无感知。如果将来内部实现变了比如面积改成由self._area直接返回调用方代码完全不用动。这就是封装和抽象的力量也是装饰器在语言层面的典型应用。4.3 可堆叠装饰器执行顺序与设计策略一个函数上可以同时叠加多个装饰器这也是实际项目中最常见的用法。来看一个例子def bold(func): functools.wraps(func) def wrapper(): return b func() /b return wrapper def italic(func): functools.wraps(func) def wrapper(): return i func() /i return wrapper bold italic def render(): return hello print(render()) # bihello/i/b看到结果了吗装饰器的应用顺序是从下往上的先执行italic再执行bold。这就像层层包裹的洋葱离函数定义最近的那层装饰器最先被应用到原函数上。我在一开始提到的那个线上事故就是没搞清楚这个顺序。当时我在视图函数上写了login_required和cache本意是先做权限校验再读缓存但因为顺序写反导致未登录用户直接命中了缓存数据。后来我把login_required放在上方问题立刻解决。设计堆叠装饰器时我的经验是把偏全局/偏前置的装饰器放上面把偏具体/偏业务的装饰器放下面。比如权限校验、事务管理这类横切关注点放上层日志、缓存这类偏业务增强的放下层。这样读代码时最先映入眼帘的是最宏观的约束符合阅读直觉。5. 装饰器的经典应用场景从缓存到权限从重试到注册5.1 实现一个带过期时间的函数级缓存函数级缓存是装饰器的代表性应用之一。对于计算密集、结果可复用的函数缓存能显著提升性能。我第一次意识到装饰器的强大就是因为用 20 行代码实现了一个带过期时间的函数缓存把一个重复计算接口的响应时间从 300ms 降到了 1ms。import functools import time def cache_with_ttl(seconds): def decorator(func): cache {} functools.wraps(func) def wrapper(*args, **kwargs): key (args, tuple(sorted(kwargs.items()))) now time.time() if key in cache: value, timestamp cache[key] if now - timestamp seconds: print([cache hit], key) return value else: print([cache expired], key) del cache[key] value func(*args, **kwargs) cache[key] (value, now) return value # 提供手动清空缓存的方法附加到 wrapper 上 wrapper.clear lambda: cache.clear() return wrapper return decorator cache_with_ttl(5) def get_user_info(user_id): print(fetching from database...) return {id: user_id, name: fuser_{user_id}} print(get_user_info(1)) # fetching from database... print(get_user_info(1)) # [cache hit] time.sleep(6) print(get_user_info(1)) # fetching from database...这里有几个细节值得注意缓存 key 由args和排序后的kwargs组成确保无论调用方式如何相同参数的函数都能命中同一个缓存项。这个设计在真实项目中非常关键否则同一逻辑可能因参数顺序不同而重复计算。过期策略用的是时间戳比较简单可靠。如果要更精确可以用time.monotonic()避免系统时间被修改的影响。我在wrapper上动态挂了clear方法让外部可以手动清洗缓存。这在实际调试时很实用否则改完代码想验证新逻辑还得等缓存自然过期。5.2 权限校验把能不能调放到函数边界上在 Web 开发中权限校验是装饰器最经典的用武之地。它把检查用户身份、检查用户角色这部分逻辑从业务函数中剥离出来让业务函数只关心自己该做的事。def require_role(role): def decorator(func): functools.wraps(func) def wrapper(user, *args, **kwargs): if user.get(role) ! role: raise PermissionError(f需要 {role} 权限当前用户角色为 {user.get(role)}) return func(user, *args, **kwargs) return wrapper return decorator require_role(admin) def delete_user(user, target_user_id): return f用户 {target_user_id} 已被删除 print(delete_user({name: Alice, role: admin}, 42)) # 用户 42 已被删除 try: delete_user({name: Bob, role: guest}, 42) except PermissionError as e: print(e) # 需要 admin 权限当前用户角色为 guest这种做法的收益很直接多个需要管理员权限的接口可以共用一个装饰器权限逻辑只需要维护一份将来如果权限模型变了比如增加一个超级管理员角色也只需要改装饰器内部判断不用动任何业务函数。我在实际项目中经常用这种方式做细粒度权限 接口复用可维护性比在每个接口里复制粘贴权限判断代码好得多。5.3 重试机制对付不稳定外部依赖的法宝调用外部 API 时网络抖动、服务暂时不可用是常态。与其让整个请求直接失败不如在函数层面加一个失败自动重试的装饰器。这也是我在写爬虫和调用第三方服务时最常用的工具。import random import time def retry(max_attempts3, delay1, 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 as e: if attempt max_attempts: raise print(f第 {attempt} 次尝试失败: {e}{delay} 秒后重试...) time.sleep(delay) return wrapper return decorator retry(max_attempts3, delay0.5) def flaky_api(): if random.random() 0.7: raise ConnectionError(网络连接失败) return 成功 print(flaky_api())实现重试装饰器时有几个为什么必须想清楚为什么exceptions要作为参数传入因为不同场景下值得重试的异常类型不同。网络错误值得重试但是参数校验错误重试一百次也没用只会掩盖问题。为什么max_attempts里包含第一次调用因为range(1, max_attempts 1)意味着总尝试次数就是max_attempts第一次失败后还会再试max_attempts - 1次。如果想把额外重试次数作为参数语义要写清楚否则容易造成困惑。为什么重试前要delay因为很多失败是瞬时过载立即重试大概率还是失败稍等片刻反而更容易成功。更高级的实现可以引入指数退避或抖动但基础版本已经能解决大部分问题。5.4 注册机制插件系统的报名处装饰器还有一种经常被忽略但极为强大的用途——注册函数。它不是在函数执行时做增强而是在函数定义的那一刻把函数登记到某个数据结构里。# registry.py handlers {} def register(event_type): def decorator(func): handlers[event_type] func return func # 注意这里返回原函数而不是 wrapper return decorator register(user.created) def on_user_created(user): print(f处理用户创建事件: {user}) register(user.deleted) def on_user_deleted(user): print(f处理用户删除事件: {user}) def dispatch(event_type, payload): handler handlers.get(event_type) if handler: handler(payload) else: raise KeyError(f没有注册 {event_type} 事件) dispatch(user.created, {id: 1})这种装饰器即注册的模式是很多插件系统、事件总线、路由表的底层基础设施。Flask 的app.route(/)、Django 的admin.register(Model)、pytest 的pytest.fixture本质上都是一个注册装饰器。注意这个装饰器返回的是原函数func而不是wrapper因为这里不需要改变函数行为只是顺便把函数登记一下。很多人会惯性思维地认为装饰器必须返回一个新函数其实返回原函数完全合法能更简洁地实现注册语义。6. 避坑地图装饰器开发中常见的坑与排查思路6.1 坑一忘了return result函数静默返回 None这是初学者最容易踩、而且最难发现的坑。装饰器内部调用了原函数但如果不显式返回结果wrapper默认返回None。如果你的业务代码没有对返回值做严格检查这个问题会潜伏很久。def broken_decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): func(*args, **kwargs) # 忘了 return return wrapper broken_decorator def add(a, b): return a b print(add(1, 2)) # None排查思路如果你发现某个被装饰的函数明明有返回值外部却收到 None先检查装饰器内部有没有return。这个问题的隐蔽性在于它不会报错行为差异只在返回值那一层。6.2 坑二装饰器在导入时执行而不是调用时执行装饰器代码在函数定义时就会执行不是在函数被调用时才执行。这个特性带来的副作用是装饰器内部的顶层代码比如打印、连接数据库会在模块导入阶段就开始运行。def announce(func): print(f正在装饰 {func.__name__}) # 这一行在 import 时就执行 functools.wraps(func) def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper announce def foo(): pass # 导入这个模块时会立即输出正在装饰 foo如果你在装饰器内部做了重量级初始化操作比如创建数据库连接池、加载模型文件这可能导致模块导入变慢。解决办法是尽量把耗时操作推迟到wrapper内部首次调用时执行懒加载或者在装饰器设计时明确提示这个行为。6.3 坑三多个装饰器叠加顺序搞反前面已经详细分析过叠加顺序的问题这里再补充一个排查思路。如果你发现加了多个装饰器后行为不符合预期可以把其中一个装饰器临时降级为手动写法逐步排查到底是哪个装饰器的问题# 原始写法 bold italic def render(): return hello # 手动展开等价于 def render(): return hello render bold(italic(render))把装饰器展开成普通函数调用往往能瞬间看清执行顺序和数据流向。6.4 坑四在类方法上直接使用函数装饰器导致self丢失如果你想把一个装饰器直接用在类方法上要特别注意第一个参数的问题。看这个例子def log_call(func): functools.wraps(func) def wrapper(*args, **kwargs): print(f调用 {func.__name__}) return func(*args, **kwargs) return wrapper class Service: log_call def run(self, task): return frunning {task} s Service() print(s.run(job)) # 看起来没问题这里函数能正常工作是因为*args会把self和task都接住。但如果你在装饰器里想访问self的属性就不能靠简单的*args了因为装饰器不知道哪个参数是self。更稳妥的方案是让装饰器也接受self参数def log_call(func): functools.wraps(func) def wrapper(self, *args, **kwargs): print(f调用 {func.__name__}实例{self}) return func(self, *args, **kwargs) return wrapper不过这样做会让装饰器只能用于类方法不能用于普通函数。在某些框架中装饰器设计者会通过inspect.signature来动态判断第一个参数是self、cls还是普通参数但这对大多数场景来说过于复杂了。我的建议是为类方法和普通函数各准备一套装饰器不要试图用一个装饰器通吃所有形态。6.5 坑五忘记functools.wraps导致框架行为异常如果说忘记return result是静默返 None那么忘记functools.wraps就是信息伪装。被装饰函数的名字变成了wrapper很多依赖函数名做判断的框架会直接罢工。我遇到过的一个实际案例某框架根据视图函数的__name__生成 URL 路由名结果因为我写的装饰器没加wraps所有被装饰的视图都注册成了同一个名字路由全部冲突。排查了一上午最后发现是__name__被覆盖了。加上functools.wraps(func)后一切恢复正常。关于这个坑我的建议很简单——写装饰器永远默认加 wraps没有例外。这行代码成本几乎为零却能为未来省下大量排查时间。7. 日常工具箱几个我反复在用的装饰器模板7.1 通用日志装饰器这个装饰器我几乎在每个 Python 项目里都会写一份。它对调试和线上问题追踪非常有帮助尤其是当你需要快速知道某个函数的入参、出参和耗时的时候。import functools import time import logging logger logging.getLogger(app.func) def log_func(levellogging.INFO): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.perf_counter() try: result func(*args, **kwargs) logger.log(level, f{func.__module__}.{func.__name__} - {result!r} 耗时{time.perf_counter() - start:.4f}s) return result except Exception as e: logger.exception(f{func.__module__}.{func.__name__} 异常: {e}) raise return wrapper return decorator使用这个装饰器时特别注意两点不要在生产环境对高频函数打完整参数和返回值的日志否则日志量会爆炸。建议只保留函数名和耗时参数通过repr控制长度或直接省略。logger.exception会自动带上当前异常堆栈比logger.error更适合放在except块里。7.2 输入校验装饰器在数据入口处做校验比在函数内部写一堆if判断要整洁得多。我经常用装饰器做轻量参数校验避免业务函数被校验逻辑淹没。def validate(**validators): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): # 简单假设第一个参数名对应校验规则 for arg_name, validator in validators.items(): if arg_name in kwargs: kwargs[arg_name] validator(kwargs[arg_name]) return func(*args, **kwargs) return wrapper return decorator def positive_int(x): if not isinstance(x, int) or x 0: raise ValueError(f{x} 必须是正整数) return x validate(limitpositive_int) def get_items(limit): return [i for i in range(limit)] print(get_items(limit3)) try: get_items(limit-1) except ValueError as e: print(e)不过要提醒一下这种方式适合简单场景。如果参数校验规则特别复杂还是应该用 pydantic 或 marshmallow 这类专用库把校验逻辑和数据结构绑定在一起而不是堆在装饰器里。7.3 事务装饰器在操作数据库时开启事务、执行、提交、失败回滚是一个极其通用的模式。用装饰器可以把这个流程统一封装减少重复代码。class TransactionError(Exception): pass def transaction(conn): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): conn.begin() try: result func(*args, **kwargs) conn.commit() return result except Exception: conn.rollback() raise return wrapper return decorator这个装饰器的使用场景很广但要注意它假设被装饰的函数在单个连接上工作函数内部不能自行提交或回滚否则会破坏事务边界。此外如果一个函数里嵌套调用了另一个带事务装饰器的函数要小心事务嵌套问题很多数据库连接库默认不支持嵌套事务需要设计成事务装饰器只在最外层生效。8. 我的个人心得装饰器不是炫技而是关注点分离的工具写这篇文章的时候我回顾了这些年用装饰器的经历。从最开始觉得它有点魔幻到熟练运用再到偶尔被它坑一把我对装饰器的态度是它是一个极其强大、但也需要克制使用的工具。什么时候该用装饰器我总结了几条经验有多个函数共享同一段横切逻辑且这段逻辑与业务本身无关时。比如日志、缓存、权限、重试、事务。此时装饰器能把横切逻辑集中管理业务函数保持纯粹。你希望函数保持原样但在其周围织入额外行为。装饰器天然适合做 AOP面向切面编程式的增强因为它不改动原函数的代码只需要在调用处标记一下。需要一种声明式的、可读性强的表达方式。require_role(admin)比if user.role ! admin: raise ...更直观读者一看就知道这个接口的权限要求。什么时候不该用装饰器过度抽象导致业务逻辑被拆得七零八落。如果一个装饰器需要读取函数内部的局部变量、或者需要依赖调用顺序那往往说明这个逻辑不太适合用装饰器表达。装饰器本身太复杂嵌套层级过深。当函数上叠了五六个装饰器而且每个装饰器都有参数时代码的可读性会直线下降。此时建议把装饰器合并或者把部分逻辑移到业务函数内部。性能敏感的内层循环。装饰器引入了额外的函数调用层级对绝大多数业务场景来说可以忽略不计但在超高频的循环中这个开销会累积。实测下来在一秒钟执行百万次的场景里装饰器带来的额外函数调用可能让性能下降一到两成这时候就需要权衡了。最后再分享一个调试技巧当你怀疑某个装饰器有问题时可以用inspect模块直接查看被装饰函数的真实信息import inspect timer def foo(a, b2): pass print(inspect.signature(foo)) # 如果没有 wraps会显示 (*args, **kwargs) print(foo.__wrapped__) # wraps 会把原函数存在 __wrapped__ 属性里__wrapped__属性是functools.wraps自动设置的指向原始函数。很多框架和调试工具就是靠这个属性反向找到真实函数的。如果你自己实现装饰器且不想用functools.wraps也可以手动设置wrapper.__wrapped__ func效果类似。总而言之装饰器的本质不复杂复杂的是在合适的场景识别出这里可以用装饰器以及设计出足够通用、可配置、可维护的装饰器接口。希望这篇文章能帮你跨过那道看着会写但不会用的门槛。如果你在读的过程中有什么疑问或者在实际项目中遇到了装饰器相关的怪异问题欢迎在评论区聊聊我看到了会尽量回复。
