我debug了三年Python代码，头两年最怕的就是看到别人写的装饰器。那玩意儿看起来像天书，一层套一层，根本不知道执行顺序是什么。但等我真正把装饰器吃透之后，再看那些祖传代码，简直就像戴了夜视仪——那些重复的日志逻辑、权限校验、超时重试，全是靠这层“外挂”拆出去的。
这个比喻很贴切：装饰器就是给函数穿上“钢铁侠战衣”。托尼·史塔克本身还是那个人，穿上战衣才能飞、能发射激光、能扛导弹。函数也一样，核心业务逻辑不动，通过装饰器在外面套上额外的能力。你不需要在函数内部改一行代码，就能让它自动打日志、自动计算耗时、自动重试失败请求。这篇文章不整那些花活，就是从头手写装饰器，把原理、写法、实战场景和踩坑记录全过一遍。看完你不仅能看懂别人的装饰器，还能自己设计出优雅的重试机制和缓存逻辑。
1. 从零拆解装饰器：它到底在解决什么问题
1.1 一段让人崩溃的重复代码
先看一个很多人天天在写的场景。你负责一个订单模块，有create_order、cancel_order、query_order三个函数，项目经理要求在每次调用前后都打日志，方便排查线上问题。于是代码变成了这个样子：
def create_order(user_id, product_id, count): print(f"[LOG] 调用 create_order，参数：{user_id}, {product_id}, {count}") # 假装这里有几百行业务逻辑 order_id = 9527 print(f"[LOG] create_order 执行完成，返回：{order_id}") return order_id def cancel_order(order_id): print(f"[LOG] 调用 cancel_order，参数：{order_id}") # 又是一大堆逻辑 result = "已取消" print(f"[LOG] cancel_order 执行完成，返回：{result}") return result这代码有问题吗？能跑，月薪三千。但当你需要给第三个、第四个、第五个函数加日志时，你会发现自己陷入了一场复制粘贴的噩梦。更可怕的是，如果哪天日志格式要加一个时间戳，你就要跑到每个函数里改，漏改一个线上排查就费半天劲。这就是典型的需求变更灾难——你想改的是横切在十几个函数之上的公共逻辑，却被迫把每个函数都动一遍。
装饰器解决的就是这个痛点：把横切关注点和核心业务拆开。横切关注点就是那些跟业务无关、但每个函数都要处理的公共事务，比如日志、鉴权、事务、缓存、重试。有了装饰器，你的业务函数永远只需要关注自己那一亩三分地，公共逻辑全部收拢到装饰器里，一处修改，处处生效。
1.2 Python函数的一等公民身份
很多初学者一直看不懂装饰器，是因为脑子里缺了一个关键认知：Python里函数和整数、字符串一样，是一等公民。意思是函数可以像变量一样被赋值、被当作参数传给另一个函数、被当作返回值从函数里丢出来。
def say_hello(name): return f"你好，{name}" # 函数可以赋值给变量 greet = say_hello print(greet("张三")) # 你好，张三 # 函数可以作为参数传入 def call_with_zhang(func): return func("张三") print(call_with_zhang(say_hello)) # 你好，张三 # 函数可以作为返回值 def get_func(): return say_hello print(get_func()("李四")) # 你好，李四体会到那种感觉了吗？函数就跟你家沙发一样，想搬到哪里就搬到哪里。正是因为函数能作为参数和返回值传递，我们才有机会写出一个“通用包装器”：接收一个函数，返回一个新的函数。这个包装器可以在内部决定什么时候调用原函数、调用前后做什么事。
1.3 闭包：装饰器的心脏
闭包这个概念听着玄乎，拆开就两件事：内层函数引用外层函数的变量，并且外层函数把这个内层函数返回出去。这个组合在外层函数执行完毕后依然有效，因为内层函数把外层函数的变量“随身携带”了。
def outer(x): def inner(y): return x + y return inner add_5 = outer(5) print(add_5(10)) # 15这里的x本来属于outer的局部变量，outer执行完就该消失了。但inner还在引用它，Python就觉得这变量不能回收，于是x被保存在inner的“闭包环境”里。之后你调用add_5(10)，inner依然记得x = 5。
装饰器就是闭包最经典的用法：外层函数接收一个函数func，内层函数wrapper调用func并在前后加料，最后外层函数把wrapper返回。你拿到手的还是一个函数，但已经是穿了战衣的强化版。
1.4 @语法糖究竟做了什么
@符号看起来神秘，拆开来看就是一次函数调用加一次赋值。这两行代码：
@my_decorator def add(a, b): return a + b等价于：
def add(a, b): return a + b add = my_decorator(add)就这么朴素。@my_decorator其实就是“把 add 这个函数作为参数扔进 my_decorator，然后把返回的新函数重新赋值给 add”。所以装饰器不一定要用@写，你完全可以手动调用，但语法糖写起来优雅得多，而且一看就知道这个函数被“包装”过了，代码可读性直接上一个台阶。
上了@之后，有个细节一定要注意：此时add这个名字指向的已经不是原来的函数体，而是装饰器返回的wrapper。你调用add(1, 2)，实际上是调用wrapper(1, 2)。后面讲调试技巧的时候你会看到，这个“名字指向变化”会带来什么坑。
2. 手把手写出你的第一个装饰器
2.1 最朴素的装饰器模板
理论说够了，直接上手。一个通用的装饰器模板我建议你直接背下来，就像程序员的三级头一样焊在脑子里：
import functools def my_decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): # 调用前做点什么 print("准备调用函数") result = func(*args, **kwargs) # 调用后做点什么 print("函数调用完毕") return result return wrapper有四个重点必须理解透。
第一，wrapper必须写成*args, **kwargs这种任意参数的形式。因为你不知道未来要装饰的函数接收几个参数，只有写成任意参数，才能做到“把原函数的参数原封不动地传进去”。不信你试试写死两个参数a, b，然后拿去装饰一个接收三个参数的函数，当场报错。
第二，func(*args, **kwargs)的返回值必须接住并return。很多人第一次写装饰器最容易漏的就是这一步。如果你的func有返回值，而wrapper不把它 return 出去，外层拿到的一律是None。你可能会在排查半天后捶胸顿足——函数逻辑明明没问题，结果就是丢了返回值。
第三，functools.wraps必须在装饰器里默认带上。它做了一件很多人忽略的大事：把原函数的__name__、__doc__、__module__等元信息复制到wrapper上。不加它，等你用inspect或其他框架读取函数信息时，看到的全是wrapper的名字，debug 的时候一脸懵。别偷懒，每次写装饰器都把这三行闭眼写上。
第四，wrapper里的print只是示例，真正的项目里你应该换成日志输出、耗时统计、异常捕获、缓存判断等逻辑。模板的骨架就是“前置处理 + 调用原函数 + 后置处理 + 返回结果”，任何装饰器都是在这个骨架上填肉。
2.2 给装饰器加参数：三层嵌套怎么理解
写着写着你就会发现需求变了：这个装饰器除了接收要被装饰的函数，还想接收一些配置参数。比如做个日志装饰器，不同模块想打印不同级别的前缀，这时候你就需要三层嵌套：
import functools def log_with(prefix): def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): print(f"[{prefix}] 调用 {func.__name__}") result = func(*args, **kwargs) print(f"[{prefix}] {func.__name__} 执行完成") return result return wrapper return decorator @log_with("订单模块") def create_order(user_id, product_id): return 9527这里的三层结构对应三个职责：最外层log_with负责接收配置参数prefix，中间层decorator负责接收函数func，最内层wrapper负责接收真正的业务参数并执行。调用流程就是：先执行log_with("订单模块")得到一个decorator，再把这个decorator应用到create_order上。
很多初学者在这里绕晕，我提供一个简单的记忆方法：看@后面有没有括号。@log_with("订单模块")后面带了括号，说明先调用函数返回装饰器；@my_decorator后面没括号，说明直接把下面的函数传给装饰器。一句话总结：有括号先执行取装饰器，没括号直接用。
2.3 类装饰器：当函数闭包不够直观时
函数式嵌套写多了，有时候连自己都要数一下第几层。如果装饰器内部逻辑比较复杂、需要保存状态或依赖多个方法协作，写成类会更清爽。类装饰器的核心就是让类实例变得可调用：定义__init__接收被装饰的函数，定义__call__实现包装逻辑。
import functools import time class Timer: def __init__(self, func): functools.update_wrapper(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_func(): time.sleep(0.5) return "done"这里有两个细节。第一，functools.update_wrapper(self, func)的作用跟functools.wraps相同，但对象是self，因为类实例要模拟函数的元信息。第二，类装饰器的本质是：slow_func = Timer(slow_func)，此时slow_func是一个Timer实例，每次调用slow_func()都会触发__call__。
类装饰器的优势在于状态维护。比如你要实现一个统计函数调用次数的装饰器，函数闭包也能写，但用类直接在__init__里初始化self.count = 0，每次调用在__call__里self.count += 1，然后你还能给类加一个reset()方法手动清零。这种场景下，类比三层嵌套函数直观得多。
2.4 装饰器语法糖的组合难题
装饰器最容易被低估的难点不是怎么写，而是怎么组合。当你在一个函数上叠了多个装饰器时，执行顺序的直觉往往是错的。看下面这个例子：
def decorator_a(func): @functools.wraps(func) def wrapper(*args, **kwargs): print("A 前") result = func(*args, **kwargs) print("A 后") return result return wrapper def decorator_b(func): @functools.wraps(func) def wrapper(*args, **kwargs): print("B 前") result = func(*args, **kwargs) print("B 后") return result return wrapper @decorator_a @decorator_b def hi(): print("hi")执行hi()，输出顺序是什么？不是 A 前、B 前、hi、B 后、A 后，也不是从 A 开始“包裹”的顺序。正确的执行顺序是：A 前 → B 前 → hi → B 后 → A 后。为什么？因为装饰器的应用顺序是从下往上：hi = decorator_a(decorator_b(hi))。decorator_b(hi)先执行，得到wrapper_b；接着decorator_a(wrapper_b)再执行，得到wrapper_a。所以最终调用链路是wrapper_a进入，执行func（即wrapper_b），再执行真正的hi。
在实际项目里，这个顺序直接决定你的日志前后关系、权限校验和缓存的生效逻辑。比如你想一个接口先做权限校验再做参数校验，那权限校验的装饰器就要写在下面（离函数更近），因为它是先被应用的、在调用链的最外层。
3. 装饰器的实战场景：日志、计时、权限、缓存、重试
3.1 日志记录：业务代码里最该先抽出去的逻辑
日常项目中，装饰器用得最多的场景就是日志。把日志逻辑硬塞进业务函数，最大的问题是噪声污染——你看代码时满眼都是print或logger.info，真正的业务逻辑被埋在一堆日志调用的缝隙里，很难一眼看出这个函数到底在干嘛。
用装饰器把日志抽出去之后，函数只剩两行核心逻辑：
import functools import logging logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") logger = logging.getLogger(__name__) def log_call(func): @functools.wraps(func) def wrapper(*args, **kwargs): logger.info(f"进入 {func.__name__}, args={args}, kwargs={kwargs}") try: result = func(*args, **kwargs) logger.info(f"退出 {func.__name__}, 结果={result}") return result except Exception as e: logger.exception(f"{func.__name__} 出错: {e}") raise return wrapper @log_call def add(a, b): return a + b加一个try...except包裹后，这个装饰器甚至能帮你统一记录异常堆栈。线上出bug时，那些日志就是你的黑匣子——上面记录的args、kwargs、result、异常信息，配合时间戳，基本能定位九成以上的问题。我自己在服务端代码里就是靠这一招，把排查一个问题从翻日志找半小时缩短到两分钟。
一个进阶技巧：给log_call增加一个开关参数，比如@log_call(enabled=False)，这样你可以在测试环境全量开启日志，生产环境按需开启某些核心函数，而不需要删代码或注释装饰器。开关控制的实现就是在装饰器内部加一个if not enabled: return func(*args, **kwargs)的短路逻辑。
3.2 性能计时：毫秒级定位慢函数
性能优化最怕的不是慢，而是不知道哪里慢。全凭猜的话，你很可能把时间花在了根本不影响瓶颈的函数上。一个性能计时装饰器就派上用场了：
import functools import time import statistics def timeit(repeats=1): def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): total = 0 best = float("inf") for _ in range(repeats): start = time.perf_counter() result = func(*args, **kwargs) elapsed = time.perf_counter() - start total += elapsed best = min(best, elapsed) avg = total / repeats print(f"{func.__name__}: avg={avg:.6f}s best={best:.6f}s (repeats={repeats})") return result return wrapper return decorator @timeit(repeats=5) def build_report(): time.sleep(0.1) return "report ready"为什么用time.perf_counter()而不是time.time()？因为perf_counter是专门为测量短时间间隔设计的，精度极高，受系统时间调整影响小；而time.time()返回的是墙上时钟，精度可能只有毫秒级，而且系统校时会导致跳变。测一个微秒级的函数，用time.time()得到的结果是废的。
加repeats参数是我在实际优化中总结出来的经验。单个函数的首次调用可能有冷启动开销（比如加载缓存、连接池初始化），跑一次测出来的数据波动很大。跑五遍取平均值和最佳值，能把噪声过滤掉，定位真正的性能瓶颈。优化完之后再跑一遍这个装饰器，对比平均值下降多少，这就是你优化的量化成果。
3.3 权限校验：给接口加一道门禁
在Web后端或者内部工具里，权限校验是另一种横切逻辑。没有装饰器的时候，你会在每个handler函数开头写一遍if not check_permission(user): raise Forbidden。有了装饰器，校验逻辑集中在最外层执行，不通过的请求直接拦截，业务函数连自己被校验过这件事都不知道。
import functools def require_role(role): def decorator(func): @functools.wraps(func) def wrapper(user, *args, **kwargs): if user.get("role") != role: raise PermissionError(f"需要 {role} 权限，当前用户等级不足") return func(user, *args, **kwargs) return wrapper return decorator @require_role("admin") def delete_user(user, user_id): return f"用户 {user_id} 已删除" # 正常调用 admin = {"name": "张三", "role": "admin"} normal = {"name": "李四", "role": "user"} delete_user(admin, 1001) # 正常 delete_user(normal, 1002) # 抛出 PermissionError这个例子里有个很实用的设计：把user作为参数传给装饰器。实际项目中user可能来自请求的 session、JWT 或者某个全局上下文。装饰器拿到用户身份，执行权限判断，通过后再把user透传给业务函数。这样业务代码就不需要自己判断“我有没有权限”，而是默认执行到这里就已经是授权状态了。
权限装饰器还常跟“操作审计”结合：在校验通过之后、调用业务函数之前，插入一条审计日志，记录谁在什么时间执行了什么操作。这种组合用法威力巨大——一个装饰器同时搞定鉴权和审计，业务开发根本不用关心这两件事。
3.4 结果缓存：递归加速的救星
缓存是装饰器最直观的“战衣”效果。拿经典的斐波那契数列举例，纯递归写法时间复杂度是指数级，N稍微大一点就卡死。但你只需要加一个缓存装饰器，性能立刻飙升到 O(N)。
import functools def cached(func): cache = {} @functools.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 @cached def fib(n): if n < 2: return n return fib(n - 1) + fib(n - 2) print(fib(100)) # 瞬间出结果这个手写缓存的思路值得理解：用(args, kwargs)拼成一个可哈希的 key，第一次调用时计算并存入字典，后续直接命中。Python的标准库里其实已经有现成的functools.lru_cache，比我这版更强大，支持最大缓存数量、统计命中率等。但理解手写版本能帮你明白lru_cache背后到底做了什么。
lru_cache用起来更省心，默认直接加，还能控制缓存上限：
import functools @functools.lru_cache(maxsize=128) def get_user_info(user_id): # 模拟从数据库查询 return {"id": user_id, "name": f"用户{user_id}"}小提示：lru_cache要求被装饰函数的参数必须是可哈希的。列表、字典这些可变类型传进去会直接报错。如果你确实需要缓存带不可哈希参数的结果，就得自己做序列化处理，比如把列表转成元组再作为 key。
缓存的一个经典坑是“缓存穿透”和“缓存雪崩”，在接口层面如果对查询结果做了缓存，但查询失败直接抛异常，那异常情况就不会被缓存，导致每次失败请求都穿透到数据库。所以写缓存装饰器时，建议只缓存成功的返回值，异常直接抛出、不缓存。这样失败时可以快速重试，而不会命中脏缓存。
3.5 重试机制：让临时故障不背锅
写爬虫、调用第三方API、操作数据库的时候，最烦的就是临时性网络抖动。一次超时不代表服务挂了，也许下一秒就好了。手动写重试逻辑会污染业务代码，而且写出来大概率是三重循环加各种状态变量，又丑又难测。重试装饰器就是专门处理这种场景的：
import functools import time def retry(max_attempts=3, delay=1.0, 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_attempts=5, delay=0.5, exceptions=(ConnectionError, TimeoutError)) def fetch_data(): # 模拟远程API调用 import random if random.random() < 0.4: raise ConnectionError("网络抖动") return {"data": 123}这个装饰器有两点要拿捏。第一，exceptions参数要窄不要宽。默认值(Exception,)虽然方便，但会把代码bug也重试五次，浪费资源还可能掩盖真实问题。更好的做法是只重试那些“临时性故障”，比如连接错误、超时、服务暂时不可用；程序逻辑错误就别重试了，重试一百次也是错。第二，delay参数可以做成指数退避——每失败一次，等待时间翻倍。这样避免重试请求同时打到服务端造成更大的压力。指数退避是分布式系统里的一种通用策略，很多API客户端就是这么做的。
这个装饰器还能延伸出一个进阶玩法：加上最大重试时间限制。比如规定整体重试不超过30秒，超过就放弃，配合delay递增策略，能更精细地控制容错行为。
4. 常见问题与排查技巧实录
4.1 多个装饰器的执行顺序到底怎么算
这个问题我在前面已经给出答案了，但还是值得从排查角度再讲一遍。当你看到这样的堆叠：
@log_call @timeit(repeats=3) def query(user_id): pass虽然它读起来是从上到下，但实际执行顺序是：query = log_call(timeit(repeats=3)(query))。也就是说，timeit先包装好query，log_call再包装timeit的结果。调用时最先进入的是log_call的wrapper，最后才执行真正的query。
排查顺序问题时，你可以在每个装饰器的wrapper里加一行带函数名的打印。跑一次你就看到完整的洋葱模型了。设计装饰器组合时，我的经验法则是：把越通用的横切逻辑放在越外面（离业务函数越远）。日志和异常捕获放最外层，缓存放稍内层，权限校验也靠外层，因为被拦截的请求不该触发日志和缓存。
4.2 参数混淆：何时传装饰器参数，何时传函数参数
新手最常犯的“灵异事件”是把装饰器参数和函数参数搞混。一切的判断基准还是看@后面有没有调用：
# 错误示范：装饰器不带参数，却写成带调用 @timeit() # 此时会先执行 timeit()，返回一个装饰器，然后.... # 正确：如果 timeit 定义为接收 func，就直接 @timeit如果装饰器函数是这样定义的：
def decorator(func): ...那么@decorator直接用就行。反过来，如果是带参数装饰器：
def decorator(arg1, arg2): ...那么@decorator(x, y)才能用。如果写成@decorator，你实际上是把下面的函数当成了arg1传给decorator，返回的很可能是decorator内部定义的wrapper吗？不，问题大了：此时decorator的arg1是函数，arg2缺失直接报错。
解决这类问题的方法很简单：报错时看 traceback 里函数调用的层级。如果提示缺少参数，第一反应检查@后面的括号是否和装饰器定义的方式匹配。把这个判断条件想一遍，90%的参数错误都能当场解决。
4.3 调试技巧：用签名和命名空间还原真相
装饰器带来的调试噩梦是：函数的名字变了、签名变了、注释丢了。你print(func.__name__)，得到的是wrapper，不是业务函数名。排查时你怎么确认这个函数到底有没有被装饰过？
三个工具组合使用。第一，functools.wraps已经解决了元信息复制的问题，所以前提是每个装饰器都老老实实写functools.wraps(func)。第二，Python 3.4+ 的functools提供了一个__wrapped__属性，装饰器会把这个属性指向原函数，你可以顺着链条找到最原始的函数。第三，inspect.signature可以检测函数的参数签名，如果被装饰后的函数签名变了，调用时可能出现意想不到的兼容问题。
import inspect print(inspect.signature(query)) # (user_id: int) -> None print(query.__wrapped__) # <function query at 0x...>如果发现query的签名是(*args, **kwargs)而不是实际的(user_id)，说明装饰器没有正确透传参数信息。某些依赖签名做参数的框架（比如 FastAPI、DRF）会因此出问题，这种时候你要么给wrapper手动设置__signature__，要么检查装饰器是否写了functools.wraps。
另外一个小技巧：在装饰后的函数上调用help()或查看文档字符串，如果看到的是wrapper的文档而不是原函数的，说明装饰器没有functools.wraps。这时候补上它，你的API文档、IDE提示、自动补全都会恢复正常。
4.4 一个容易被忽略但值得单独说的情况：装饰器的求值时机
很多人在模块导入时发现副作用比预期来得更早，原因就是装饰器的执行时机。装饰器在函数定义时就执行了，不是首次调用时执行。也就是说，@decorator这行代码，在模块被 import 的那一刻就会运行。如果你的装饰器里有重操作（比如初始化数据库连接、加载大型配置），它会在模块导入阶段就执行，拖慢启动速度。
这个特性有时候会被“误打误撞”变成有用的机制。比如你想在注册表里自动收集所有被装饰的函数，可以让装饰器在定义时把函数名加入一个全局列表：
_all_handlers = {} def register_handler(name): def decorator(func): _all_handlers[name] = func return func return decorator @register_handler("create") def create_handler(): pass @register_handler("delete") def delete_handler(): pass这也是装饰器的一种高级玩法：装饰器的主要目的不是包装函数，而是利用函数定义的时机完成注册。写生产级框架、插件系统时这个模式很常见。但要注意，如果你依赖这种机制，一定要保证模块被 import 过——有时候你写了@register_handler，却忘了 import 那个模块，注册表里永远找不到这个函数。
最后再分享一个我个人的体会：装饰器没学会之前，你会觉得它是某种炫技的黑魔法；真正上手之后你会发现，它不过是一种把代码从别人身上复制到自己身上的约束工具。每次写业务代码之前，先想一想哪些逻辑在横切面，哪些是真正的核心业务，把横切逻辑抽成装饰器，你的代码会干净得让同事怀疑你雇了代码洁癖。我自己在项目里已经把日志、鉴权、缓存、重试这些基础设施全部抽成了装饰器，业务模块纯粹得只剩下业务逻辑。遇到复杂场景，无非就是三层嵌套加上functools.wraps模板的变体，琢磨清楚原理，一切都有迹可循。
