Python 装饰器详解

引言

当写 Python 程序时，经常会遇到一种场景：一个函数本身的逻辑很简单，但在它执行前后，需要附加一些额外的功能。比如打印日志、计算耗时、做权限校验、添加缓存。如果没有装饰器，往往只能在函数里手动加上这些重复的代码，不仅冗余，而且破坏了函数的单一职责。

Python 提供了一种优雅的方式来解决这个问题，那就是装饰器。装饰器的本质是对函数或类的"包装"，它在不改变原有逻辑的前提下，为目标对象增加新的功能。装饰器最常见的形式是用一个函数去接收另一个函数，并返回一个新的函数。

举一个简单的例子：

python 复制代码

def greet(name):
    return f"Hello, {name}!"

def uppercase_decorator(func):
    def wrapper(*args, **kwargs):
        original_result = func(*args, **kwargs)
        return original_result.upper()
    return wrapper

greet = uppercase_decorator(greet)

print(greet("Alice"))  # HELLO, ALICE!

在这个例子里，uppercase_decorator 就是一个装饰器。它接收 greet 函数，并返回一个新的函数 wrapper。这个新函数在调用 greet 后，把结果转成大写再返回。对我们来说，原始的 greet 没有任何修改，但功能却被增强了。

这种"无侵入式增强"的思想就是装饰器的核心。随着文章的深入，将展示装饰器的更多写法。

装饰器的基础

要真正理解装饰器，需要先明白两个概念：函数是一等公民 ，以及闭包。这两者构成了装饰器的底层原理。

在 Python 里，函数和整数、字符串一样，都是对象。可以把函数赋值给变量，也可以把它作为参数传递，甚至可以把它作为返回值返回。如：

python 复制代码

def greet(name):
    return f"Hello, {name}!"

# 函数赋值给变量
say_hello = greet
print(say_hello("Alice"))  # Hello, Alice!

# 函数作为参数传递
def call_function(func, value):
    return func(value)

print(call_function(greet, "Bob"))  # Hello, Bob!

# 函数作为返回值返回
def outer():
    def inner():
        return "Inner function called"
    return inner

new_func = outer()
print(new_func())  # Inner function called

这说明函数在 Python 中地位很高，它不再只是"过程"，而是真正的"对象"，是一等公民。有了这个前提，我们才可能编写"以函数为输入，以函数为输出"的装饰器。

至于闭包，它指的是内部函数引用了外部函数的变量，即使外部函数已经结束运行，这个变量依然能够被内部函数使用。

python 复制代码

def make_multiplier(n):
    def multiplier(x):
        return x * n
    return multiplier

times2 = make_multiplier(2)
times3 = make_multiplier(3)

print(times2(5))  # 10
print(times3(5))  # 15

这里 times2 和 times3 看上去像是普通函数，但实际上它们都记住了外部函数 make_multiplier 中 n 的值。哪怕 make_multiplier 已经执行完毕，变量 n 依然存在于闭包里。

理解闭包之后，就能更好地理解装饰器的工作原理。因为装饰器往往会定义一个内部函数，然后把外部函数作为参数传递进去，这正是闭包在发挥作用。

在下一节，我们会把这两个概念结合起来，写出第一个真正意义上的装饰器，并看看 Python 提供的 @ 语法糖是如何让装饰器更简洁、更自然的。

装饰器的基本语法

有了函数作为一等公民和闭包的基础，装饰器就变得顺理成章了。它的核心思想是：定义一个函数，这个函数接收另一个函数作为参数，并返回一个新的函数，从而在不修改原函数代码的前提下，为它添加额外功能。

先写一个最小可用的装饰器：

python 复制代码

def simple_decorator(func):
    def wrapper():
        print("Before the function runs")
        func()
        print("After the function runs")
    return wrapper

def say_hello():
    print("Hello!")

# 手动应用装饰器
say_hello = simple_decorator(say_hello)

say_hello()

运行输出：

text 复制代码

Before the function runs
Hello!
After the function runs

可以看到，say_hello 被包装了一层，执行时不仅打印了 Hello!，还多了前后两条信息。

上面的例子有点繁琐，需要手动把函数重新赋值。Python 提供了 @ 语法糖，让装饰器的使用更加直观：

python 复制代码

def simple_decorator(func):
    def wrapper():
        print("Before the function runs")
        func()
        print("After the function runs")
    return wrapper

@simple_decorator
def say_hello():
    print("Hello!")

say_hello()

这段代码和前面的写法完全等价。@simple_decorator 的含义就是把 say_hello 传给 simple_decorator，再用返回的新函数覆盖原来的 say_hello。

上面的装饰器只能修饰不带参数的函数。如果目标函数有参数，我们需要让装饰器更通用一些，用 *args 和 **kwargs 来接收任意参数：

python 复制代码

def universal_decorator(func):
    def wrapper(*args, **kwargs):
        print("Function is running...")
        result = func(*args, **kwargs)
        print("Function finished")
        return result
    return wrapper

@universal_decorator
def add(a, b):
    return a + b

print(add(3, 5))

通过 *args 和 **kwargs，使能够保证装饰器可以用于任何函数，不管它有多少参数、什么样的签名。

常见场景与实战示例

装饰器的价值在于它能把一些横切逻辑（logging、性能统计、权限控制等）独立出来，避免在业务函数里反复写重复的代码。下面我们通过几个常见场景来看看装饰器的实际威力。

日志与调试

调试代码时，经常需要知道一个函数被调用了多少次、传入了什么参数、返回了什么结果。装饰器可以帮我们在不修改函数的前提下，自动输出这些信息。

python 复制代码

def log_decorator(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_decorator
def multiply(a, b):
    return a * b

multiply(3, 4)

输出：

text 复制代码

Calling multiply with args=(3, 4), kwargs={}
multiply returned 12

有了这样的装饰器，便不用在每个函数里手动写日志逻辑，调试起来就轻松多了。

性能监控

有时候想知道某个函数运行了多久，装饰器可以快速实现一个程序运行的计时器。

python 复制代码

import time

def timing_decorator(func):
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        print(f"{func.__name__} took {end - start:.4f} seconds")
        return result
    return wrapper

@timing_decorator
def slow_function():
    time.sleep(1)
    return "done"

slow_function()

输出为：

text 复制代码

slow_function took 1.0001 seconds

这种装饰器在性能优化、分析瓶颈时非常实用。

权限校验

在 Web 开发中，很多函数在执行前需要检查用户是否有权限，装饰器可以把权限校验逻辑统一抽离出来。

python 复制代码

def require_admin(func):
    def wrapper(user, *args, **kwargs):
        if not user.get("is_admin"):
            raise PermissionError("Admin access required")
        return func(user, *args, **kwargs)
    return wrapper

@require_admin
def delete_database(user):
    return "Database deleted!"

# 模拟调用
admin = {"name": "Alice", "is_admin": True}
guest = {"name": "Bob", "is_admin": False}

print(delete_database(admin))   # 正常执行
print(delete_database(guest))   # 抛出 PermissionError

如此一来，便把权限检查从业务逻辑里剥离开，使代码更清晰、更安全。

缓存

如果一个函数经常被调用，并且同样的参数会反复出现，我们可以通过装饰器给它加缓存，提高效率。

python 复制代码

def cache_decorator(func):
    cache = {}
    def wrapper(*args):
        if args in cache:
            print("Returning cached result")
            return cache[args]
        result = func(*args)
        cache[args] = result
        return result
    return wrapper

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

print(fibonacci(10))  # 第一次计算
print(fibonacci(10))  # 第二次命中缓存

输出为：

text 复制代码

Returning cached result
Returning cached result
Returning cached result
Returning cached result
Returning cached result
Returning cached result
Returning cached result
Returning cached result
55
Returning cached result
55

通过这几个例子，可以看到装饰器在实际开发中的应用场景非常广泛。无论是调试、优化性能，还是增强安全性、提升效率，它都能让我们写出更简洁、更优雅的代码。

接下来会进入一些更深入的话题，比如为什么需要 functools.wraps，装饰器如何与类结合，以及多个装饰器叠加时的执行顺序。

进阶内容

掌握了装饰器的基本写法后，很快便会遇到一些更复杂的情况。比如想保留原函数的元信息，或者希望用类来写装饰器，甚至在一个函数上叠加多个装饰器。这一节就来深入探讨这些问题。

保留函数元信息：functools.wraps

如果用前面写的装饰器去包装函数，会发现原函数的 __name__、__doc__ 等元信息被替换成了内部的 wrapper。这可能会对调试、文档生成或一些框架的反射机制造成影响。

例如：

python 复制代码

def simple_decorator(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@simple_decorator
def greet(name):
    """Say hello to someone"""
    return f"Hello, {name}!"

print(greet.__name__)  # wrapper
print(greet.__doc__)   # None

解决办法是使用 functools.wraps，它会把原函数的元信息复制到包装函数上：

python 复制代码

from functools import wraps

def simple_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@simple_decorator
def greet(name):
    """Say hello to someone"""
    return f"Hello, {name}!"

print(greet.__name__)  # greet
print(greet.__doc__)   # Say hello to someone

在实际开发中，给装饰器加上 @wraps 几乎是必不可少的好习惯。

类装饰器

除了函数，也可以用类来实现装饰器。关键是定义 __call__ 方法，让类实例能像函数一样被调用。

python 复制代码

class Repeat:
    def __init__(self, times):
        self.times = times

    def __call__(self, func):
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(self.times):
                result = func(*args, **kwargs)
            return result
        return wrapper

@Repeat(3)
def say_hi(name):
    print(f"Hi, {name}!")

say_hi("Alice")

这个装饰器会让 say_hi 被执行三次。用类实现装饰器的好处是更容易维护状态，逻辑复杂时比函数更清晰。

装饰器叠加

Python 允许在一个函数上叠加多个装饰器。装饰器的执行顺序是自下而上的，即离函数最近的装饰器先执行，最外层的最后执行。

python 复制代码

def decorator_a(func):
    def wrapper(*args, **kwargs):
        print("Decorator A before")
        result = func(*args, **kwargs)
        print("Decorator A after")
        return result
    return wrapper

def decorator_b(func):
    def wrapper(*args, **kwargs):
        print("Decorator B before")
        result = func(*args, **kwargs)
        print("Decorator B after")
        return result
    return wrapper

@decorator_a
@decorator_b
def say_hello():
    print("Hello!")

say_hello()

运行结果：

text 复制代码

Decorator A before
Decorator B before
Hello!
Decorator B after
Decorator A after

带参数的装饰器工厂

有时候我们希望装饰器本身也能接收参数，这就需要再多写一层函数，常见的写法是装饰器工厂。

python 复制代码

from functools import wraps

def repeat(times):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(times):
                func(*args, **kwargs)
        return wrapper
    return decorator

@repeat(3)
def greet(name):
    print(f"Hello, {name}!")

greet("Alice")

这里的 repeat(3) 先返回一个具体的装饰器，再作用到 greet 上。这样就能动态控制装饰器的行为。

这一节讨论了 wraps、类装饰器、装饰器叠加以及装饰器工厂，这些都是写出健壮、可扩展装饰器的必备技巧。下一节将介绍一些常见且实用的内置装饰器，以及在流行框架里常见的装饰器应用，从理论走向实践。

实用库中的装饰器

装饰器的思想在 Python 标准库和各种第三方框架里应用得非常广泛。理解这些装饰器的原理，不仅能更好地使用它们，还能在需要时写出更契合业务的自定义装饰器。

标准库中的装饰器

最常见的几个标准库装饰器出现在面向对象编程中。

第一个是 @staticmethod，它用来修饰类中的方法，使其不依赖于实例或类对象，调用时就像普通函数一样：

python 复制代码

class MathUtils:
    @staticmethod
    def add(a, b):
        return a + b

print(MathUtils.add(3, 4))  # 7

这里 add 方法既不需要 self，也不需要 cls，它只是一个普通函数，被放在类的命名空间里以便组织代码。

第二个是 @classmethod，用来修饰类方法，第一个参数是类本身（通常命名为 cls），而不是实例。

python 复制代码

class Person:
    def __init__(self, name):
        self.name = name

    @classmethod
    def create_anonymous(cls):
        return cls("Anonymous")

p = Person.create_anonymous()
print(p.name)  # Anonymous

这种方式常用于工厂方法，它能根据不同场景创建类实例。

第三个是 @property，用来把方法变成只读属性，常用于封装内部逻辑，同时对外暴露简洁的接口。

python 复制代码

class Circle:
    def __init__(self, radius):
        self._radius = radius

    @property
    def area(self):
        return 3.14 * self._radius ** 2

c = Circle(5)
print(c.area)  # 78.5

这样可以用属性的方式访问计算结果，而不是调用方法，语义更加自然。

第四个是 @functools.lru_cache，这是标准库提供的缓存装饰器，用于加速重复计算。它会把函数调用的结果缓存下来，下次用相同参数调用时直接返回缓存结果。

python 复制代码

from functools import lru_cache

@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(30))

这种装饰器非常适合处理计算量大、参数有限的递归或动态规划问题。

第三方框架中的装饰器

装饰器在 Python 的生态中应用极其广泛，也来看几个经典例子。

第一个是 Flask 的路由装饰器。在 Flask 里，常见的 @app.route 就是装饰器，它把一个普通函数注册为 HTTP 路由处理器。

python 复制代码

from flask import Flask
app = Flask(__name__)

@app.route("/hello")
def hello():
    return "Hello, Flask!"

当访问 /hello 路径时，Flask 就会调用 hello 函数返回响应。

第二个是 Django 的权限装饰器。Django 提供了 @login_required，用来限制只有登录用户才能访问某个视图。

python 复制代码

from django.contrib.auth.decorators import login_required

@login_required
def dashboard(request):
    return HttpResponse("This is the dashboard")

这个装饰器会在执行 dashboard 前检查用户是否已登录，没登录就会重定向到登录页面。

第三个是 Click 的命令行装饰器。在命令行工具库 Click 里，装饰器用来定义命令和参数。

python 复制代码

import click

@click.command()
@click.option("--name", default="World")
def greet(name):
    click.echo(f"Hello, {name}!")

if __name__ == "__main__":
    greet()

执行脚本时，可以通过 --name 传参，装饰器负责解析逻辑。

这些例子展示了装饰器在框架中的巨大作用，它不仅能简化接口，让代码更直观，还能隐藏复杂逻辑，让开发者更专注于业务本身。

最佳实践与注意事项

装饰器让代码更简洁、更优雅，但如果使用不当，也可能带来困惑和维护困难。在这一节，我们结合经验来总结一些实用的最佳实践和注意事项。

避免滥用

装饰器适合用来处理横切逻辑，比如日志、缓存、权限验证。这些逻辑本来就应该与业务代码分离。

但如果把一切都包装成装饰器，最终会让代码变得难以阅读。一个函数如果套上五六层装饰器，读者很难一眼看出它到底做了什么。

建议：

对常见的、跨多个函数的逻辑使用装饰器；
对只在一个函数中出现的逻辑，直接写在函数里即可。

始终使用 functools.wraps

几乎所有自定义装饰器都应该加上 @wraps，否则会丢失原函数的名字和文档字符串。

这不仅影响调试和文档工具，还可能导致依赖元信息的框架行为异常。

python 复制代码

from functools import wraps

def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

虽然只是一个小小的习惯，却能避免很多麻烦。

注意副作用

装饰器实际上修改了函数的引用，它可能会改变函数的调用方式，甚至引入缓存或权限逻辑。

这意味着装饰器有可能影响测试、调试或代码的预期行为。

例如，在递归函数上使用缓存装饰器，可能会导致结果不一致，如果在测试时忘记清理缓存，就可能出现非预期结果。

因此在使用装饰器时，要清楚它可能引入的副作用，并在必要时提供关闭或绕过的机制。

保持可读性

有时候，过度依赖装饰器反而会降低代码的可读性。比如 Flask 的路由装饰器虽然很方便，但如果一个视图函数套了多个装饰器（路由、权限、缓存、跨域等），初学者可能会很难理解其执行顺序。

一种好的做法是把复杂的装饰器逻辑写清楚，或者在文档和注释里解释清楚装饰器的作用和顺序。

对于特别复杂的逻辑，也可以用类装饰器或明确的函数调用来替代，这样更直观。

关注性能

装饰器本质上会增加一次函数调用层级。如果装饰器逻辑复杂，或者装饰器层数较多，就可能影响性能。

虽然在大多数场景下这种开销可以忽略，但在高频调用的函数上还是要谨慎。

在必要时，可以通过性能分析工具（如 cProfile）来确认装饰器是否带来了显著的性能瓶颈。

除了可读性和性能，代码的安全性也是需要考虑的因素。对于涉及敏感逻辑或商业机密的项目，仅仅依赖 Python 语言层面的封装是不够的。可以结合专业的保护工具，例如 Virbox Protector，它提供了代码加密、反调试和防篡改等能力，可以帮助我们降低源代码被逆向或非法修改的风险，从而在功能之外增加一层安全保障。

总结

本文详细介绍了 Python 装饰器的基础语法、使用场景、进阶用法，以及在标准库和第三方框架中的应用。

装饰器的价值主要体现在三点：

让横切逻辑从业务函数里剥离出来，减少重复代码；
提高代码的可读性，让复杂功能以更自然的形式表达出来；
成为生态中的一种通用约定，几乎所有常见框架都会使用装饰器来定义配置、约束或行为。

在使用时，不要滥用装饰器，始终使用 wraps 保留元信息，避免难以追踪的副作用，关注复杂装饰器对可读性和性能的影响。