1. 为什么日志与权限成了装饰器的代名词我在一个内部后台项目里干过一件蠢事一开始只写了一个logger装饰器给每个接口记一句 INFO 日志后来运营要求加权限校验我又叠了一个require_permission再后来发现接口被刷又往上加rate_limit。三个装饰器往函数头上一叠代码变得黑魔法一样而我最头疼的不是写它们而是排查线上问题时发现日志和权限的执行顺序错了未授权请求的敏感参数居然先被日志记了下来。Python 装饰器就是这么个东西——日志和权限是最常见的两个入口但它们只是冰山一角。这篇文章从原理到高阶实战聊聊如何真正驾驭它。1.1 日志和权限到底“横切”在哪里日志和权限都属于典型的横切关注点。说人话就是它们跟你的核心业务逻辑没有直接关系但你又必须在每一个核心业务逻辑的边界上做同样的事情。比如一个订单接口你关心的核心动作是“创建订单”但创建之前你需要知道是谁在调用要不要校验权限调用完成后要不要记录一条操作日志。如果这些逻辑都写到业务函数里每个函数都会被一堆if、log、try/except糊住脸。更麻烦的是如果权限规则变了你要去几十个函数里改if判断很容易漏掉一两个。装饰器正好能把这种“围绕函数边界”的公共逻辑抽出来日志关心的是“函数被调用前和被调用后发生了什么”权限关心的是“这个函数到底该不该被执行”。这两种需求都发生在函数执行的边界上天然适合用包装器wrapper来统一处理。这也是几乎所有 Python 教程都拿日志和权限举例子背后的原因——不是巧合而是这两件事恰好踩中了装饰器的能力范围。1.2 入门级装饰器的写法与局限先看一段最基础的代码import functools import logging logger logging.getLogger(__name__) def log(func): functools.wraps(func) def wrapper(*args, **kwargs): logger.info(fcall {func.__name__} with args{args} kwargs{kwargs}) result func(*args, **kwargs) logger.info(fcall {func.__name__} done) return result return wrapper权限校验再叠一层def require_permission(permission): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): user get_current_user() if not user.has_permission(permission): raise PermissionDenied(fmissing permission: {permission}) return func(*args, **kwargs) return wrapper return decorator用起来倒是简洁log require_permission(order:create) def create_order(order_data): return ...但它的问题也很明显你只是学会了“按模板写装饰器”一旦碰到装饰器内部需要依赖请求上下文、需要异步支持、需要动态计算权限、需要排错就会开始怀疑自己是不是真的理解了装饰器。我自己的经验是停留在这种用法上的时间越长后面踩坑的代价越大。1.3 为什么只学用法远远不够只用log、require_permission的开发者遇见带参数的装饰器或者staticmethod、classmethod堆在一起的场景时经常会把顺序搞反。遇见functools.wraps没写导致的函数名错乱又要排查半天。真正深入原理之后你会发现装饰器的本质其实是一个非常简单的概念——函数只是对象函数可以返回函数。这个底层认知一旦建立日志和权限只是装饰器的两个起点后面还能用它做缓存、重试、限流、链路追踪甚至实现一套轻量级的 AOP 框架。所以我这篇不讲那些“三分钟学会装饰器”的套话直接从执行原理一路拆到实战代码每一段都是我在真实项目里跑过的写法。2. 从语法糖到底层装饰器执行时到底发生了什么2.1 函数是一等公民但很多人忘了这件事Python 里函数和整数、字符串、列表一样都是对象。你可以把一个函数赋值给变量可以把它塞进列表可以把它作为参数传给另一个函数也可以在一个函数里返回另一个函数。装饰器所有的魔法都建立在这个基础上。def hello(): return hello f hello # 赋值 print(f()) # 调用这看起来人畜无害但它是理解语法的钥匙如果函数可以被当作值传递那“给函数加一层包装”就变成了“创建一个新函数在里面调用老函数”。闭包就是在这个过程里自然产生的——内层函数引用了外层函数的变量并且把这个引用保存了下来。2.2 语法糖等价于一次显式赋值很多人看到decorator觉得神秘其实它只是下面这行代码的语法糖# 你写的 decorator def func(): pass # Python 实际执行的 def func(): pass func decorator(func)也就是说装饰器是在函数定义时立即执行的不是在调用时才执行的。这意味着如果你在装饰器内部打印日志你会在模块导入时就看到那行输出而不是等到函数被调用。这个细节经常让人误解。同样地带参数的装饰器require_permission(order:create)实际上经历了两个阶段先调用require_permission(order:create)它返回一个真正的装饰器函数然后这个装饰器再作用于下面的函数。所以带参数的装饰器必须有三层嵌套外层收参数中层收函数内层收*args/**kwargs。def require_permission(permission): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): ... return wrapper return decorator我在给人讲的时候喜欢把这个过程写成“洋葱模型”参数、函数、调用参数一层套一层。理解了这件事装饰器堆叠顺序的坑就成功避开了一半。2.3 闭包与变量捕获陷阱闭包是装饰器能记住原函数func的关键但闭包也容易埋雷。最常见的雷是循环变量捕获decorators [] for i in range(3): def decorator(func): def wrapper(*args, **kwargs): return i return wrapper decorators.append(decorator)这段代码里所有wrapper返回的值都是 2因为它们捕获的都是同一个变量i循环结束后i的最终值是 2。这也是为什么装饰器工厂函数里要尽量用不可变参数传递或者用默认参数技巧来“冻结”值。顺带一提functools.wraps不只是为了好看。它的内部会复制__module__、__name__、__qualname__、__doc__、__dict__等属性到包装函数上并且设置__wrapped__指向原函数这样inspect.signature、help()、IDE 自动补全才能正常工作。我见过团队里有人为了省一行引用不写functools.wraps结果一个接口环境里满屏都是wrapper的函数名半天定位不到真实函数。3. 日志场景的高阶进化从 print 到链路追踪与性能监控3.1 结构化日志别再把参数拼进字符串初级的日志装饰器把参数转成字符串拼进日志里像fcall {func.__name__} args{args}。这在本地开发没问题但一旦接入集中式日志采集比如 Elasticsearch Filebeat你希望日志是结构化的 JSON方便按字段检索而不是一坨没法解析的文本。更好的做法是给日志装饰器增加extra字段或者直接输出 JSON 行。下面是我在项目里用过的一个简化版本import json import functools import logging logger logging.getLogger(access) def json_log(func): functools.wraps(func) def wrapper(*args, **kwargs): record { event: before_call, func: func.__name__, args_preview: [str(a)[:200] for a in args], } logger.info(json.dumps(record, ensure_asciiFalse)) result func(*args, **kwargs) logger.info(json.dumps({event: after_call, func: func.__name__}, ensure_asciiFalse)) return result return wrapper这里有个细节日志里的参数不要全量输出。我曾经把整个请求体打进日志结果下游的日志采集直接撑爆了磁盘。所以要么截断要么只放关键 ID要么在内网环境才开完整参数。3.2 给请求注入 trace_id每个日志都串成一条线单体应用还好微服务或者多线程场景下最痛苦的是出现一个报错但你不知道这次请求经历了哪些函数。传统做法是每次调用前手动往日志里塞 request_id但有了装饰器完全可以在入口统一生成。关键在于 Python 的contextvars。多线程里你不能直接用一个全局变量存 request_id那样线程之间会互相污染协程里更不能用普通全局变量因为多个协程会交替执行。contextvars是专门为这种情况设计的上下文变量装饰器入口写入包装函数内部读取。import contextvars trace_var contextvars.ContextVar(trace_id, defaultNone) def trace(func): functools.wraps(func) def wrapper(*args, **kwargs): if trace_var.get() is None: trace_var.set(uuid4().hex) return func(*args, **kwargs) return wrapper把trace放在最外层接口入口处自动分配 trace_id再结合日志格式化里的trace_var.get()整条链路的日志就都能串起来了。这个思路并不复杂但它比“在业务代码里手动传 request_id”优雅太多。3.3 性能监控与慢调用告警另一个很实用但很容易被忽略的功能是耗时统计。装饰器能在调用前后各取一次时间计算耗时并判断是否超过阈值。注意要用time.perf_counter()因为time.time()可能被系统时间调整影响而perf_counter专门用来测量间隔。import time import functools SLOW_THRESHOLD 1.0 # 秒 def monitor_slow(func): functools.wraps(func) def wrapper(*args, **kwargs): start time.perf_counter() try: result func(*args, **kwargs) return result finally: elapsed time.perf_counter() - start if elapsed SLOW_THRESHOLD: logger.warning(slow call %s: %.2fs, func.__name__, elapsed) return wrapper这里用finally可以保证即使函数抛异常耗时统计也一定会记录。不要把它写在return后面那样异常情况就漏了。3.4 失败重试与指数退避日志场景经常伴随着“外部服务偶尔抽风需要自动重试”。重试装饰器是个非常典型的横切逻辑但它有一个大坑重试次数和退避策略处理不好会把系统拖垮。一个合理的装饰器至少应该支持最大重试次数指数退避的基础间隔只在指定异常类型上重试重试次数超过后的最终异常import time import functools def retry(max_retries3, base_interval0.5, exceptions(Exception,)): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): retries 0 while True: try: return func(*args, **kwargs) except exceptions as exc: retries 1 if retries max_retries: raise wait base_interval * (2 ** (retries - 1)) logger.warning(retry %s after %.2fs due to %r, func.__name__, wait, exc) time.sleep(wait) return wrapper return decorator重试装饰器最容易犯的错是捕获Exception太宽泛把业务错误也重试了。比如“订单状态不允许”这种业务异常重试一百次也没用只会给日志刷屏。所以exceptions参数一定要明确指定。3.5 和日志采集系统对接时的数据规范如果你用 Filebeat 这类采集器收集日志文件装饰器输出的内容最好遵循统一的格式。不然运维同学会拿着日志搜索工具挨个问“你这个时间戳为什么不是 ISO 格式”。我踩过一次本地调试时觉得 readable 就行上线后采集端无法解析时间字段所有日志时间都被当成接收时间问题排查整整慢了半天。所以现在我的日志装饰器统一输出 JSON并且保证每个字段名都提前定义清楚比如func、event、trace_id、elapsed_ms、error。采集端只需要配置解析 JSON搜索关键字直接查字段比 grep 一堆无规律的字符串舒服得多。4. 权限场景的高阶进化声明式鉴权与动态策略4.1 从写死权限名到可配置的权限装饰器初级的权限装饰器长这样def require_admin(func): functools.wraps(func) def wrapper(*args, **kwargs): if current_user.role ! admin: raise PermissionDenied return func(*args, **kwargs) return wrapper一旦需要“管理员可以运营也可以”你就要写第二个装饰器或者加or条件。更通用的做法是让装饰器接收权限列表同时支持any和all两种语义def require_permissions(*perms, require_allTrue): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): user get_current_user() user_perms user.permissions() if require_all: ok all(p in user_perms for p in perms) else: ok any(p in user_perms for p in perms) if not ok: raise PermissionDenied(fneed one of {perms}) return func(*args, **kwargs) return wrapper return decorator这种写法的价值在于权限规则是声明式的拿着函数代码就能看出它能被谁调用。权限变了不需要改函数逻辑只需要改装饰器参数。4.2 支持 RBAC 和 ABAC 的权限判断真实项目里权限往往不是简单的“某个用户有没有某个权限点”而是跟角色、资源、上下文相关。这时候用两张表说清楚模型判断方式适合场景RBAC用户 - 角色 - 权限点后台管理系统角色固定权限静态ABAC用户 资源 环境条件文档协作、多租户、数据层面权限装饰器本身并不关心内部用哪种模型它只需要从某个AccessPolicy里拿到最终结论。比如我可以定义一个authorize装饰器接收一个策略对象或函数def authorize(policy): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): decision policy.check(get_current_user(), func, args, kwargs) if not decision.allowed: raise PermissionDenied(decision.reason) return func(*args, **kwargs) return wrapper return decorator这样 RBAC、ABAC 都可以作为policy塞进去。关于“行级权限”这类需求核心也是这套逻辑——策略检查的不只是“能不能调用函数”还要结合资源参数判断“能不能操作这个 ID”。装饰器名称可以叫authorize(OrderPolicy())然后OrderPolicy内部再根据订单归属做判断。4.3 权限判断结果要缓存但缓存必须会失效权限判断常见瓶颈是频繁查数据库或外部权限服务。用户调一次接口权限装饰器就去查一遍性能奇差。于是很多人引入缓存却忘了缓存失效问题。权限缓存不能简单地lru_cache一挂了之因为用户的权限可能被管理员修改。推荐做法是带 TTL 的缓存或者和用户的 token 版本号绑定import time import functools class PermissionCache: def __init__(self, ttl60): self._ttl ttl self._store {} def get(self, user_id, perm): item self._store.get((user_id, perm)) if item and item[0] time.monotonic(): return item[1] return None def set(self, user_id, perm, allowed): self._store[(user_id, perm)] (time.monotonic() self._ttl, allowed)注意这里用time.monotonic()而不是time.time()避免系统改时间导致缓存提前永不过期。权限变更后如果 TTL 没到最多延迟 60 秒生效对大部分系统是可以接受的能换来显著的性能提升。4.4 同时支持同步和异步函数现代 Python 项目里async def很常见。如果你的权限装饰器只返回普通wrapper套在异步函数上会出现RuntimeWarning: coroutine was never awaited因为包装函数是普通函数它调用func(*args, **kwargs)拿到的是协程对象但没 await。解决方式有两种。要么写两套装饰器要么让装饰器内部分辨函数类型然后返回不同类型的 wrapper。我在项目里更倾向后者import asyncio import functools import inspect def require_permission(perm): def decorator(func): if inspect.iscoroutinefunction(func): functools.wraps(func) async def async_wrapper(*args, **kwargs): user get_current_user() if not user.has_permission(perm): raise PermissionDenied(perm) return await func(*args, **kwargs) return async_wrapper else: functools.wraps(func) def wrapper(*args, **kwargs): user get_current_user() if not user.has_permission(perm): raise PermissionDenied(perm) return func(*args, **kwargs) return wrapper return decorator这个细节很容易被忽略但一旦线上同时存在同步和异步接口你会发现装饰器必须感知函数类型。同理flask类框架用普通函数跑异步会有更多坑最好在框架入口就统一处理。4.5 在 Web 框架里设计“鉴权层”而不是“到处加装饰器”装饰器好用但别滥用。如果一个项目里一百个接口都手动加require_permission(xxx)维护成本很高。更合理的方式是让装饰器与路由元数据结合必要时在框架层面做一个集中式鉴权中间件。不过这不意味着装饰器就没用了。它更适合做“差异化授权”比如 95% 的接口统一鉴权剩下的 5% 接口需要额外校验资源权限这时候用authorize(ResourcePolicy(order_owner))做精确补充。这样的组合比把所有判断塞进中间件灵活得多。5. 把装饰器当武器库缓存、重试、限流与描述符5.1 带 TTL 的缓存装饰器缓存是装饰器的经典高阶用法functools.lru_cache自带内存缓存但有些场景需要自定义 TTL。比如爬虫获取的列表页5 秒内没必要重复请求用户信息查询1 分钟内没必要重复查库。实现一个简单的 TTL 缓存装饰器时核心要注意参数是否可哈希import time import functools def ttl_cache(ttl15): def decorator(func): cache {} functools.wraps(func) def wrapper(*args, **kwargs): key (args, tuple(sorted(kwargs.items()))) now time.monotonic() cached cache.get(key) if cached and cached[0] ttl now: return cached[1] result func(*args, **kwargs) cache[key] (now, result) return result return wrapper return decorator注意kwargs要排序否则{a: 1, b: 2}和{b: 2, a: 1}会算成两个 key。另外如果参数里有不可哈希对象比如list这种直接用args做 key 的方案会炸。一般可以对参数做签名摘要或者要求调用方传可哈希对象这个要提前想好。5.2 限流装饰器单机版滑动窗口接口限流如果用了 Redis一般做成独立服务或框架中间件但如果只是单进程内的简单限制装饰器完全够用。核心是记录每次调用的时间戳然后判断窗口内的调用次数是否超过上限。import time import functools def rate_limit(max_calls10, window_seconds60): def decorator(func): timestamps [] functools.wraps(func) def wrapper(*args, **kwargs): now time.monotonic() timestamps[:] [t for t in timestamps if now - t window_seconds] if len(timestamps) max_calls: raise RateLimitExceeded(too many calls) timestamps.append(now) return func(*args, **kwargs) return wrapper return decorator这个版本的缺陷是它不是线程安全的。多线程环境下多个请求同时读到timestamps长度不够就会一起放行。真要稳妥可以加一个threading.Lock在判断和追加之间加锁。上面只是为了展示装饰器的思路上线前必须补锁或换分布式限流方案。5.3 类装饰器给类的所有方法批量加日志函数装饰器只能包装单独的函数如果你想给一个类里的所有方法都加上日志总不能一个方法一个方法地加。这时候可以用装饰器装饰类本身def log_methods(cls): for name, method in inspect.getmembers(cls, inspect.isfunction): setattr(cls, name, log(method)) return cls这种写法在某些内部框架里很有用比如自动给所有 Service 方法加埋点。但要小心inspect.getmembers(cls, inspect.isfunction)会连同继承的方法一起拿到而且staticmethod、classmethod的行为可能不同所以做批量封装的类装饰器一定要在真实类结构上测一遍再上线。5.4 装饰器与描述符控制类方法的属性访问当装饰器作用在类属性上并且这个属性本身实现了描述符协议__get__、__set__、__delete__事情就会变得更有趣。一个经典的例子是控制方法的绑定行为。其实日常写代码不一定会亲自实现描述符但理解它有助于解释“为什么property能够和装饰器和谐共处”。property本身就是property类作为装饰器实现的它重写了__get__让函数变成属性访问。你可以在自己的装饰器里也实现__get__让装饰后的函数绑定到实例时保留额外信息。举个例子class bound_with_meta: def __init__(self, func, meta): self.func func self.meta meta def __get__(self, instance, owner): if instance is None: return self def bound(*args, **kwargs): return self.func(instance, *args, **kwargs) return bound这看起来像一个小玩具但当你需要装饰器在类方法上传递元数据时比如 API 文档、路由信息这个思路就很有用。很多 Web 框架实际就是这么干的——装饰器往函数上挂meta框架再用描述符读取。6. 踩坑实录被 装饰器坑过的那些瞬间6.1 忘写 functools.wraps 导致的“鬼打墙”有一个同事写装饰器没带functools.wraps于是被装饰函数的名字全部变成wrapper。因为他还在多个函数上用了同一个装饰器报错堆栈里所有函数都叫wrapper并且参数签名也变成(*args, **kwargs)无法通过关键字传参。排查过程花了两个小时。后来我们的代码规范里明确规定自定义装饰器必须带functools.wraps(func)并且通过__wrapped__属性暴露原函数。这样既方便调试也能让inspect.signature拿到原始签名。6.2 装饰器堆叠顺序一错权限和日志全乱这是我最想强调的坑。Python 装饰器的执行顺序是先应用下面的装饰器再应用上面的装饰器。也就是说log require_permission(order:create) def create_order(...): ...应用顺序是先require_permission包装create_order然后log再包装结果。运行时调用顺序反过来先执行最外层log再执行require_permission最后才是真实函数。如果我把顺序写成require_permission(order:create) log def create_order(...): ...运行时会先执行require_permission再执行log。这时候未授权请求会在进入log之前被拦截日志里没有未授权的敏感参数这可能是你想要的也可能是你不想要的。问题在于——项目里没有人把这个顺序文档化后来权限策略变了有人调换了一个装饰器把结果改得面目全非。所以我的原则是外层放跟“调用者身份”相关的装饰器内层放跟“函数行为”相关的装饰器。比如身份校验在最外日志在中间重试在最里。并且每个装饰器内部都要注意如果它抛了异常不能让调用链上更外层的装饰器误解。6.3 带默认参数的方法被装饰后签名变丑即使用了functools.wrapsinspect.signature在大多数情况下还是能通过__wrapped__找到原签名。但如果你的装饰器内部又使用了装饰器工厂或者手动做了参数转换就可能碰到signature仍然显示(*args, **kwargs)的情况。更棘手的是IDE 补全和静态类型检查器比如 mypy、pylance对decorator包装后的函数签名推导能力有限。解决方式是给装饰器函数加上类型注解并且尽可能让包装函数接受与原始函数一致的签名或者至少返回Callable[..., Any]。我在实际项目里最终选择了收紧规范装饰器不得改变被装饰函数的签名除非它的目的就是改写签名。6.4 调试器断点打在装饰器内部越看越晕装饰器会把调用栈拉长很多。如果你在wrapper里打断点每调用一次函数都会先进wrapper。在复杂的嵌套装饰器下你可能会看到三层以上的wrapper帧。我的调试建议很简单优先在真实函数体内部打断点不要只在装饰器里断需要看包装逻辑时利用func.__wrapped__直接跳到原函数。如果你使用的是 PyCharm打开“View Breakpoints”里 “On breakpoint” 的某个选项或者直接把断点打在func(*args, **kwargs)这行一步步看进去。另一个办法是在调试阶段临时注释掉部分装饰器减少干扰定位问题后再恢复。6.5 性能监控发现装饰器拖慢了函数我遇到过性能监控显示某个原本耗时 5ms 的函数套了日志装饰器和权限装饰器之后整体耗时变成 50ms。原因很简单日志装饰器把整个大请求体 JSON 序列化并写入日志权限装饰器每次调用都查询一次数据库而不是走缓存重试装饰器的time.sleep基础间隔设置得太小导致快速连续重试反而放大了负载。装饰器叠加带来的性能开销不是理论问题而是真实的生产事故。所以给装饰器加性能保护要像给业务加保护一样上心日志截断、权限缓存、重试退避缺一不可。我自己现在写装饰器时有个习惯每个装饰器都要在文档里写清楚它的开销等级以及是否应该在生产环境禁用。6.6 一个组合实战可插拔的“安全日志缓存”装饰器最后给你一个我在项目中实际用过的组合思路。我们需要一个接口既要记录日志又要权限校验还想要短时间缓存结果。与其堆三层装饰器不如抽象成一个组合装饰器def api_endpoint(permissionNone, cache_ttlNone): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): if permission: authorize(permission, get_current_user()) if cache_ttl: cached get_cache(func.__name__, args, kwargs) if cached is not None: return cached result log_call(func, args, kwargs) if cache_ttl: set_cache(func.__name__, args, kwargs, result, cache_ttl) return result return wrapper return decorator这样的组合装饰器只暴露一个入口内部按固定顺序执行“鉴权 - 缓存读取 - 业务调用 - 日志 - 缓存写入”。它牺牲了一部分灵活度但换来了极高的可读性和执行顺序可控。我强烈建议你在项目里做类似的封装而不是放任每个人任意堆叠装饰器——这是装饰器项目后期最容易失控的地方。我个人在实际操作中的体会是装饰器不是越花哨越好它真正厉害的地方是帮你在业务代码外面划出一道清晰的边界。日志和权限只是最常见的切入点真正让你“超越”它们的是对函数对象的底层理解以及那套“包装、组合、控制顺序”的心智模型。碰到复杂场景时先画清楚调用顺序再动手写代码往往能少踩一半的坑。