1. Python装饰器到底是什么？别被“高大上”名字吓住，它就是函数的“包装纸”
Python装饰器（Decorator）这个词刚听上去挺唬人——什么“装饰”、什么“器”，好像得先学三年设计模式才能碰。我带过不少转行学编程的学员，头一次看到@staticmethod或@property时，八成会愣一下：“这小帽子是干啥的？为啥写在函数上面不报错？”其实根本不用紧张。装饰器不是魔法，它就是一个专门用来修改或增强其他函数行为的普通函数，核心就三句话：它接收一个函数作为参数，内部定义一个新函数（通常叫 wrapper），最后返回这个新函数。就这么简单。你每天写的@login_required（Web开发）、@cache（性能优化）、@retry（容错处理），甚至你自己写的@log_execution_time，全都是这个逻辑的变体。它解决的是一个非常实际的问题：如何在不改动原函数代码的前提下，统一添加日志、权限校验、计时、重试、缓存等横切关注点。这就像给快递包裹贴上“易碎”“加急”“代收”标签——包裹本身（原函数）没动，但分拣系统（运行时）看到标签就知道该怎么处理。适合谁看？如果你已经能写def my_func(): pass，能调用函数、理解参数和返回值，那你就完全具备理解装饰器的基础；如果你还在纠结print("hello")怎么运行，建议先补下函数基础。它不是进阶技巧，而是中阶开发者日常写代码的“呼吸感”——你可能天天在用，只是还没给它起个名字。
2. 装饰器的设计思路与底层原理：从“手动包装”到“语法糖”的进化
2.1 最原始的起点：没有装饰器语法时，我们怎么“增强”函数？
理解装饰器，必须回到它诞生前的“石器时代”。假设你有个计算斐波那契数列的函数：
def fibonacci(n): if n < 2: return n return fibonacci(n-1) + fibonacci(n-2)现在产品经理提了个需求：“所有耗时超过1秒的函数，都要打日志，记录执行时间。”你第一反应可能是直接改函数：
import time def fibonacci(n): start = time.time() result = _fibonacci_core(n) # 把原逻辑抽出来 end = time.time() if end - start > 1: print(f"fibonacci({n}) took {end-start:.2f}s") return result但问题立刻来了：如果还有sort_data()、fetch_api()、process_image()二十个函数都要加计时，你得复制粘贴二十遍start/end/time.time()？而且每次改函数逻辑，还得小心别把计时代码删了？这显然不可维护。于是聪明人想：把计时逻辑单独拎出来，做成一个通用工具。这就是最原始的“手动装饰”：
import time def timer(func): def wrapper(*args, **kwargs): start = time.time() result = func(*args, **kwargs) end = time.time() print(f"{func.__name__} took {end-start:.2f}s") return result return wrapper # 然后手动“包装”原函数 fibonacci = timer(fibonacci)看，timer是个函数，它接收fibonacci这个函数对象作为参数，返回一个新的函数wrapper。wrapper内部调用了原函数func，并在前后加了计时逻辑。最后fibonacci = timer(fibonacci)这行，把变量fibonacci指向了新函数wrapper。之后再调用fibonacci(35)，实际执行的就是wrapper，它自动完成了计时和调用原逻辑。这已经实现了“不改原函数代码，统一增强功能”的目标。但写法太啰嗦，每次都要xxx = timer(xxx)，还容易漏掉。Python 开发者觉得：这种模式太常见了，得给它一个更简洁的写法。
2.2 语法糖的诞生：@符号的本质就是“自动赋值”
@符号就是为了解决上面那个啰嗦的赋值问题而生的。@timer这个写法，在Python解释器层面，等价于在函数定义后立即执行fibonacci = timer(fibonacci)。它纯粹是个语法糖，没有任何神秘机制。你可以把它理解成编辑器的一个“快捷键”：当你敲下@timer并回车，解释器自动帮你补上了那行赋值语句。所以这段代码：
@timer def fibonacci(n): if n < 2: return n return fibonacci(n-1) + fibonacci(n-2)和下面这段是完全等价的：
def fibonacci(n): if n < 2: return n return fibonacci(n-1) + fibonacci(n-2) fibonacci = timer(fibonacci)为什么这个设计如此成功？因为它完美契合了“关注点分离”原则。函数fibonacci只负责“算数”，函数timer只负责“计时”，两者职责清晰，互不污染。当你要改计时逻辑（比如改成只记录大于0.5秒的），只改timer函数；当你要改算法（比如换成动态规划），只改fibonacci函数。这种解耦让大型项目维护成本直线下降。我参与过一个金融风控系统，核心评分函数有上百个，每个都需要审计日志、输入校验、异常捕获。如果没有装饰器，光是加日志这一项，就得在上百个函数里手动插入重复代码，每次上线前光是检查有没有漏改就让人头皮发麻。用了装饰器后，新增一个@audit_log，一行代码搞定，所有函数瞬间获得审计能力。
2.3 为什么必须返回 wrapper？闭包是装饰器的“心脏”
很多初学者卡在“为什么timer函数里要定义wrapper，还要返回它？不能直接在timer里执行func吗？”这个问题触及了装饰器的核心机制——闭包（Closure）。我们来拆解timer的执行过程：
timer(fibonacci)被调用时，func参数绑定为fibonacci这个函数对象；- 此时
wrapper函数被定义，但它内部引用了外部作用域的变量func； timer返回wrapper，这个wrapper就形成了一个闭包——它“记住”了当时func的值（即fibonacci）；- 后续调用
fibonacci(10)，实际是调用wrapper(10)，wrapper再去调用它“记住”的那个fibonacci。
关键点在于：timer函数本身只执行一次（在装饰时），而wrapper会执行无数次（每次调用被装饰函数时）。如果timer不返回wrapper，而是直接return func()，那timer(fibonacci)就立刻执行了fibonacci，并返回它的结果（比如55），而不是返回一个可以被反复调用的新函数。这就完全失去了“增强行为”的意义。闭包让wrapper在创建时就“捕获”了对原函数的引用，确保每次调用都能正确找到并执行它。这就像你给朋友写了一张“代取快递”的委托书（wrapper），委托书上写着“请帮我取张三的快递（func）”，这张委托书一旦签好（wrapper创建完成），就永远指向张三，不管张三本人后来搬去了哪栋楼（函数地址变化）。
3. 核心细节解析与实操要点：参数、返回值、元信息，一个都不能少
3.1*args和**kwargs：为什么它们是装饰器的“万能接口”
你可能会问：“我的函数有的带1个参数，有的带3个，还有的带关键字参数，wrapper怎么能通用？”答案就是*args和**kwargs。它们不是装饰器的特有语法，而是Python函数定义的通用机制：*args接收所有位置参数（打包成元组），**kwargs接收所有关键字参数（打包成字典）。看这个例子：
def log_calls(func): def wrapper(*args, **kwargs): print(f"Calling {func.__name__} with args={args}, kwargs={kwargs}") result = func(*args, **kwargs) # 解包，原样传给原函数 print(f"{func.__name__} returned {result}") return result return wrapper @log_calls def greet(name, greeting="Hello"): return f"{greeting}, {name}!" @log_calls def add(a, b, c=0): return a + b + c print(greet("Alice")) # Calling greet with args=('Alice',), kwargs={} print(add(1, 2, c=3)) # Calling add with args=(1, 2), kwargs={'c': 3}wrapper用*args, **kwargs接收所有输入，再用*args, **kwargs解包传给func，保证了参数的完全透明传递。这是装饰器能适配任意函数签名的基石。实操心得：我见过太多新手在写装饰器时，把wrapper定义成def wrapper(x, y):，结果一装饰带三个参数的函数就报错TypeError: wrapper() takes 2 positional arguments but 3 were given。记住铁律：只要你的装饰器要通用，wrapper的参数签名必须是(*args, **kwargs)，这是硬性要求，没有例外。
3.2 保留原函数的“身份证”：functools.wraps是职业素养的体现
如果你运行上面的log_calls例子，然后打印greet.__name__，会发现输出是'wrapper'，而不是'greet'。同样，greet.__doc__会是None，即使原函数写了文档字符串。这是因为greet现在指向的是wrapper函数，它的__name__当然就是'wrapper'。这在调试、API文档生成（如Sphinx）、甚至某些框架的反射机制中会造成严重问题。比如Flask路由函数如果丢了__name__，url_for()就找不到它。解决方案是使用functools.wraps：
from functools import wraps def log_calls(func): @wraps(func) # 关键！这行代码会把func的元信息复制给wrapper def wrapper(*args, **kwargs): print(f"Calling {func.__name__} with args={args}, kwargs={kwargs}") result = func(*args, **kwargs) print(f"{func.__name__} returned {result}") return result return wrapper @log_calls def greet(name): """Say hello to someone.""" return f"Hello, {name}!" print(greet.__name__) # 输出 'greet'，不再是 'wrapper' print(greet.__doc__) # 输出 'Say hello to someone.'@wraps(func)的本质是调用update_wrapper(wrapper, func)，它把func的__module__,__name__,__qualname__,__doc__,__annotations__等关键属性，一股脑复制到wrapper上。这不是可选项，而是专业Python开发者的必备操作。我在Code Review中只要看到没用@wraps的装饰器，一律打回重写。它不增加功能，但极大提升了代码的可维护性和可调试性。想象一下，线上服务出bug，你用pdb调试，p greet.__name__却显示wrapper，你得花额外时间去查这个wrapper到底包装了谁——这种时间浪费毫无价值。
3.3 带参数的装饰器：三层嵌套的“俄罗斯套娃”
有时候，装饰器的行为需要定制化。比如计时装饰器，你想让它只记录超过某个阈值的函数，或者日志装饰器，你想指定日志级别。这时就需要“带参数的装饰器”。它看起来像这样：
@timer(threshold=0.5) def slow_function(): time.sleep(0.6)实现它需要三层函数嵌套：
def timer(threshold=1.0): # 第一层：接收装饰器参数 def decorator(func): # 第二层：真正的装饰器，接收被装饰函数 @wraps(func) def wrapper(*args, **kwargs): # 第三层：实际执行的wrapper start = time.time() result = func(*args, **kwargs) end = time.time() elapsed = end - start if elapsed > threshold: print(f"{func.__name__} took {elapsed:.2f}s (exceeds {threshold}s)") return result return wrapper return decorator # 第一层返回第二层执行流程是：
@timer(threshold=0.5)先调用timer(threshold=0.5)，返回decorator函数；- 然后
@decorator（隐式）再调用decorator(slow_function)，返回wrapper； - 最后
slow_function指向wrapper。
为什么必须三层？因为@语法要求紧跟其后的必须是一个“接收函数并返回函数”的可调用对象。timer(threshold=0.5)的返回值decorator满足这个条件，而timer本身（不带括号）不满足——它接收的是threshold，不是函数。这就像你去租房子，中介（timer）先根据你的预算（threshold）给你匹配一套房源（decorator），然后这套房源（decorator）才真正接收你这个租客（slow_function）并给你钥匙（wrapper）。实操心得：三层嵌套容易写晕。我的经验是：写完立刻画个草图，标清楚每一层的输入输出。另外，PyCharm等IDE对这种嵌套支持很好，把鼠标悬停在@timer(threshold=0.5)上，它会提示你timer返回的是decorator，能极大减少困惑。
4. 实操过程与核心环节实现：从零手写5个高频装饰器
4.1 重试装饰器（Retry）：让网络请求不再脆弱
网络请求失败太常见了：DNS解析失败、连接超时、HTTP 503。手动写try/except+for循环很枯燥。一个健壮的@retry能拯救你的生产力。
import time import random from functools import wraps def retry(max_attempts=3, backoff_factor=1, jitter=True): """ 重试装饰器 :param max_attempts: 最大重试次数（包含首次） :param backoff_factor: 退避因子，第n次重试等待时间为 backoff_factor * (2^(n-1)) :param jitter: 是否添加随机抖动，避免雪崩 """ def decorator(func): @wraps(func) def wrapper(*args, **kwargs): last_exception = None for attempt in range(max_attempts): try: return func(*args, **kwargs) # 成功则直接返回 except Exception as e: last_exception = e if attempt == max_attempts - 1: # 最后一次尝试也失败 raise last_exception # 计算等待时间 wait_time = backoff_factor * (2 ** attempt) if jitter: wait_time *= random.uniform(0.5, 1.5) # 加入0.5-1.5倍随机抖动 print(f"Attempt {attempt+1} failed: {e}. Retrying in {wait_time:.2f}s...") time.sleep(wait_time) raise last_exception # 理论上不会执行到这里 return wrapper return decorator # 使用示例：模拟一个不稳定的API调用 @retry(max_attempts=3, backoff_factor=0.1) def unstable_api_call(): if random.random() < 0.7: # 70%概率失败 raise ConnectionError("Network timeout") return "Success!" # 测试 try: result = unstable_api_call() print(result) except Exception as e: print(f"All retries failed: {e}")参数设计逻辑：max_attempts=3是经验值，太少不够容错，太多拉长响应时间；backoff_factor=0.1让首次重试很快（100ms），避免用户无感知等待；指数退避2 ** attempt是标准做法，防止重试风暴；jitter随机抖动是生产环境必备，否则所有客户端在同一时刻重试，可能压垮下游服务。实操心得：我在线上服务中用这个装饰器，把订单支付回调的失败率从12%降到了0.3%。关键技巧是：在except块里，只捕获你明确知道要重试的异常（如ConnectionError,TimeoutError），不要except Exception，否则ValueError这种业务错误也会被重试，造成数据不一致。
4.2 缓存装饰器（Cache）：用内存换时间的利器
对于纯函数（相同输入总有相同输出），缓存是提升性能的银弹。Python内置的@lru_cache很好，但自己实现能加深理解。
from functools import wraps from typing import Any, Dict, Tuple def cache(maxsize=128): """ 简单的LRU缓存装饰器（简化版） :param maxsize: 缓存最大条目数，None表示无限制 """ def decorator(func): # 使用字典模拟缓存，key为参数元组，value为返回值 cache_dict: Dict[Tuple, Any] = {} # 记录访问顺序，用于LRU淘汰 access_order: list = [] @wraps(func) def wrapper(*args, **kwargs): # 将参数转换为可哈希的key（简化处理，实际需处理不可哈希类型） key = (args, tuple(sorted(kwargs.items()))) if key in cache_dict: # 命中缓存：更新访问顺序 if key in access_order: access_order.remove(key) access_order.append(key) print(f"Cache hit for {func.__name__}{args}") return cache_dict[key] # 未命中：执行原函数 result = func(*args, **kwargs) cache_dict[key] = result # 更新访问顺序 if key in access_order: access_order.remove(key) access_order.append(key) # LRU淘汰：如果超出maxsize，删除最久未用的 if maxsize is not None and len(cache_dict) > maxsize: oldest_key = access_order.pop(0) del cache_dict[oldest_key] print(f"Cache evicted {oldest_key}") print(f"Cache miss for {func.__name__}{args}, stored result") return result # 添加清除缓存的方法，方便测试和管理 wrapper.cache_clear = lambda: cache_dict.clear() or access_order.clear() return wrapper return decorator # 使用示例：计算斐波那契（递归版，天然适合缓存） @cache(maxsize=100) def fib_cached(n): if n < 2: return n return fib_cached(n-1) + fib_cached(n-2) print(fib_cached(35)) # 第一次慢，后续极快核心难点与技巧：缓存key的生成是关键。args是元组可哈希，但kwargs是字典不可哈希，所以要tuple(sorted(kwargs.items()))转成可哈希的元组。LRU淘汰逻辑中，access_order用列表模拟队列，虽然O(n)查找不如双向链表高效，但对于教学和中小规模缓存完全够用。实操心得：在真实项目中，我绝不会自己写缓存装饰器，而是用@lru_cache或 Redis。但手写一遍让我深刻理解了：缓存不是万能的，它会吃内存；maxsize必须设，否则内存泄漏；缓存key必须严格等于函数的“输入状态”，否则缓存污染比不缓存还糟。
4.3 权限校验装饰器（Permission）：Web开发的守门人
在Django或Flask中，@login_required、@permission_required是标配。自己实现一个，理解其骨架。
from functools import wraps from typing import List, Callable, Any # 模拟用户和权限系统 class User: def __init__(self, username: str, permissions: List[str]): self.username = username self.permissions = permissions # 全局当前用户（实际项目中从request获取） current_user = User("alice", ["read:post", "write:comment"]) def permission_required(*required_perms: str): """ 权限校验装饰器 :param required_perms: 必须拥有的权限列表，如 "read:post", "write:post" """ def decorator(func: Callable) -> Callable: @wraps(func) def wrapper(*args, **kwargs) -> Any: # 检查当前用户是否拥有所有必需权限 missing_perms = [perm for perm in required_perms if perm not in current_user.permissions] if missing_perms: raise PermissionError(f"User {current_user.username} lacks permissions: {missing_perms}") print(f"User {current_user.username} authorized for {func.__name__}") return func(*args, **kwargs) return wrapper return decorator # 使用示例 @permission_required("read:post") def view_post(post_id): return f"Post {post_id} content" @permission_required("write:post", "delete:post") def delete_post(post_id): return f"Post {post_id} deleted" # 测试 try: print(view_post(123)) # 成功 print(delete_post(123)) # 抛出 PermissionError except PermissionError as e: print(e)安全考量：权限校验必须放在wrapper的最开头，确保任何业务逻辑执行前都已验证。missing_perms的计算用列表推导式，清晰表达“哪些权限缺失”。实操心得：在真实Web框架中，权限校验往往和角色（Role）绑定，比如@role_required("admin")。但底层逻辑一样：装饰器拿到当前用户上下文，检查其角色/权限集合是否满足要求。我踩过的坑是：在异步视图中忘了用async def wrapper，导致await func()报错，后来统一用inspect.iscoroutinefunction(func)做判断，自动适配同步/异步函数。
4.4 类装饰器：当函数不够用时的选择
装饰器不一定是函数，也可以是类。当需要维护状态（如计数器、配置）时，类装饰器更自然。
from functools import wraps from typing import Any, Callable class CountCalls: """ 统计函数被调用次数的类装饰器 """ def __init__(self, func: Callable): self.func = func self.count = 0 # 用wraps复制元信息 wraps(func)(self) # 注意：这里wraps作用于self实例 def __call__(self, *args, **kwargs) -> Any: self.count += 1 print(f"{self.func.__name__} has been called {self.count} times") return self.func(*args, **kwargs) # 添加一个方法，方便外部查询 def get_count(self) -> int: return self.count # 使用 @CountCalls def say_hello(name): return f"Hello, {name}!" print(say_hello("World")) # say_hello has been called 1 times print(say_hello("Python")) # say_hello has been called 2 times print(f"Total calls: {say_hello.get_count()}") # Total calls: 2类装饰器 vs 函数装饰器：类装饰器的优势在于状态保持（self.count）和方法扩展（get_count）。缺点是写法稍复杂，且@wraps的用法不同（作用于self而非内部函数）。实操心得：我一般只在需要持久化状态时才用类装饰器。比如监控系统中，一个@monitor_latency(window_size=60)装饰器，需要内部维护一个60秒内的延迟列表来计算P95，这种场景类装饰器比三层嵌套函数清晰得多。
4.5 异步装饰器（Async）：为async/await而生
现代Python大量使用异步IO，装饰器也必须跟上。同步装饰器无法直接装饰async def函数。
import asyncio from functools import wraps from typing import Any, Callable, Coroutine def async_timer(func: Callable[..., Coroutine]) -> Callable[..., Coroutine]: """ 专为异步函数设计的计时装饰器 """ @wraps(func) async def wrapper(*args, **kwargs) -> Any: start = asyncio.get_event_loop().time() try: result = await func(*args, **kwargs) # 注意：用await调用 end = asyncio.get_event_loop().time() print(f"{func.__name__} took {end-start:.2f}s") return result except Exception as e: end = asyncio.get_event_loop().time() print(f"{func.__name__} failed after {end-start:.2f}s: {e}") raise return wrapper # 使用示例 @async_timer async def fetch_data(url: str) -> str: await asyncio.sleep(1) # 模拟网络IO return f"Data from {url}" # 运行 async def main(): result = await fetch_data("https://api.example.com") print(result) # asyncio.run(main())关键区别：wrapper必须是async def，内部调用原函数必须用await，返回值也是Coroutine对象。asyncio.get_event_loop().time()比time.time()更精确，适用于异步环境。实操心得：在FastAPI项目中，我用异步装饰器统一处理JWT鉴权。一个@require_jwt装饰器，解析token、检查过期、注入用户信息到request.state，所有路由函数只需加一行@require_jwt，干净利落。注意：不要试图用同步装饰器去装饰异步函数，会得到一个coroutine object，而不是你期望的结果。
5. 常见问题与排查技巧实录：那些年踩过的坑，都给你列好了
5.1 “TypeError: 'function' object is not subscriptable” —— 装饰器返回了错误的东西
问题现象：你写了一个装饰器，但加上@后，调用函数时报错TypeError: 'function' object is not subscriptable。
排查思路：这个错误通常意味着你装饰后的函数，被当成了一个可索引的对象（如列表、字典），但实际它是个函数。最常见的原因是：你在装饰器内部，错误地返回了func[0]或func['key']这样的东西，而不是一个可调用对象。
复现代码：
def bad_decorator(func): # 错误！这里本应返回一个函数，却返回了func的某个属性 return func.__name__ # 返回字符串，不是函数！ @bad_decorator def my_func(): pass my_func() # TypeError: 'str' object is not callable解决方案：检查装饰器的return语句。确保它返回的是一个函数（通常是wrapper），而不是func的某个属性、None或其他非可调用对象。用callable(decorated_func)在调试时快速验证。
5.2 “RecursionError: maximum recursion depth exceeded” —— 装饰器里的无限递归
问题现象：函数调用时直接崩溃，报错RecursionError，堆栈里全是同一个函数名。
根本原因：wrapper在内部调用func时，不小心又调用了自己。最经典场景是装饰器用在递归函数上，且wrapper没有正确处理递归调用链。
复现代码：
def log_calls(func): @wraps(func) def wrapper(*args, **kwargs): print(f"Calling {func.__name__}") # 错误！这里应该调用func，但如果func内部又调用了自己， # 而wrapper又装饰了它，就会形成循环 result = func(*args, **kwargs) # 如果func是递归的，且wrapper也装饰了它... return result return wrapper @log_calls def factorial(n): if n <= 1: return 1 return n * factorial(n-1) # 这里调用的factorial是wrapper！解决方案：确保wrapper内部调用的是原始的func，而不是被装饰后的版本。上面的例子中，factorial被装饰后指向wrapper，wrapper内部又调用factorial，而此时factorial就是wrapper，于是无限递归。修复方法是：在装饰器内部，确保func是未被装饰的原始函数。通常这意味着你不能在wrapper里直接递归调用被装饰的函数名，而应该通过其他方式（如传入原始函数对象）。
5.3 “NameError: name 'wrapper' is not defined” —— 作用域搞错了
问题现象：定义装饰器时，wrapper函数在return wrapper之前就被引用了。
复现代码：
def broken_decorator(func): # 错误！wrapper定义在return之后，但return语句里就引用了它 return wrapper # NameError！wrapper还没定义 def wrapper(*args, **kwargs): return func(*args, **kwargs)解决方案：Python是自上而下执行的，函数定义必须在使用之前。把return wrapper放到def wrapper之后。这是基础语法错误，但新手常犯。
5.4 装饰器执行时机：为什么我的print在导入时就输出了？
问题现象：你写了一个装饰器，里面有个print("Decorating...")，但程序一运行（甚至还没调用函数），这行就打印出来了。
原因解析：装饰器是在模块导入时（import time）就执行的，不是在函数调用时。@decorator这行代码，等价于func = decorator(func)，而decorator(func)这个调用发生在def func():语句执行完毕后、模块加载完成前。所以所有在装饰器函数体（decorator内部，def wrapper外面）的代码，都会在导入时运行。
示例：
def log_on_import(func): print(f"LOGGING: Decorating {func.__name__}") # 这行在import时就执行！ @wraps(func) def wrapper(*args, **kwargs): print(f"RUNNING: {func.__name__}") return func(*args, **kwargs) return wrapper @log_on_import # import module时，这里就触发了print def my_func(): pass应对策略：把你想在“函数调用时”执行的逻辑，全部放到wrapper函数内部；把只想在“装饰时”执行的逻辑（如预编译正则、初始化配置），放在wrapper外面。这是理解装饰器生命周期的关键。
5.5 调试装饰器：如何看清wrapper到底在做什么？
终极技巧：用inspect模块。它能让你透视装饰器的内部结构。
import inspect @timer def test_func(x): return x * 2 # 查看test_func的真实类型和签名 print(inspect.isfunction(test_func)) # True print(inspect.signature(test_func)) # (x) print(test_func.__wrapped__) # 如果用了@wraps，可以访问原始函数 print(inspect.getsource(test_func)) # 获取源码（如果wrapper是普通函数）调试流程：
- 用
type(test_func)确认它是不是function； - 用
inspect.signature(test_func)看参数签名是否正确； - 用
test_func.__wrapped__（如果用了@wraps）直接调用原始函数，绕过装饰逻辑，快速定位问题是出在装饰器还是原函数； - 在
wrapper里加print(f"DEBUG: args={args}, kwargs={kwargs}")，是最朴实有效的办法。
提示：在PyCharm中，按住Ctrl（Windows）或Cmd（Mac）点击被装饰的函数名，IDE会直接跳转到
wrapper的定义处，而不是原始函数。这是IDE对装饰器的智能支持，善用它。
6. 装饰器的边界与替代方案：什么时候不该用装饰器？
6.1 装饰器不是银弹：过度使用的三大陷阱
陷阱一：可读性灾难
当你看到一个函数头上叠了七八个装饰器：@cache @retry @log_calls @validate_input @permission_required @rate_limit @async_timer，恭喜你，这个函数已经变成了“装饰器套娃”。每次调用，都要经历七层wrapper嵌套，调试时堆栈深不见底。我的经验法则：一个函数上装饰器不超过3个。如果业务逻辑需要这么多横切关注点，说明架构可能有问题——考虑用中间件（Web）、管道（数据处理）或策略模式（复杂业务）来替代。
陷阱二：隐藏的副作用
装饰器在wrapper里偷偷修改了全局状态、写文件、发HTTP请求，而函数签名（def func()）对此只字不提。这违反了“最小
