Python 装饰器：让你的代码优雅到飞起

★

本文为 Python 进阶系列第 8 篇，面向有一定基础、希望提升代码封装能力的运维开发者与编程初学者。读完本文，你将彻底理解装饰器原理，并能直接落地使用。

为什么别人的代码看起来更"高级"？一个 @xxx 放在函数上方，就能自动计时、记录日志、鉴权、重试、缓存……这就是装饰器（Decorator）——Python 最优雅的特性之一。

很多开发者对装饰器望而却步，本文用通俗讲解 + 可运行案例，带你从零掌握。

一、装饰器到底是什么？

一句话定义：装饰器是一个接收函数、返回新函数的函数，用于在不修改原函数代码的前提下，为函数增加额外功能。

基础示例

defmy_decorator(func):defwrapper():        print("函数执行前")        func()        print("函数执行后")return wrapper@my_decoratordefsay_hello():    print("Hello!")say_hello()

输出：

函数执行前Hello!函数执行后

原理解析

• @my_decorator 等价于 say_hello = my_decorator(say_hello)
• 装饰器接收原函数，返回包装函数 wrapper
• 调用原函数实际上执行的是 wrapper
• 核心思想：给函数套一层"外壳"，在执行前后插入额外逻辑

★

💡 初学者类比：装饰器就像快递包装盒——商品（原函数）不变，外层加了防护材料（额外逻辑），最终收到的还是你要的东西。

二、带参数的函数装饰器

实际开发中函数几乎都有参数，使用 *args 与 **kwargs 可适配任意参数形式。

from functools import wrapsdefmy_decorator(func):    @wraps(func)defwrapper(*args, **kwargs):        print(f"准备调用 {func.__name__}")        result = func(*args, **kwargs)        print(f"调用完成，返回值：{result}")return resultreturn wrapper@my_decoratordefcalculate(a, b):return a + bresult = calculate(10, 20)print(f"最终结果: {result}")

输出：

准备调用 calculate调用完成，返回值：30最终结果: 30

★

💡 注意：这里已加入 @wraps(func)，作用是保留原函数的名称和文档信息，避免元信息丢失（详见第五节）。

三、带参数的装饰器

装饰器本身也可以接收参数，需要三层嵌套结构：

装饰器工厂(参数)  →  装饰器(func)  →  包装函数 wrapper

from functools import wrapsdefrepeat(times):"""让函数重复执行 N 次"""defdecorator(func):        @wraps(func)defwrapper(*args, **kwargs):for i in range(times):                result = func(*args, **kwargs)return resultreturn wrapperreturn decorator@repeat(times=3)defsay_hi(name):    print(f"Hi, {name}!")say_hi("小明")

输出：

Hi, 小明!Hi, 小明!Hi, 小明!

运维场景： 三层嵌套结构在运维脚本中很常见，例如 @retry(max_attempts=3) 这类可配置的重试装饰器，下一节直接给出完整实现。

四、五大实用装饰器（直接复制使用）

1. 计时器：自动测量函数耗时

性能排查时最常用，无需修改业务代码，一行 @timer 即可。

import timefrom functools import wrapsdeftimer(func):    @wraps(func)defwrapper(*args, **kwargs):        start = time.time()        result = func(*args, **kwargs)        end = time.time()        print(f"⏱️ {func.__name__} 执行耗时: {end - start:.4f} 秒")return resultreturn wrapper@timerdefslow_task():    time.sleep(1)return"任务完成"slow_task()# 输出: ⏱️ slow_task 执行耗时: 1.0012 秒

运维场景： 用于排查接口慢查询、数据库操作耗时，快速定位性能瓶颈。

2. 日志记录器：自动记录调用信息

from datetime import datetimefrom functools import wrapsdeflog(func):    @wraps(func)defwrapper(*args, **kwargs):        ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")        print(f"[{ts}] 调用函数: {func.__name__}")        print(f"       参数: args={args}, kwargs={kwargs}")        result = func(*args, **kwargs)        print(f"[{ts}] 返回值: {result}")return resultreturn wrapper@logdefprocess_data(data):return data.upper()process_data("hello")

输出：

[2026-04-11 10:00:00] 调用函数: process_data       参数: args=('hello',), kwargs={}[2026-04-11 10:00:00] 返回值: HELLO

运维场景： 替代手动埋点，在关键函数入口/出口自动输出日志，方便问题追踪。

3. 自动重试：失败自动重试

import timeimport randomfrom functools import wrapsdefretry(max_attempts=3, delay=1):defdecorator(func):        @wraps(func)defwrapper(*args, **kwargs):for attempt in range(max_attempts):try:return func(*args, **kwargs)except Exception as e:if attempt == max_attempts - 1:raise# 最后一次仍失败，抛出异常                    print(f"⚠️ 第 {attempt + 1} 次失败，{delay} 秒后重试... 原因: {e}")                    time.sleep(delay)return wrapperreturn decorator@retry(max_attempts=3, delay=0.5)defunstable_api():if random.random() < 0.7:raise ConnectionError("网络不稳定")return"API 调用成功"try:    print(unstable_api())except ConnectionError as e:    print(f"重试耗尽，最终失败: {e}")

运维场景： 调用第三方 API、数据库连接、网络请求等不稳定操作时，加上 @retry 可大幅提升脚本健壮性，无需手写 for 循环重试逻辑。

4. 缓存器：相同参数直接返回缓存结果

from functools import wrapsdefmemoize(func):    cache = {}    @wraps(func)defwrapper(*args):if args in cache:            print(f"🎯 命中缓存: {args}")return cache[args]        result = func(*args)        cache[args] = resultreturn resultreturn wrapper@memoizedeffibonacci(n):if n < 2:return nreturn fibonacci(n - 1) + fibonacci(n - 2)print(fibonacci(10))  # 输出: 55

★

💡 提示：Python 标准库已内置 functools.lru_cache，生产环境优先使用，此处手写版本帮助理解原理。

from functools import lru_cache@lru_cache(maxsize=128)deffibonacci(n):if n < 2:return nreturn fibonacci(n - 1) + fibonacci(n - 2)

运维场景： 缓存配置文件读取结果、DNS 解析结果，避免重复 I/O 操作。

5. 权限检查：自动验证角色

from functools import wrapsdefrequire_role(role):defdecorator(func):        @wraps(func)defwrapper(user, *args, **kwargs):if user.get("role") != role:raise PermissionError(f"需要 {role} 权限，当前角色: {user.get('role')}")return func(user, *args, **kwargs)return wrapperreturn decorator@require_role("admin")defdelete_user(user, user_id):    print(f"删除用户 {user_id}")# 正常调用admin = {"role": "admin"}delete_user(admin, 123)  # 输出: 删除用户 123# 权限不足try:    guest = {"role": "guest"}    delete_user(guest, 123)except PermissionError as e:    print(f"权限错误: {e}")# 输出: 权限错误: 需要 admin 权限，当前角色: guest

运维场景： 内部运维平台的高危操作（删除、重启、变更配置），统一通过装饰器做角色校验，避免权限逻辑散落各处。

五、装饰器常见坑点与解决方案

坑 1：函数元信息丢失

未使用 @wraps 会导致函数名、文档字符串被 wrapper 覆盖，影响日志输出和调试。

# ❌ 错误写法：未使用 @wrapsdefmy_decorator(func):defwrapper():return func()return wrapper@my_decoratordefimportant_function():"""重要函数"""passprint(important_function.__name__)  # 输出: wrapper  ← 错误！print(important_function.__doc__)   # 输出: None     ← 文档丢失！

# ✅ 正确写法：加上 @functools.wraps(func)from functools import wrapsdefmy_decorator(func):    @wraps(func)defwrapper():return func()return wrapper@my_decoratordefimportant_function():"""重要函数"""passprint(important_function.__name__)  # 输出: important_function ✓print(important_function.__doc__)   # 输出: 重要函数 ✓

★

💡 最佳实践：编写任何装饰器时，@wraps(func) 是必加项，养成习惯。

坑 2：多个装饰器的执行顺序

多个装饰器叠加时，包装顺序从下往上，执行顺序从上往下。

@decorator_a   # 第 2 个包装，最外层，最先执行@decorator_b   # 第 1 个包装，最内层，第二执行defmy_func():pass# 等价于：my_func = decorator_a(decorator_b(my_func))

实际验证：

from functools import wrapsdefdecorator_a(func):    @wraps(func)defwrapper(*args, **kwargs):        print("A - 开始")        result = func(*args, **kwargs)        print("A - 结束")return resultreturn wrapperdefdecorator_b(func):    @wraps(func)defwrapper(*args, **kwargs):        print("B - 开始")        result = func(*args, **kwargs)        print("B - 结束")return resultreturn wrapper@decorator_a@decorator_bdefmy_func():    print("执行原函数")my_func()

输出：

A - 开始B - 开始执行原函数B - 结束A - 结束

六、进阶：类装饰器

类也可以作为装饰器，优势是可以方便地保存状态（如调用次数、缓存数据等）。

classCountCalls:def__init__(self, func):        self.func = func        self.count = 0def__call__(self, *args, **kwargs):        self.count += 1        print(f"📊 第 {self.count} 次调用 {self.func.__name__}")return self.func(*args, **kwargs)@CountCallsdefsay_hello():    print("Hello!")say_hello()say_hello()

输出：

📊 第 1 次调用 say_helloHello!📊 第 2 次调用 say_helloHello!

运维场景： 用类装饰器统计高频操作的调用次数，方便监控与告警。

七、核心知识点总结

一句话记忆：装饰器 = 给函数套一层逻辑，不改原代码，增强新能力。

八、实战作业

实现一个类型校验装饰器 @validate_types，在执行前检查参数类型是否与注解一致：

@validate_typesdefadd(a: int, b: int) -> int:return a + badd(1, 2)    # 正常执行，输出: 3add("1", 2)  # 抛出类型错误

提示： 通过 func.__annotations__ 获取函数的类型注解，通过 func.__code__.co_varnames 获取参数名列表。

参考实现：

from functools import wrapsdefvalidate_types(func):    @wraps(func)defwrapper(*args, **kwargs):        hints = func.__annotations__        params = list(func.__code__.co_varnames[:func.__code__.co_argcount])for i, arg in enumerate(args):            param_name = params[i]if param_name in hints andnot isinstance(arg, hints[param_name]):raise TypeError(f"参数 '{param_name}' 应为 {hints[param_name].__name__}，"f"实际传入 {type(arg).__name__}"                )return func(*args, **kwargs)return wrapper

★

本文基于《Intermediate Python》中文版整理，补充大量实战案例与避坑经验。

下一篇预告： 全局变量与返回值——那些你不知道的坑，敬请期待！