进阶修炼与毕业 · 进阶与毕业

第27章 给函数穿外套

装饰器

第 27 章 给函数穿外套:装饰器入门

📖 本章目标:理解"函数可以当参数",学会用装饰器给函数"加 Buff"。
学完本章,你会在不改动原函数的情况下,给函数加计时、日志、鉴权等能力。
这一章很"魔法"——你会第一次体会到 Python"代码写代码"的优雅。


【开场小剧场】给函数贴膜

学生: 皮皮,我写了 10 个函数,现在想给每个都加上"计时"功能,难道要一个个改?

皮皮: 你买了新手机,会拆开改电路加功能吗?不会——你贴个膜、戴个壳就完事,手机原样不动,能力却增强了。

学生: 所以对函数也能"贴膜"?

皮皮: 对!Python 的装饰器(decorator) 就是给函数"贴膜":不修改函数本身,在外面包一层"增强外套"。这是 Python 最酷的语法之一,今天带你揭开它的面纱。

学生: 那会不会很难?我前面学的还不太熟。

皮皮: 别怕,今天就三块砖头:函数当参数 → 闭包 → 装饰器,一块一块垒,垒完你就懂了。


27.1 铺垫:函数也是一等公民

Python 里,函数本身就是一种对象,可以像变量一样传来传去:

def say_hi():
    print("你好!")

# 函数能赋值给变量
f = say_hi
f()              # 你好!(f 和 say_hi 指向同一个函数)

# 函数能当参数传进去
def call_twice(func):
    func()
    func()

call_twice(say_hi)    # 你好!你好!

逐行拆解:
- def say_hi()::定义一个函数。注意:函数名本身不带括号;
- f = say_hi:把函数赋值给变量 f——不是调用,没有括号;
- f():用变量 f 去调用,相当于 say_hi();
- def call_twice(func):参数 func 接收一个"函数";
- func():在 call_twice 内部调用传进来的函数;
- call_twice(say_hi):传入函数(不带括号!),内部被调用了两次。

关键心法:"传函数"的时候永远不写括号,写括号就是在调用它。 你把"做事的方法"传给别人,别人在自己方便的时候替你执行。

换例加深:一个函数,两种姿势

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

# 姿势一:直接调用
print(greet("小明"))        # 你好,小明!

# 姿势二:当参数传给别的函数
def shout(text_func, name):
    result = text_func(name)
    print(result.upper())

shout(greet, "小红")        # 你好,小红! (大写)

shout 收到一个"函数",再用它去生成文本。 函数从此不再是"写在角落里的命令",而是可以自由传递的"工具"。

💡 一句话:函数本身可以像数据一样被"赋值、传递、返回"——这叫函数是一等公民(first-class)。装饰器的地基就是它。


27.2 闭包:函数里面造函数

闭包(closure):在一个函数内部定义另一个函数,内部函数能记住外部函数的变量。

def outer(x):
    def inner():
        print(f"我记住了 x = {x}")    # 用到外部函数的 x
    return inner                      # 把内部函数返回出去

func = outer(10)
func()      # 我记住了 x = 10

逐行拆解:
- def outer(x)::外部函数,参数 x;
- def inner()::在函数内部定义另一个函数;
- print(f"... x = {x}"):inner 用到了 outer 的参数 x;
- return inner:返回的是 inner 这个函数本身(不带括号);
- func = outer(10):调用 outer,得到 inner,存进 func;
- func():调用 func,打印出"x = 10"。

神奇之处: outer 执行完早就结束了,x 应该没了——但 inner 仍然记得 x = 10。内部函数"记住"了外部函数的变量环境,这就是闭包。 装饰器就靠它。

换例加深:靠闭包做"计数器"

def make_counter():
    count = 0                       # 外部变量
    def add_one():
        nonlocal count              # 声明要改外部变量(第 17 章 global 的"函数内版本")
        count += 1
        return count
    return add_one

counter = make_counter()
print(counter())    # 1
print(counter())    # 2
print(counter())    # 3

count 被 add_one "记住"了,而且每次调用都在累计。 这就是闭包的威力:函数不仅能记住外部变量,还能保存状态。

💡 和 global 对比记忆:第 17 章用 global 改全局变量;这里用 nonlocal 改外层函数的变量。两者都是"改别人家的变量前先打声招呼"。


27.3 手写第一个装饰器:给函数计时

装饰器 = 一个接收函数、返回新函数的函数。

import time

def timer(func):
    """装饰器:给函数计时"""
    def wrapper():
        start = time.time()
        func()                    # 调用原函数
        end = time.time()
        print(f"函数耗时 {end - start:.4f} 秒")
    return wrapper                # 返回"套了外壳"的版本

# 用法一:手动套
def slow_job():
    time.sleep(1)

wrapped = timer(slow_job)
wrapped()       # 函数耗时 1.0000 秒

# 用法二:@ 语法糖(推荐)
@timer
def fast_job():
    print("秒完")

fast_job()      # 秒完 / 函数耗时 0.0000 秒

逐行拆解:
- def timer(func)::装饰器——它接收一个函数;
- def wrapper()::造一个新函数"外壳",外壳里准备加东西;
- start = time.time():计时开始;
- func():调用原函数(让它照常干活);
- end = time.time():计时结束,打印耗时;
- return wrapper:把"套了外壳的版本"交出去;
- wrapped = timer(slow_job):手动套壳——wrapped 现在是"计时版 slow_job";
- @timer:语法糖,等价于 fast_job = timer(fast_job)。

为什么叫"语法糖"? 因为 @timer 只是一个更甜更好写的写法,底层就是"拿 timer 包一层,把结果存回原名"。之后调用 fast_job() 时,真正跑的是 wrapper——它先计时,再执行原函数。

换例加深:两个函数都加计时

@timer
def download():
    time.sleep(0.5)

@timer
def upload():
    time.sleep(0.3)

download()   # 函数耗时 0.5000 秒
upload()     # 函数耗时 0.3000 秒

同一个装饰器,随便给多少个函数用。 你只需要写一次计时逻辑,想给谁加就给谁贴个 @timer。

配套代码文件:code/ch27/timer.py。

🐍"皮皮注:装饰器读法顺口溜——@timer 就是 fast_job = timer(fast_job)。写错这句,后面全乱。"


27.4 原函数有参数怎么办:args 和 *kwargs

上面的装饰器假设原函数没参数。真实函数基本都有参数,这时 wrapper 要原样转发参数,用第 16 章学的 *args/**kwargs:

import time

def timer(func):
    def wrapper(*args, **kwargs):      # 收下任何参数
        start = time.time()
        result = func(*args, **kwargs) # 原样传回原函数
        end = time.time()
        print(f"耗时 {end - start:.4f} 秒")
        return result                  # 把原函数的结果也原样返回
    return wrapper

@timer
def add(a, b):
    time.sleep(0.1)
    return a + b

print(add(3, 5))      # 耗时 0.1000 秒 / 8

逐行拆解:
- def wrapper(*args, **kwargs)::外套不限参数——不管原函数有几个参数、是不是关键字参数,全收下;
- result = func(*args, **kwargs):把收到的参数原样拆开传给原函数;
- return result:把原函数的返回值原样还回去。

记住固定模板:wrapper(*args, **kwargs) 接参数 → func(*args, **kwargs) 传参数 → return result 返回结果。 这样原函数"穿多厚的壳都不破",行为不变,只是多了外套。

换例加深:带关键字参数的函数也能套

@timer
def make_greeting(name, punctuation="!"):
    return f"你好,{name}{punctuation}"

print(make_greeting("小红"))              # 耗时 ...秒 / 你好,小红!
print(make_greeting("小红", punctuation="?"))  # 关键字参数也能穿过去

看,*args 接住位置参数,**kwargs 接住关键字参数,一个不漏。 不管你原函数签名长啥样,这层外套通吃。

💡 背下这个三件套:*args 接 → 拆开传 → return result 还。它是所有通用装饰器的"标准骨架"。


27.5 实战:登录鉴权装饰器

装饰器最常见用途之一:权限校验。不改原函数,就在"进门之前"加一道检查:

logged_in = True      # 模拟登录状态

def login_required(func):
    def wrapper(*args, **kwargs):
        if not logged_in:
            print("❌ 请先登录!")
            return      # 挡住,不执行原函数
        return func(*args, **kwargs)
    return wrapper

@login_required
def show_profile():
    print("这是我的个人资料,只有登录才能看")

show_profile()      # 这是我的个人资料...

# 改成未登录再试
logged_in = False
show_profile()      # ❌ 请先登录!

逐行拆解:
- if not logged_in::进门检查;
- return:挡在门口——注意这里直接 return,压根没碰 func;
- return func(*args, **kwargs):检查通过,才放原函数执行。

看到价值了吗? 不管有多少个"只有登录才能看"的页面,每个函数前加一个 @login_required 就行——鉴权逻辑只写一遍,全局复用。这就是装饰器"横切关注点"的威力。

换例加深:写个日志装饰器

def log_call(func):
    def wrapper(*args, **kwargs):
        print(f"[日志] 调用 {func.__name__},参数是 {args}")
        return func(*args, **kwargs)
    return wrapper

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

print(add(3, 5))    # [日志] 调用 add,参数是 (3, 5) / 8

func.__name__ 能拿到原函数的名字(每个函数都自带)。日志、调试、监控……都是这么做的。

配套代码文件:code/ch27/auth_decorator.py。

🐍"皮皮注:鉴权是装饰器最经典的应用。把'要不要放行'写成装饰器,业务函数就只管干自己的活,脏活累活让装饰器挡在前面。代码瞬间清爽。"


27.6 进阶:给装饰器自己带参数(了解)

如果想让装饰器可配置,比如"计时精度 3 位还是 6 位",再套一层:

import time

def timer(precision=4):
    def decorator(func):
        def wrapper(*args, **kwargs):
            start = time.time()
            result = func(*args, **kwargs)
            print(f"耗时 {(time.time() - start):.{precision}f} 秒")
            return result
        return wrapper
    return decorator

@timer(precision=2)
def job():
    time.sleep(0.05)

job()      # 耗时 0.05 秒

三层嵌套: timer(precision) 返回 decorator,decorator(func) 返回 wrapper。

逐行拆解:
- timer(precision=2):最外层,先收下配置(precision);
- decorator(func):中间层,再收下函数;
- wrapper(*args, **kwargs):最内层,真正干活的外壳;
- f"{...:.{precision}f}":用配置的精度格式化秒数。

对比一下: 普通装饰器是"两层的三明治",带参数的装饰器是"三层的汉堡"。用的时候记得写括号 @timer(precision=2),这是它和普通装饰器最明显的区别。这个了解即可,新手先玩熟基础的。

💡 真实世界:很多框架(Flask、Django)到处是装饰器。用别人的装饰器很简单——@xxx 一行;能看懂、能写简单的,就够你横着走了。


【皮皮小课堂】本章要点


【翻车现场】本章的坑

坑 1:wrapper 忘了 return result

def timer(func):
    def wrapper(*args, **kwargs):
        func(*args, **kwargs)        # ❌ 没 return!
    return wrapper

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

print(add(3, 5))    # None!

外层调 add(3,5) 拿到的是 wrapper 的返回值,而 wrapper 没返回原函数的结果。 想让原函数的结果"穿透外套",必须 return func(...)。

坑 2:忘了转发参数

def timer(func):
    def wrapper():        # ❌ 不接受参数
        func()
    return wrapper

@timer
def add(a, b): ...
add(3, 5)    # TypeError: add() missing ...

原函数有参数,外套却不接、不传,调用必崩。统一用 wrapper(*args, **kwargs)。

坑 3:把装饰器用在函数定义时就"执行"了

装饰器是在定义时立刻套上的(模块加载那一刻),不是调用时才套。如果装饰器里有副作用,会在 import 时就发生。写装饰器时留意这点。

坑 4:装饰器里改原函数的名字

用了装饰器后,函数的 __name__ 会变成 wrapper,调试/文档会困惑。标准库 functools.wraps 能保留原名(一行):

import functools

def timer(func):
    @functools.wraps(func)          # 保留 func 的名字和文档
    def wrapper(*args, **kwargs):
        ...
    return wrapper

新手知道"有这个讲究"即可,遇到再查。

坑 5:@timer 手滑写成 @timer()

def timer(func):
    def wrapper():
        func()
    return wrapper

@timer()        # ❌ 多了括号!
def hi():
    print("你好")

@timer() 会把 timer() 的返回值当装饰器——而 timer() 这里报 TypeError(缺 func 参数);就算不报错,@ 后面跟着的也是一个"函数"而不是"调用结果",语义全乱。语法糖 @timer 后面坚决不写括号;只有带参数的装饰器才写 @timer(precision=2)。

坑 6:装饰器返回时漏了括号,把函数对象交出去

def timer(func):
    def wrapper():
        func()
    return wrapper    # 这里返回的是 wrapper 这个函数(对的)

看着没问题?那看看这个"错版"——把装饰器当函数调用,却漏掉了调用:

wrapped = timer       # ❌ 只取了 timer 本身,没调用
wrapped = timer()     # ❌ 漏了 func 参数
wrapped = timer(slow_job)   # ✅ 正确姿势

装饰器是个"函数",你要真正"调用"它、把函数传进去,它才给你一个"套好壳的函数"。 忘了传函数,拿到的是个没用的壳子。


【本章习题】

一、选择题

1. (★) @timer 加在函数上面,等价于下面哪个操作?

2. (★★) 装饰器里 wrapper(*args, **kwargs) 的作用是?

3. (★★) 想保留原函数的结果,wrapper 里必须?

4. (★★) 下面代码输出什么?

def make_counter():
    count = 0
    def add_one():
        nonlocal count
        count += 1
        return count
    return add_one

c = make_counter()
print(c())
print(c())

5. (★★ 多选) 关于装饰器,下列说法正确的是?

二、判断题

1. (★) 装饰器 @timer 必须在函数定义之后、调用之前生效。( )

2. (★★) 原函数有参数时,装饰器的 wrapper 必须用 *args, **kwargs 转发。( )

3. (★★) 使用装饰器后,原函数的返回值会被自动保留,不需要额外处理。( )

4. (★★) "把函数当参数传给别人",传的时候要写括号 f()。( )

三、代码纠错题

1. (★★) 下面代码 add(3, 5) 返回 None,请指出问题并改正:

import time

def timer(func):
    def wrapper(*args, **kwargs):
        start = time.time()
        func(*args, **kwargs)
        print(f"耗时 {time.time() - start:.4f} 秒")
    return wrapper

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

print(add(3, 5))    # 打印出 None

2. (★★) 下面的装饰器想给"有参数"的函数加日志,但一调用就报 TypeError,请指出问题并改正:

def logger(func):
    def wrapper():
        print(f"[日志] 调用 {func.__name__}")
        return func()
    return wrapper

@logger
def greet(name):
    return f"你好,{name}"

print(greet("小明"))    # ❌ TypeError: greet() takes 0 positional arguments but 1 was given

四、编程实战题

1. (基础 ★) 写一个 logger 装饰器:每次调用被装饰的函数时,打印一行"调用 函数名 函数"。

2. (基础 ★★) 写一个 repeat(3) 装饰器:让被装饰的函数连续执行 3 次。

3. (基础 ★★) 写一个 double_result 装饰器:让被装饰函数的返回值变成原来的 2 倍。例如 double_result 装饰的 add(1, 2) 返回 6。

4. (挑战 ★★★) 写一个"输入校验"装饰器 positive_only:如果函数的第一个参数是负数,打印提示并返回 None(不执行原函数);否则正常执行原函数并返回结果。



【参考答案与解析】

一、选择题

1. 答案:B
@timer 语法糖等价于 func = timer(func)。

2. 答案:B
*args, **kwargs 接收任意参数,func(*args, **kwargs) 原样转发。

3. 答案:A
想保留结果,必须 return func(*args, **kwargs)。

4. 答案:C
闭包"记住"count 并累计:第一次 1,第二次 2。

5. 答案:A、B、C、D
A 对:装饰器核心价值;B 对:三大用途;C 对:函数一等公民;D 对:闭包让内部函数记住外部变量。

二、判断题

1. 错误(×)。装饰器在函数定义时(模块加载那一刻)就套上了,不是调用时才套。

2. 正确(√)。统一用 *args, **kwargs 转发,兼容任何签名。

3. 错误(×)。必须显式 return func(...),否则原函数返回值被"吞掉"变 None。

4. 错误(×)。传函数时不写括号;写括号 f() 是"调用"它,得到的是结果而不是函数本身。

三、代码纠错题

1. 解析: wrapper 调用了 func(...) 但没 return,返回值丢了。改正:

def timer(func):
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)      # 保存结果
        print(f"耗时 {time.time() - start:.4f} 秒")
        return result                        # 返回结果
    return wrapper

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

print(add(3, 5))    # 耗时 ...秒 / 8

2. 解析: wrapper 不接受参数,导致 greet("小明") 传进来的 "小明" 无处安放。改正:用 *args, **kwargs 接住并转发:

def logger(func):
    def wrapper(*args, **kwargs):
        print(f"[日志] 调用 {func.__name__},参数是 {args}")
        return func(*args, **kwargs)        # 原样转发
    return wrapper

@logger
def greet(name):
    return f"你好,{name}"

print(greet("小明"))    # [日志] 调用 greet,参数是 ('小明',) / 你好,小明

核心: 通用装饰器骨架三件套——*args, **kwargs 接、func(*args, **kwargs) 传、return 还,一个都不能少。

四、编程实战题

1. 参考代码:

def logger(func):
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__} 函数")
        return func(*args, **kwargs)
    return wrapper

@logger
def say_hi():
    print("你好!")

say_hi()    # 调用 say_hi 函数 / 你好!

2. 参考代码:

def repeat(times):
    def decorator(func):
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result       # 返回最后一次的结果
        return wrapper
    return decorator

@repeat(3)
def knock():
    print("咚咚咚")

knock()     # 咚咚咚 x3

3. 参考代码:

def double_result(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result * 2       # 把结果翻倍
    return wrapper

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

print(add(1, 2))    # 6

4. 参考代码:

def positive_only(func):
    def wrapper(x, *args, **kwargs):
        if x < 0:
            print("❌ 第一个参数不能是负数!")
            return None
        return func(x, *args, **kwargs)
    return wrapper

@positive_only
def double(x):
    return x * 2

print(double(5))     # 10
print(double(-5))    # ❌ 第一个参数不能是负数! / None

🐍"皮皮注:装饰器学完,你已经能给函数'贴膜'了。下一章进入文本世界——正则表达式,用一套'咒语'在字符串里精确搜索、提取、替换。这是爬虫、文本处理的看家本领。"


📖 下一章,文本搜救队:正则表达式。

📦 本章配套代码

运行方式:命令行进入目录后执行 py 文件名.py(Windows)或 python3 文件名.py(Mac/Linux)