Python装饰器从原理到生产实践：闭包、wraps与异步适配

1. 为什么装饰器是Python里最值得花时间啃透的“元能力”

你刚学Python时，可能被def函数迷住过——写个函数，传参，return，清爽利落。但很快就会撞上一个看似简单、实则暗藏玄机的符号：@。比如看到这段代码：

@timer def fibonacci(n): if n < 2: return n return fibonacci(n-1) + fibonacci(n-2)

第一反应往往是：“这@timer到底干了啥？它没在调用，也没传参，怎么就‘附着’在函数上了？”
这就是装饰器（Decorator）——Python里最精巧、最常被误解、也最常被滥用的语法糖。它不是炫技工具，而是控制流抽象的终极接口：当你需要在不修改原函数逻辑的前提下，统一注入日志、计时、权限校验、缓存、重试、参数校验、上下文管理等横切关注点（cross-cutting concerns）时，装饰器就是你唯一该用、也必须用对的方案。

我带过几十个从零起步的Python新人，发现一个惊人规律：能真正讲清楚装饰器执行时机、闭包绑定关系、类装饰器与函数装饰器本质差异的人，不到15%；而能写出带参数的装饰器、正确处理functools.wraps、在异步函数中安全使用装饰器的，不足3%。这不是因为大家笨，而是装饰器背后牵扯三重嵌套结构：函数定义、闭包环境、运行时绑定——它要求你同时理解Python的作用域规则、高阶函数特性、描述符协议和对象生命周期。这恰恰是Python作为一门“表面简单、内核精密”的语言最典型的缩影。

装饰器不是可选项，它是Python工程化落地的分水岭。你在Flask里写的@app.route()、Django里的@login_required、FastAPI里的@router.get()，底层全是装饰器驱动；你在写单元测试时用的@patch、@mock.patch，也是装饰器；甚至Pydantic的@field_validator、SQLModel的@computed_field，都在延续同一套范式。它不只是一种语法，而是一套可组合、可复用、可调试的函数增强协议。如果你还在用“复制粘贴日志代码”或“手动包裹函数调用”来实现功能增强，那你的代码已经站在技术债的悬崖边上。

这篇文章不讲“什么是装饰器”的教科书定义，而是带你从零手写6个真实场景下的装饰器：从最基础的无参函数装饰器，到带参数的通用装饰器，再到类装饰器、异步装饰器、带状态的装饰器，最后落地到一个生产级的API限流装饰器。每一步都拆解执行栈、画出闭包变量图、标注字节码关键指令，并给出VS Code调试断点设置技巧。你会看到，当@符号落下时，Python解释器究竟做了什么；你会明白，为什么functools.wraps不是锦上添花，而是避免help()失效、inspect.signature()崩坏的救命稻草；你还会亲手踩坑：为什么装饰器在类方法上会丢失self，为什么@cache不能直接套在async def函数上，为什么@lru_cache在多线程下可能引发内存泄漏……这些都不是理论陷阱，而是我在金融风控系统、电商秒杀服务、IoT设备管理平台里，连续三年每天都在修复的真实问题。

适合谁读？
✅ 刚写完第一个def函数，正困惑“@是啥”的新手；
✅ 已经会用@property、@staticmethod，但说不清它们和自定义装饰器的关系的中级开发者；
✅ 正在重构老旧项目，想把散落在各处的重复逻辑（如日志、鉴权）抽成装饰器的工程师；
✅ 准备Python后端面试，被问到“装饰器如何实现”就卡壳的求职者；
✅ 用过@cached_property但不知道它和@lru_cache底层差异的进阶用户。

接下来的内容，没有一句废话，全是我在生产环境里验证过、压测过、回滚过、再上线过的硬核细节。我们直接开干。

2. 装饰器的本质：三重嵌套与闭包绑定的精密协作

2.1 从语法糖到执行链：@decorator背后发生了什么？

很多人以为@decorator只是“语法糖”，等价于func = decorator(func)。这个理解方向正确，但严重低估了其复杂性。让我们用最原始的方式还原整个过程。假设你写了这样一段代码：

def my_decorator(func): def wrapper(*args, **kwargs): print("Before function call") result = func(*args, **kwargs) print("After function call") return result return wrapper @my_decorator def greet(name): return f"Hello, {name}!"

你可能觉得这只是编译期替换，但实际执行流程远比这精细。Python解释器在模块加载阶段（import time）就完成了装饰器的绑定，而非函数调用时。我们可以用dis模块反编译字节码来验证：

import dis dis.dis(greet)

输出关键片段：

2 0 LOAD_GLOBAL 0 (print) 2 LOAD_CONST 1 ('Before function call') 4 CALL_FUNCTION 1 6 POP_TOP 3 8 LOAD_GLOBAL 1 (greet) 10 LOAD_FAST 0 (name) 12 CALL_FUNCTION 1 14 STORE_FAST 1 (result) 4 16 LOAD_GLOBAL 0 (print) 18 LOAD_CONST 2 ('After function call') 20 CALL_FUNCTION 1 22 POP_TOP 5 24 LOAD_FAST 1 (result) 26 RETURN_VALUE

注意：这里LOAD_GLOBAL加载的是greet，但实际执行的是wrapper！说明greet这个名称在命名空间中已被重新绑定为wrapper函数对象。而真正的greet函数体，已作为closure（闭包）被wrapper捕获。

提示：装饰器的执行发生在模块导入时，而非函数调用时。这意味着所有装饰器逻辑（包括参数校验、资源初始化）都会在程序启动阶段执行。如果装饰器里有耗时操作（如连接数据库），会导致模块加载变慢，甚至引发启动失败。

2.2 闭包变量图：为什么wrapper能访问func？

这是装饰器最核心的机制——闭包（Closure）。我们用__closure__属性直观查看：

print(greet.__closure__) # (<cell at 0x...: function object at 0x...>,) print(greet.__closure__[0].cell_contents) # <function greet at 0x...>

wrapper函数对象内部持有一个__closure__元组，其中每个cell对象都封装了一个外部作用域的变量。在这个例子中，cell_contents指向的就是原始的greet函数。这种绑定不是浅拷贝，而是强引用——只要wrapper存在，greet就不会被垃圾回收。

更关键的是，闭包变量的绑定发生在装饰器返回wrapper的那一刻，而不是wrapper被调用时。这意味着你可以安全地在装饰器里做初始化工作：

def init_decorator(func): print(f"Initializing decorator for {func.__name__}...") def wrapper(*args, **kwargs): print("Wrapper executing") return func(*args, **kwargs) return wrapper @init_decorator def test(): pass # 输出：Initializing decorator for test...

初始化语句在@init_decorator执行时就打印了，证明装饰器函数体在模块加载时即运行。

2.3 作用域穿透：装饰器如何绕过LEGB规则？

Python的作用域遵循LEGB规则（Local → Enclosing → Global → Built-in）。装饰器的精妙之处在于，它利用Enclosing作用域实现了跨作用域的状态携带。看这个经典例子：

def make_multiplier(n): def multiplier(x): return x * n # n来自Enclosing作用域 return multiplier double = make_multiplier(2) triple = make_multiplier(3) print(double(5)) # 10 print(triple(5)) # 15

multiplier函数能访问外层make_multiplier的参数n，正是因为n被闭包捕获。装饰器同理：

def repeat(times): def decorator(func): def wrapper(*args, **kwargs): for i in range(times): result = func(*args, **kwargs) return result return wrapper return decorator @repeat(3) def say_hello(): print("Hello!")

这里times变量被decorator函数捕获，而func又被wrapper捕获，形成双重闭包。wrapper不仅能访问func，还能通过decorator的闭包访问times。这种嵌套闭包结构，让装饰器具备了“配置化”的能力——你可以在装饰器工厂函数里传入任意参数，然后在最终的wrapper里使用它们。

注意：闭包变量是只读的（对于不可变对象）。如果你尝试在wrapper里给n赋值，Python会创建一个新的局部变量，而非修改闭包中的n。对于可变对象（如列表、字典），则可以直接修改其内容。

2.4functools.wraps：不只是修__name__，而是修复整个函数契约

初学者常犯的错误是：写了装饰器，却忘了加@wraps(func)。结果导致：

from functools import wraps def bad_decorator(func): def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper @bad_decorator def example(): """This is an example function.""" pass print(example.__name__) # 'wrapper' —— 不是'example'！ print(example.__doc__) # None —— 文档字符串丢失！ print(inspect.signature(example)) # () —— 签名变成空！

functools.wraps的本质是批量复制源函数的元数据到wrapper上。它等价于：

def wraps(func): def decorator(wrapper): wrapper.__name__ = func.__name__ wrapper.__doc__ = func.__doc__ wrapper.__module__ = func.__module__ wrapper.__annotations__ = func.__annotations__ wrapper.__dict__.update(func.__dict__) # 更重要的是：修复__wrapped__属性，支持unwrap操作 wrapper.__wrapped__ = func return wrapper return decorator

但wraps远不止复制属性。它还修复了inspect模块依赖的关键信息，比如：

• inspect.signature(wrapper)能正确返回原函数的参数签名；
• help(wrapper)显示原函数的文档；
• IDE（如PyCharm、VS Code）能正确跳转到原函数定义；
• pytest的@pytest.mark.parametrize等装饰器能正确识别参数。

没有wraps，你的装饰器就像一个“假面人”——外表是函数，内里却是另一个函数，所有基于函数元数据的工具链都会失效。我在一个微服务项目中曾因漏掉@wraps，导致OpenAPI文档生成器无法提取路由函数的参数类型，最终花了3小时排查才定位到这个“小疏忽”。

3. 从零手写6个生产级装饰器：覆盖90%真实场景

3.1 基础版：无参函数装饰器（日志记录）

这是装饰器的“Hello World”，但生产环境要求远超教学示例。我们需要：

• 记录函数名、参数、返回值、执行时间；
• 区分INFO（正常）、WARNING（耗时过长）、ERROR（异常）日志级别；
• 支持logging模块的标准配置，而非硬编码print。

import logging import time from functools import wraps # 配置日志（实际项目中应从配置文件加载） logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) logger = logging.getLogger(__name__) def log_execution(func): @wraps(func) def wrapper(*args, **kwargs): start_time = time.time() func_name = func.__name__ # 记录入参（避免敏感信息，仅记录类型和长度） arg_repr = [repr(a) for a in args] kwarg_repr = [f"{k}={repr(v)}" for k, v in kwargs.items()] signature = ", ".join(arg_repr + kwarg_repr) logger.info(f"Calling {func_name}({signature})") try: result = func(*args, **kwargs) end_time = time.time() duration = end_time - start_time # 根据耗时分级日志 if duration > 1.0: logger.warning(f"{func_name} executed in {duration:.2f}s") else: logger.info(f"{func_name} executed in {duration:.2f}s") # 记录返回值类型和长度（避免打印大对象） result_type = type(result).__name__ result_len = len(result) if hasattr(result, '__len__') else 'N/A' logger.debug(f"{func_name} returned {result_type} (len: {result_len})") return result except Exception as e: end_time = time.time() duration = end_time - start_time logger.error(f"{func_name} raised {type(e).__name__}: {e} (in {duration:.2f}s)", exc_info=True) raise return wrapper # 使用示例 @log_execution def fetch_user(user_id: int) -> dict: """模拟获取用户信息""" time.sleep(0.5) # 模拟网络延迟 return {"id": user_id, "name": "Alice", "email": "alice@example.com"} # 调用 user = fetch_user(123)

实操心得：

• exc_info=True是关键，它让日志包含完整的traceback，便于定位异常源头；
• logger.debug()用于返回值，避免污染INFO日志，生产环境可关闭DEBUG日志；
• 对args/kwargs的repr()处理，防止日志中打印超长字符串或二进制数据；
• hasattr(result, '__len__')比isinstance(result, (list, dict, str))更健壮，支持自定义容器类。

3.2 进阶版：带参数的装饰器工厂（API限流）

无参装饰器只能做固定逻辑，而真实业务需要动态配置。比如API限流：不同接口允许的QPS不同。这就需要装饰器工厂（Decorator Factory）。

import time from collections import defaultdict, deque from functools import wraps from typing import Callable, Any, Dict, List, Optional class RateLimiter: """内存版限流器，适用于单机场景""" def __init__(self, max_calls: int, window_seconds: float): self.max_calls = max_calls self.window_seconds = window_seconds # key: (func_name, ip) -> deque of timestamps self.calls: Dict[str, deque] = defaultdict(deque) def is_allowed(self, key: str) -> bool: now = time.time() # 清理窗口外的旧调用 while self.calls[key] and self.calls[key][0] < now - self.window_seconds: self.calls[key].popleft() if len(self.calls[key]) >= self.max_calls: return False self.calls[key].append(now) return True def rate_limit(max_calls: int = 10, window_seconds: float = 60.0, key_func: Optional[Callable] = None): """ 限流装饰器工厂 Args: max_calls: 窗口内最大调用次数 window_seconds: 时间窗口长度（秒） key_func: 生成限流key的函数，默认使用函数名+IP（需从request获取） """ def decorator(func: Callable) -> Callable: # 为每个被装饰函数创建独立限流器 limiter = RateLimiter(max_calls, window_seconds) @wraps(func) def wrapper(*args, **kwargs): # 生成限流key：默认为函数名，生产环境应结合用户ID/IP if key_func: key = key_func(*args, **kwargs) else: key = func.__name__ if not limiter.is_allowed(key): raise RuntimeError(f"Rate limit exceeded for {key}") return func(*args, **kwargs) # 添加解除限流的方法（用于测试或紧急情况） wrapper._limiter = limiter return wrapper return decorator # 使用示例：对登录接口限流（每分钟最多5次） @rate_limit(max_calls=5, window_seconds=60) def login(username: str, password: str) -> bool: """模拟登录验证""" time.sleep(0.1) return username == "admin" and password == "123" # 使用示例：自定义key（按用户ID限流） def user_key_func(*args, **kwargs): return f"user_{kwargs.get('user_id', 'unknown')}" @rate_limit(max_calls=100, window_seconds=3600, key_func=user_key_func) def get_user_profile(user_id: int) -> dict: return {"id": user_id, "profile": "..."}

原理深挖：

• rate_limit()是工厂函数，返回decorator；decorator接收func，返回wrapper；wrapper才是最终执行的函数。三层嵌套缺一不可；
• limiter实例绑定在wrapper闭包中，确保每个被装饰函数有独立的计数器；
• wrapper._limiter是调试后门，方便单元测试中重置计数器；
• key_func设计为可选参数，兼顾简单场景（函数名）和复杂场景（用户ID/IP），体现装饰器的扩展性。

3.3 类装饰器：状态管理与资源清理

函数装饰器适合无状态逻辑，但当需要维护状态（如计数器、缓存）或管理资源（如文件句柄、数据库连接）时，类装饰器更清晰。

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) 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 reset(self): """重置计数器""" self.count = 0 def get_count(self) -> int: return self.count # 使用 @CountCalls def add(a: int, b: int) -> int: return a + b print(add(1, 2)) # add has been called 1 times print(add(3, 4)) # add has been called 2 times print(f"Total calls: {add.get_count()}") # Total calls: 2 add.reset()

对比函数装饰器的优势：

• 状态（self.count）自然封装在实例中，无需全局变量或闭包变量；
• 提供reset()、get_count()等方法，接口更丰富；
• __call__方法让实例可调用，符合Python的鸭子类型哲学；
• 可以继承扩展，比如class CacheCountCalls(CountCalls)。

注意：类装饰器必须实现__call__方法，且通常需要在__init__中调用wraps(func)(self)来修复元数据。否则add.__name__会变成CountCalls实例的类名。

3.4 异步装饰器：async def函数的正确打开方式

Python 3.7+ 的async/await彻底改变了I/O密集型应用的编写方式，但装饰器必须适配。错误做法：直接套用同步装饰器。

# ❌ 错误：同步装饰器套在async函数上 @log_execution # 这个装饰器是同步的！ async def fetch_data(url: str) -> str: await asyncio.sleep(1) return f"Data from {url}" # 调用时会报错：TypeError: object ... can't be used in 'await' expression

正确做法：编写专门的异步装饰器。

import asyncio from functools import wraps from typing import Any, Callable, Awaitable def async_log_execution(func: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]: """异步版本的日志装饰器""" @wraps(func) async def wrapper(*args, **kwargs) -> Any: start_time = asyncio.get_event_loop().time() func_name = func.__name__ arg_repr = [repr(a) for a in args] kwarg_repr = [f"{k}={repr(v)}" for k, v in kwargs.items()] signature = ", ".join(arg_repr + kwarg_repr) logger.info(f"Calling async {func_name}({signature})") try: result = await func(*args, **kwargs) # 关键：await！ end_time = asyncio.get_event_loop().time() duration = end_time - start_time logger.info(f"Async {func_name} executed in {duration:.2f}s") return result except Exception as e: end_time = asyncio.get_event_loop().time() duration = end_time - start_time logger.error(f"Async {func_name} raised {type(e).__name__}: {e} (in {duration:.2f}s)", exc_info=True) raise return wrapper # 使用 @async_log_execution async def fetch_data(url: str) -> str: await asyncio.sleep(1) return f"Data from {url}" # 调用 result = asyncio.run(fetch_data("https://api.example.com"))

关键差异：

• 参数类型注解明确为Callable[..., Awaitable[Any]]，IDE能提供更好提示；
• wrapper函数本身是async def，内部用await func(...)调用原函数；
• asyncio.get_event_loop().time()比time.time()更精确，适用于异步事件循环；
• 所有日志记录保持异步非阻塞（logger.info在asyncio中是线程安全的）。

3.5 带状态的装饰器：LRU缓存的深度定制

Python内置@lru_cache很强大，但生产环境常需定制：比如缓存键生成逻辑、过期策略、缓存命中率监控。

import time from functools import wraps from typing import Any, Callable, Dict, Hashable, Optional from collections import OrderedDict class CustomLRUCache: """可监控、可配置的LRU缓存""" def __init__(self, maxsize: int = 128, ttl: Optional[float] = None): self.cache = OrderedDict() self.maxsize = maxsize self.ttl = ttl # Time-to-live in seconds self.hits = 0 self.misses = 0 def _is_expired(self, timestamp: float) -> bool: if self.ttl is None: return False return time.time() - timestamp > self.ttl def get(self, key: Hashable) -> Any: if key in self.cache: value, timestamp = self.cache[key] if self._is_expired(timestamp): del self.cache[key] self.misses += 1 return None self.cache.move_to_end(key) # 更新LRU顺序 self.hits += 1 return value self.misses += 1 return None def put(self, key: Hashable, value: Any): if self.maxsize == 0: return if len(self.cache) >= self.maxsize > 0: self.cache.popitem(last=False) # 移除最久未使用的 self.cache[key] = (value, time.time()) def stats(self) -> Dict[str, int]: total = self.hits + self.misses hit_rate = self.hits / total if total > 0 else 0.0 return {"hits": self.hits, "misses": self.misses, "hit_rate": hit_rate} def custom_cache(maxsize: int = 128, ttl: Optional[float] = None): """带TTL和统计的缓存装饰器""" def decorator(func: Callable) -> Callable: cache = CustomLRUCache(maxsize, ttl) @wraps(func) def wrapper(*args, **kwargs) -> Any: # 生成缓存键：使用args+kwargs的tuple，要求所有参数可哈希 try: key = (args, tuple(sorted(kwargs.items()))) except TypeError: # 如果参数不可哈希（如dict、list），降级为不缓存 return func(*args, **kwargs) cached_result = cache.get(key) if cached_result is not None: return cached_result result = func(*args, **kwargs) cache.put(key, result) return result # 暴露缓存统计和清除方法 wrapper.cache_stats = lambda: cache.stats() wrapper.cache_clear = lambda: cache.cache.clear() wrapper.cache_info = lambda: f"Cache size: {len(cache.cache)}, Hits: {cache.hits}, Misses: {cache.misses}" return wrapper return decorator # 使用示例：缓存数据库查询，5分钟过期 @custom_cache(maxsize=1000, ttl=300.0) def get_user_by_id(user_id: int) -> dict: # 模拟数据库查询 time.sleep(0.1) return {"id": user_id, "name": f"User{user_id}"}

生产级考量：

• ttl支持缓存自动过期，避免陈旧数据；
• stats()方法提供命中率监控，可接入Prometheus；
• cache_clear()便于在数据变更时主动失效缓存；
• 对不可哈希参数（如dict）的优雅降级，防止装饰器崩溃；
• OrderedDict保证LRU行为，比dict更可靠（Python 3.7+dict虽保持插入顺序，但move_to_end是OrderedDict专属）。

3.6 组合式装饰器：权限校验与事务管理的协同

真实业务中，一个函数常需多个装饰器：先校验权限，再开启数据库事务，最后记录日志。装饰器的组合顺序至关重要。

from functools import wraps from typing import Callable, Any # 权限校验装饰器 def require_role(required_role: str): def decorator(func: Callable) -> Callable: @wraps(func) def wrapper(*args, **kwargs): # 模拟从请求中获取用户角色 user_role = kwargs.get('user_role', 'guest') if user_role != required_role: raise PermissionError(f"Role '{required_role}' required, got '{user_role}'") return func(*args, **kwargs) return wrapper return decorator # 数据库事务装饰器 def transactional(func: Callable) -> Callable: @wraps(func) def wrapper(*args, **kwargs): # 模拟开启事务 print("Starting database transaction...") try: result = func(*args, **kwargs) print("Committing transaction...") return result except Exception as e: print("Rolling back transaction...") raise e return wrapper # 组合使用：顺序决定执行顺序（从下到上） @log_execution @transactional @require_role("admin") def delete_user(user_id: int, user_role: str = "guest") -> bool: """删除用户，需admin权限，且在事务中执行""" print(f"Deleting user {user_id}") return True # 调用 delete_user(123, user_role="admin") # 输出顺序： # Calling delete_user(123, user_role='admin') # Starting database transaction... # Deleting user 123 # Committing transaction... # delete_user executed in 0.00s

执行顺序详解：
装饰器从下到上应用，但执行时从上到下嵌套。上述代码等价于：

delete_user = log_execution(transactional(require_role("admin")(delete_user)))

因此调用栈为：

1. log_execution.wrapper→ 2.transactional.wrapper→ 3.require_role.wrapper→ 4.delete_user

组合陷阱：

• 如果@require_role放在最外层，权限校验会在事务开启前执行，这是合理的；
• 如果@log_execution放在最内层，日志会记录事务内部的细节，可能泄露敏感信息；
• 多个装饰器共享*args, **kwargs，需确保参数传递一致（如user_role必须由调用方传入）。

4. 常见问题与排查技巧实录：那些年踩过的坑

4.1 问题速查表：高频故障与根因分析

4.2 深度排查：用dis和pdb调试装饰器

当装饰器行为异常，不要靠猜。用Python内置工具精准定位。

步骤1：反编译字节码，确认装饰器绑定

import dis @log_execution def test_func(): return 42 dis.dis(test_func) # 查看test_func是否被替换为wrapper # 关键：LOAD_GLOBAL应加载wrapper，而非test_func

步骤2：用pdb设置断点，观察闭包变量

import pdb def debug_decorator(func): @wraps(func) def wrapper(*args, **kwargs): # 在此处设断点，检查闭包 pdb.set_trace() # 进入调试器 return func(*args, **kwargs) return wrapper @debug_decorator def buggy_func(): pass

在pdb中输入：

(Pdb) pp wrapper.__closure__ # 查看闭包变量 (Pdb) pp wrapper.__closure__[0].cell_contents # 查看func是否正确 (Pdb) l # 列出当前代码 (Pdb) n # 下一行

步骤3：检查函数元数据完整性

def verify_wraps(func): """验证装饰器是否正确修复元数据""" attrs = ['__name__', '__doc__', '__module__', '__annotations__'] for attr in attrs: if not hasattr(func, attr): print(f"Missing {attr}") elif getattr(func, attr) is None and attr != '__doc__': print(f"{attr} is None") verify_wraps(log_execution(lambda: None)) # 测试装饰器

4.3 实战避坑指南：来自金融系统的血泪教训

坑1：@lru_cache在多线程下的内存泄漏
在高频交易系统中，我们曾用@lru_cache(maxsize=1024)缓存行情计算结果。但lru_cache的cache_clear()不是线程安全的。当多个线程同时调用cache_clear()，会导致OrderedDict内部状态不一致，缓存大小失控，内存持续增长。
✅解决方案：改用functools.lru_cache的线程安全替代品，或用threading.RLock包装cache_clear()。

坑2：装饰器在@classmethod/@staticmethod上的失效

class MyClass: @classmethod @log_execution # ❌ 错误：log_execution作用于classmethod对象，而非方法 def my_classmethod(cls): pass

@classmethod返回的是classmethod对象，不是函数，log_execution无法处理。
✅解决方案：将装饰器放在@classmethod上方，或改用类装饰器。

坑3：@property与装饰器的冲突

class User: @property @cached_property # ❌ 错误