1. 从一个最简单的场景说起
先别急着看概念，Python的装饰器很多人在入门阶段都把它当成一个“知道但用不上的高级特性”。但如果你写过爬虫，或者做过接口封装，大概率有这种经历：给十几个接口写日志、算耗时、加鉴权，每个函数里都得塞一遍重复代码。改一处逻辑，就得把所有函数翻出来同步。我当时第一次意识到需要装饰器，就是在给一个数据采集脚本统一加“失败重试”功能的时候——手动改了二十多个函数，改到怀疑人生。
装饰器解决的本质问题，就是在不修改原函数代码的前提下，给函数动态增加功能。它适合用来做日志记录、性能分析、权限校验、事务处理、缓存、重试机制这些横切关注点。无论你是刚看完python教程准备上手，还是已经写了几个月python代码但一直没搞懂装饰器的执行顺序，这篇文章都值得你花二十分钟看完。
这个内容能给你什么：一是一套完整的理解框架，二是可以直接抄进项目里的代码模板，三是我实际踩过的一些坑。学完之后，你再看那些开源框架里的@app.route、@click.option、@pytest.fixture，就不会再发怵了。
2. 装饰器到底做了什么：从函数是一等公民说起
2.1 函数就是变量，你能把它传来传去
要理解装饰器，第一步是接受一个事实：在Python里，函数名本质上是变量名，它指向一个函数对象。这意味着你可以把函数当作参数传给另一个函数，也可以把一个函数作为另一个函数的返回值。别说Python，很多脚本语言都有这个特性，但Python把它用得非常彻底。
def say_hello(name): return f"Hello, {name}" # 直接调用 print(say_hello("张三")) # 把函数赋值给另一个变量，然后像函数一样调用 greet = say_hello print(greet("李四"))这里greet和say_hello指向的是同一个函数对象，所以调用结果完全一样。这一点是整个装饰器机制的地基——你能把函数传来传去，才能做到“把一个函数包装进另一个函数里”。
2.2 闭包：让内层函数记住外层函数的环境
闭包的概念和装饰器是绑在一起的。简单说，如果一个内层函数引用了外层函数的变量，而这个内层函数又被当作对象返回了，那么它就“记住”了外层函数当时的环境。即使外层函数已经执行完毕，这个内层函数依然可以通过某种方式访问外层函数里的变量。
def outer(x): def inner(y): return x + y return inner add_5 = outer(5) print(add_5(3)) # 输出 8这里的inner记住了x=5这个值，所以后来不管传什么y进来，它都会加上5。这个机制是装饰器能工作的核心——装饰器本质上就是一个外层函数，它接收一个函数，然后用一个内层函数去包装它，同时这个内层函数还能访问到外层函数拿到的那个“被包装的函数”。
用生活里的例子来类比，装饰器就像给礼物打包。礼物本身是原函数，包装盒是装饰器，包装盒上写的卡片是前置逻辑和后置逻辑。你收到的还是那个礼物，但多了一层精心的包装，拆的时候还能看到卡片上的祝福语。这个类比虽然不是百分之百精准，但帮你建立直觉足够用了。
2.3 语法糖只是“语法糖”，本质还是函数调用
很多初学者看到@符号就晕，其实@decorator放在函数定义上面，等价于：
def func(): pass func = decorator(func)就这行代码。@只是把这个赋值过程放到了函数定义的位置，让你写起来更优雅。理解这一点非常重要，因为当你遇到@decorator到底做了什么、执行顺序是什么这样的问题时，只要把它还原成函数调用，一切就清楚了。
3. 手写第一个装饰器：几行代码建立起核心认知
3.1 最简单的无参数装饰器
先看一个能真实运行的例子。假设我要统计一个函数执行耗时，最朴素的做法是：
import time def time_it(func): def wrapper(*args, **kwargs): start = time.perf_counter() result = func(*args, **kwargs) end = time.perf_counter() print(f"函数 {func.__name__} 执行耗时 {end - start:.6f} 秒") return result return wrapper @time_it def compute_sum(n): time.sleep(0.1) return sum(range(n)) print(compute_sum(10000))运行结果会显示compute_sum的耗时约0.1秒，然后返回求和结果。这里的wrapper就是包装函数，它接收任意位置参数和关键字参数，这样不管原函数签名是什么，都能顺利转发。*args和**kwargs这两个参数是装饰器能通用的关键——没它们，包装函数就只能适配特定签名的原函数了。
3.2 为什么一定要写return func(*args, **kwargs)
这是新手最容易忽视的地方。有些人在写装饰器时，内层函数调用完原函数之后忘记return，结果就是原函数的所有返回值都变成了None。原因很简单：装饰器真正返回给外界的，是wrapper这个函数，所有调用都在走wrapper，wrapper返回什么，调用者就拿到什么。如果你在wrapper里调用了func但不把它返回，那wrapper自身默认返回None，调用者拿到的自然就是None。
这个坑我见得太多了，不止一次有人拿着一个“好好的装饰器”来问为什么函数返回值为空。排查的第一件事就是看装饰器的内层函数有没有写return。
3.3 失去函数身份的问题：functools.wraps不是可选项
如果你用上面那个简单的time_it装饰完函数，再去查看compute_sum的信息：
print(compute_sum.__name__) # 输出 wrapper print(compute_sum.__doc__) # 输出 None你会发现函数名丢了，文档字符串也丢了。因为装饰器返回的是wrapper，而wrapper默认没有继承原函数的元信息。这在调试、文档生成、甚至某些依赖函数名的框架逻辑里会造成问题。
解决办法是使用functools.wraps。这个装饰器的作用，就是把原函数的__name__、__doc__、__module__等属性复制到wrapper上，让外界“看起来”这个wrapper就是原函数：
from functools import wraps import time def time_it(func): @wraps(func) def wrapper(*args, **kwargs): start = time.perf_counter() result = func(*args, **kwargs) end = time.perf_counter() print(f"函数 {func.__name__} 执行耗时 {end - start:.6f} 秒") return result return wrapper注意@wraps(func)的位置——它装饰的是wrapper，不是func。这个写法我自己也容易搞错，所以每次写新装饰器时都会下意识核对一遍。
4. 装饰器的进阶形态：带参数、类装饰器与叠加
4.1 带参数的装饰器：再加一层函数
有时候装饰器本身需要参数，比如我想指定日志级别，或者想指定重试次数。这时候需要在普通装饰器外面再包一层函数，形成一个三层结构。很多人第一次看到三层嵌套的代码直接劝退，但只要顺着执行顺序捋一遍，逻辑并不复杂。
from functools import wraps import time def retry(max_retries=3, delay=0.5): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): for attempt in range(1, max_retries + 1): try: return func(*args, **kwargs) except Exception as e: print(f"第 {attempt} 次调用失败: {e}") if attempt == max_retries: raise time.sleep(delay) return wrapper return decorator @retry(max_retries=5, delay=1) def unstable_api_call(): # 模拟一个不稳定的接口 import random if random.random() < 0.6: raise ConnectionError("网络波动") return "success"这里retry是一个普通函数，它接收参数然后返回decorator，decorator才是真正意义上的装饰器。使用时的@retry(max_retries=5, delay=1)其实是分两步执行的：先调用retry得到decorator，再用decorator去装饰下面的函数。
4.2 类装饰器：当状态管理成为刚需
如果装饰器需要维护状态，比如统计调用次数、保存缓存数据，用类来写更顺手。类是带状态的，实例化后能在生命周期内保存数据。
class CallCounter: def __init__(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) @CallCounter def process(): pass process() process() process()__call__方法让类的实例可以像函数一样被调用。当装饰器用类实现时，@CallCounter会实例化一个对象，之后每次调用原函数，触发的是这个对象的__call__方法。类装饰器特别适合做带有缓存的装饰器——状态放在__init__里，每次调用先查缓存，命中就直接返回，不命中才执行原函数。
4.3 多个装饰器叠加：顺序是从下往上包
这是面试高频题，也是实际写代码时容易栽的地方。多个装饰器的执行顺序，可以用“包装”来理解：越靠近函数定义的装饰器，越先执行包装，所以它是内层；越远离函数的装饰器，后执行包装，处于外层。调用时，外层先进入，内层后进入；返回时相反。
@decorator_a @decorator_b def target(): pass等价于：
target = decorator_a(decorator_b(target))实际执行流程：调用target()时，先进入decorator_a的wrapper，在它的func调用处进入decorator_b的wrapper，最后才真正执行target本体。我建议你写个小示例，在每个装饰器里打印“进入”和“退出”日志，跑一遍，比看十篇文章都直观。
5. 装饰器的实际应用场景：从日志到缓存到鉴权
5.1 日志记录：把埋点从业务逻辑里摘出来
我最开始在爬虫项目里用装饰器，就是为了统一记录请求日志。爬虫跑起来动辄几万个请求，如果每个请求都手写日志逻辑，代码根本没法维护。用装饰器把日志逻辑集中起来，业务代码只关心请求本身，清爽很多。
from functools import wraps import logging logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s") logger = logging.getLogger("crawler") def log_call(func): @wraps(func) def wrapper(*args, **kwargs): logger.info(f"调用 {func.__name__}, 参数: {args}, {kwargs}") try: result = func(*args, **kwargs) logger.info(f"{func.__name__} 返回: {result}") return result except Exception as e: logger.error(f"{func.__name__} 异常: {e}") raise return wrapper这样在python爬虫里面，对每一个数据抓取函数只需要加上@log_call，日志就齐了。数据分析和可视化脚本里，也经常用这种方式记录每个处理步骤的耗时和数据量，排查性能瓶颈时一目了然。
5.2 缓存：用空间换时间的最佳体现
在python数据分析项目里，有些计算逻辑非常耗时，而且同样的输入会被重复计算。这时候一个带缓存的装饰器就能把耗时降到可以忽略不计。我用一个字典做缓存，键是参数，值是结果。这个方法也叫“记忆化”，动态规划问题里特别常用。
from functools import wraps def memoize(func): cache = {} @wraps(func) def wrapper(*args, **kwargs): key = (args, tuple(sorted(kwargs.items()))) if key not in cache: cache[key] = func(*args, **kwargs) return cache[key] return wrapper @memoize def expensive_query(user_id, page=1): # 模拟一次高开销的数据库查询 from time import sleep sleep(1) return f"user {user_id} page {page} data"注意key的构造——args是元组可以直接做字典键，kwargs得先排序再转元组，否则同一个参数的不同传法会被视为不同键。处理不可哈希的参数时要额外小心，比如参数里有列表时需要转成元组，否则直接TypeError。
5.3 重试机制：网络场景下的保命符
接前面的retry装饰器，我再补充一点。重试装饰器在爬虫和微服务调用里用途极大——网络请求失败是常态，能自动重试，整个任务的稳定性立刻上了一个台阶。设计重试时要考虑两点：一是重试间隔策略，除了固定间隔外，还可以用指数退避，防止重试风暴；二是记录每次重试的原因和次数，方便事后排查。
from functools import wraps import time import random def backoff_retry(max_retries=5, base_delay=0.1): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): for attempt in range(1, max_retries + 1): try: return func(*args, **kwargs) except Exception as e: if attempt == max_retries: raise delay = base_delay * (2 ** (attempt - 1)) + random.uniform(0, 0.01) print(f"第 {attempt} 次失败，{delay:.2f} 秒后重试，错误: {e}") time.sleep(delay) return wrapper return decorator指数退避的意思就是第一次失败等0.1秒，第二次等0.2秒，第三次等0.4秒，这样依次翻倍。加上一点随机抖动，避免多个请求同时重试造成雪崩。
5.4 权限校验：Web框架里的隐形守卫
在Web应用里，装饰器最经典的角色之一就是鉴权。无论你是用Django还是Flask，还是把Python应用融入微服务体系时对接Spring Cloud Alibaba，权限校验这类横切逻辑最适合用装饰器实现。虽然不同框架有自己的实现方式，但底层思路都是从session或token里解析出用户身份，检查权限，通过则进入业务函数，不通过则返回错误。
from functools import wraps def require_role(role): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): # 模拟从请求上下文取用户 user = kwargs.get("current_user") or (args[0] if args else None) if user is None or user.get("role") != role: raise PermissionError(f"需要 {role} 角色才能访问") return func(*args, **kwargs) return wrapper return decorator @require_role("admin") def delete_user(user_id, current_user=None): return f"删除用户 {user_id}"这种装饰器让业务代码根本不需要关心“当前用户能不能做这件事”，它只需要专注自己的职责。
6. 内置装饰器：staticmethod、classmethod与property
6.1classmethod与staticmethod——类里面的特殊函数
在类里定义方法时，最常见的是实例方法，第一个参数是self。而classmethod装饰的方法第一个参数是类本身（约定命名为cls），适用于需要访问类属性或调用其他类方法的场景。staticmethod则是不依赖实例也不依赖类的普通函数，只是放在类的命名空间里便于组织。
class Database: connection_pool = None @classmethod def init_pool(cls, pool_size): cls.connection_pool = {"size": pool_size} print(f"连接池初始化完成，大小 {pool_size}") @staticmethod def validate_conn_string(conn_string): return "localhost" in conn_string Database.init_pool(10) print(Database.validate_conn_string("host=localhost"))6.2property——把方法变成属性
property装饰器可以让你把一个方法当属性来访问，同时保留可定制的逻辑。典型的用法是在类里暴露一个计算属性，或者对属性的赋值做参数校验。
class Circle: def __init__(self, radius): self._radius = radius @property def area(self): return 3.14159 * self._radius ** 2 @property def radius(self): return self._radius @radius.setter def radius(self, value): if value <= 0: raise ValueError("半径必须大于0") self._radius = value c = Circle(5) print(c.area) # 直接像属性一样访问 c.radius = 10 # 触发setter校验这三个内置装饰器在python基础语法里不算难，但因为太常用，理解他们能帮你快速看懂别人的代码，尤其是python量化交易策略代码里面的数据类定义，经常能看到@property被用来保护策略参数的取值范围。
7. 常见问题与排查技巧实录
7.1 返回值丢失
症状：被装饰的函数返回None。
原因：内层wrapper忘记return func(*args, **kwargs)。
排查：看装饰器的内层函数，确认有没有把原函数的返回值传递出来。这个是最常见的问题，没有之一。
7.2 函数信息丢失
症状：被装饰的函数的__name__、__doc__变成了wrapper的。
原因：没有使用@wraps(func)。
排查：在wrapper定义上方加上@wraps(func)即可。如果你用的是类装饰器，记得在__init__里通过functools.update_wrapper(self, func)来同步元信息。
7.3 多个装饰器顺序搞反
症状：功能不生效，或者报参数错误。
原因：多个装饰器叠加时，执行顺序是“从下往上包装，从上往下执行”。很多人把顺序搞反，最外层装饰器拿到的就不是原函数，而是被内层装饰器包装过的函数。
排查：打印每个装饰器的进入和退出日志，跑一遍测试用例，立刻就知道谁在外层谁在内层。
7.4 带参数装饰器的三层结构书写错误
症状：@decorator和@decorator()表现不一致，有时直接报错。
原因：带参数的装饰器本质上是“装饰器工厂”，必须先调用工厂拿到真正的装饰器，才能去装饰函数。如果不小心少写一层，就会把函数传给工厂而不是把函数传给装饰器。
排查：记住口诀——工厂收参数，装饰器收函数，wrapper收具体调用参数。三层各司其职，错了就用这种对应关系来定位。
7.5 闭包中变量绑定陷阱
症状：所有装饰器实例共享同一个外层变量，相互影响。
原因：闭包中如果直接使用外层函数里的可变对象，多个装饰器实例可能共享状态。比如在函数体内直接用一个列表做缓存，这个列表是在装饰器定义时创建的，多个函数共用。
排查：确认缓存、计数器这类状态变量是定义在装饰器工厂调用之后还是之前。定义在decorator内、wrapper外的变量，是每个被装饰函数独立一份的。
7.6 测试时被装饰函数无法用mock直接替换
症状：单元测试里想mock某个被装饰函数，结果打不上补丁，或者补丁无效。
原因：装饰器在函数定义时就完成了替换，测试时看到的函数是wrapper，不是原函数。要mock必须针对模块里实际存在的名字来操作。
排查：mock.patch时要patch模块中该名字对应的对象。如果你知道装饰器逻辑会改函数名，建议在类装饰器里用update_wrapper保留一定的可追踪性。
8. 这段经历让我养成的几个习惯
写装饰器这几年，我慢慢养成了一些固定习惯，也算是在实战里踩坑踩出来的经验。
一是在写任何装饰器的一开始就加上from functools import wraps，不给自己留“忘了写”的机会。
二是设计带参数装饰器时先问自己：这个参数是“每个被装饰函数需要独立一份”，还是“所有被装饰函数共享一份”？这决定了状态变量放在哪一层。这个想清楚，比代码能不能跑更重要。
三是写完之后习惯性地跑一下dir()或者打印__name__，确认函数身份未被丢失。这个检查只需要几秒钟，却能避免后面排查时的巨大麻烦。
四是对于所有装饰器都做一个简单的单元测试，测试点至少覆盖：原函数被调用、返回值正确、参数能透传、异常能透传。有了这几项保障，后续把装饰器用到生产环境时才不会心虚。
装饰器在Python里就像一把多功能瑞士军刀，初看觉得花哨，一旦用顺手了就会觉得离不开。从最简单的日志埋点，到复杂的缓存、重试、鉴权系统，你都会不自觉地想到用装饰器来组织横切逻辑。我以前觉得写业务逻辑最核心的是算法和数据结构，后来发现，像装饰器这样能把代码组织得干净利落的语言特性，其实同样重要。
