装饰器(decorator)是一种接收函数、再返回新函数的高阶函数。新函数通常会先执行一些附加逻辑,再调用原函数。
例如,很多函数都需要记录「开始执行」和「执行结束」。如果每个函数都手动写一遍,代码会重复。可以把这段公共逻辑放进装饰器:
01def log_call(function): 02 def wrapper(): 03 print("开始执行") 04 result = function() 05 print("执行结束") 06 return result 07 08 return wrapper 09 10def greet(): 11 print("你好,Python") 12 13greet = log_call(greet) 14greet()
log_call() 接收原来的 greet,返回一个新的 wrapper。重新赋值后,调用 greet() 实际上是在调用包装函数,原来的问候逻辑仍然由 function() 执行。
log_call()
greet
wrapper
greet()
function()
装饰器的重点是「在不修改原函数主体的情况下,为它增加行为」。日志、计时、权限检查、缓存和重试都适合抽成这种公共包装逻辑。
Python 提供 @ 语法,让装饰器的使用更直观:
@
01def log_call(function): 02 def wrapper(): 03 print("开始执行") 04 result = function() 05 print("执行结束") 06 return result 07 08 return wrapper 09 10@log_call 11def greet(): 12 print("你好,Python") 13 14greet()
函数定义前的 @log_call 等价于下面的重新赋值:
@log_call
装饰器在函数定义完成时执行一次,而不是每次调用函数时重新执行。也就是说,模块加载过程中先创建 greet,再调用 log_call(greet) 得到新的函数;以后每次 greet() 都只调用已经生成的包装函数。
log_call(greet)
这也解释了装饰器的两个调用阶段:装饰阶段接收函数并返回包装函数,运行阶段才由包装函数接收真正的业务参数。
真实函数通常有位置参数、关键字参数和返回值,包装函数应该使用 *args 与 **kwargs 接收它们,并把结果返回给调用方:
*args
**kwargs
01from functools import wraps 02 03def log_call(function): 04 @wraps(function) 05 def wrapper(*args, **kwargs): 06 print(f"开始执行:{function.__name__}") 07 result = function(*args, **kwargs) 08 print(f"执行结束:{function.__name__}") 09 return result 10 11 return wrapper 12 13@log_call 14def add(left, right): 15 return left + right 16 17print(add(2, right=3)) # 5
*args 收集位置参数,**kwargs 收集关键字参数;调用原函数时再次展开它们,才能保持原函数的调用方式。return result 也很重要,否则装饰后的函数会丢失原来的返回值。
return result
@wraps(function) 来自 functools,它会把原函数的名称、文档字符串等信息复制到包装函数上。没有它时,add.__name__ 会变成 wrapper,调试、日志和框架读取函数信息时都不够准确。
@wraps(function)
functools
add.__name__
包装函数还可以处理异常,但不要无意中吞掉异常。下面的 finally 无论成功还是失败都会执行,原异常仍然会继续抛出:
finally
01from functools import wraps 02 03def log_result(function): 04 @wraps(function) 05 def wrapper(*args, **kwargs): 06 try: 07 return function(*args, **kwargs) 08 finally: 09 print(f"调用完成:{function.__name__}") 10 11 return wrapper 12 13@log_result 14def divide(left, right): 15 return left / right 16 17print(divide(6, 2))
有时装饰器本身也需要参数,例如希望调用函数三次。此时需要多包一层:最外层接收配置,中间层接收函数,最内层才接收业务参数:
01from functools import wraps 02 03def repeat(times): 04 def decorator(function): 05 @wraps(function) 06 def wrapper(*args, **kwargs): 07 result = None 08 for _ in range(times): 09 result = function(*args, **kwargs) 10 11 return result 12 13 return wrapper 14 15 return decorator 16 17@repeat(3) 18def greet(name): 19 print(f"你好,{name}") 20 21greet("小明")
@repeat(3) 并不是把数字直接传给 greet()。它会先执行 repeat(3),得到 decorator;再用 decorator(greet) 得到最终的 wrapper。调用 greet("小明") 时,wrapper 才会循环调用原函数三次。
@repeat(3)
repeat(3)
decorator
decorator(greet)
greet("小明")
装饰器配置还可以用于权限检查。把权限名称提前传入后,同一个装饰器工厂就能生成不同规则:
01from functools import wraps 02 03def require_role(required_role): 04 def decorator(function): 05 @wraps(function) 06 def wrapper(user, *args, **kwargs): 07 if user["role"] != required_role: 08 raise PermissionError("没有执行权限") 09 10 return function(user, *args, **kwargs) 11 12 return wrapper 13 14 return decorator 15 16@require_role("admin") 17def delete_article(user, article_id): 18 return f"已删除文章 {article_id}" 19 20admin = {"name": "小明", "role": "admin"} 21print(delete_article(admin, 10))
在 FastAPI 项目中,鉴权、日志和限流也可以采用类似思路。不过框架通常已经提供了依赖注入或中间件机制,应该先使用框架的标准能力,再决定是否自定义装饰器。
一个函数可以同时使用多个装饰器。装饰器从下往上应用,但调用时从上往下进入:
01from functools import wraps 02 03def uppercase(function): 04 @wraps(function) 05 def wrapper(*args, **kwargs): 06 return function(*args, **kwargs).upper() 07 08 return wrapper 09 10def add_prefix(function): 11 @wraps(function) 12 def wrapper(*args, **kwargs): 13 return "结果:" + function(*args, **kwargs) 14 15 return wrapper 16 17@add_prefix 18@uppercase 19def message(): 20 return "hello" 21 22print(message()) # 结果:HELLO
上面的写法等价于:
01from functools import wraps 02 03def uppercase(function): 04 @wraps(function) 05 def wrapper(*args, **kwargs): 06 return function(*args, **kwargs).upper() 07 08 return wrapper 09 10def add_prefix(function): 11 @wraps(function) 12 def wrapper(*args, **kwargs): 13 return "结果:" + function(*args, **kwargs) 14 15 return wrapper 16 17def message(): 18 return "hello" 19 20message = add_prefix(uppercase(message)) 21print(message()) # 结果:HELLO
调用 message() 时,先进入外层的 add_prefix 包装函数;它内部再调用 uppercase 包装函数,最后才执行原始的 message。装饰器较多时,要注意顺序,因为交换顺序可能改变最终结果。
message()
add_prefix
uppercase
message
Python 自带和标准库中也有很多装饰器,例如类文章中介绍过的 @property、@classmethod、@staticmethod,以及数据类使用的 @dataclass。它们本质上都在函数或类定义完成时,对定义结果进行包装或改造。
@property
@classmethod
@staticmethod
@dataclass
异步函数需要使用异步包装函数,否则包装器无法正确等待原函数:
01import asyncio 02from functools import wraps 03 04def log_async(function): 05 @wraps(function) 06 async def wrapper(*args, **kwargs): 07 print("异步任务开始") 08 result = await function(*args, **kwargs) 09 print("异步任务结束") 10 return result 11 12 return wrapper 13 14@log_async 15async def greet(name): 16 await asyncio.sleep(0) 17 return f"你好,{name}" 18 19async def show_result(): 20 print(await greet("小明"))
在 FastAPI 的异步接口中调用 await show_result(),就会实际等待装饰后的函数;异步开始、结束和问候结果也会依次输出。浏览器案例已经运行在事件循环中,直接使用 await,无需再调用 asyncio.run()。
await show_result()
await
asyncio.run()
这类装饰器适合 FastAPI 的异步接口或异步 LangChain 调用。同步函数和异步函数不能直接使用同一种包装方式,需要保持 async 和 await 的调用模型一致。
async
装饰器适合给多个函数增加相同的横切逻辑,但它也会增加调用链的间接层。看到一个被装饰的函数时,读者需要跳转到装饰器才能了解完整行为。
可以按照下面的原则判断是否使用装饰器:
@wraps
async def
装饰器不是为了让代码看起来更高级,而是为了把重复的外围逻辑集中维护。只要增加的抽象让调用关系更难理解,就应该考虑改回普通函数或使用更明确的服务对象。
本篇把前面的知识放进一个可修改的 Python 项目。main.py 只负责接收参数并调用实验函数,decorators_demo.py 保存本篇的逻辑。默认接口不需要密钥,也不会调用外部模型。
main.py
decorators_demo.py
001import asyncio 002from functools import wraps 003 004def log_call(function): 005 @wraps(function) 006 def wrapper(*args, **kwargs): 007 print(f"开始执行:{function.__name__}") 008 try: 009 return function(*args, **kwargs) 010 finally: 011 print(f"执行结束:{function.__name__}") 012 return wrapper 013 014def repeat(times: int): 015 def decorator(function): 016 @wraps(function) 017 def wrapper(*args, **kwargs): 018 result = None 019 for _ in range(times): 020 result = function(*args, **kwargs) 021 return result 022 return wrapper 023 return decorator 024 025def uppercase(function): 026 @wraps(function) 027 def wrapper(*args, **kwargs): 028 return function(*args, **kwargs).upper() 029 return wrapper 030 031def add_prefix(function): 032 @wraps(function) 033 def wrapper(*args, **kwargs): 034 return "result: " + function(*args, **kwargs) 035 return wrapper 036 037def require_role(required_role: str): 038 def decorator(function): 039 @wraps(function) 040 def wrapper(user, *args, **kwargs): 041 if user["role"] != required_role: 042 raise PermissionError("没有执行权限") 043 return function(user, *args, **kwargs) 044 return wrapper 045 return decorator 046 047def log_async(function): 048 @wraps(function) 049 async def wrapper(*args, **kwargs): 050 print(f"异步任务开始:{function.__name__}") 051 try: 052 return await function(*args, **kwargs) 053 finally: 054 print(f"异步任务结束:{function.__name__}") 055 return wrapper 056 057@log_call 058def add(left: int, right: int) -> int: 059 """把两个数字相加。""" 060 return left + right 061 062@add_prefix 063@uppercase 064def message() -> str: 065 return "hello" 066 067@uppercase 068@add_prefix 069def reversed_message() -> str: 070 return "hello" 071 072@require_role("admin") 073def delete_article(user, article_id: int) -> str: 074 return f"已删除文章 {article_id}" 075 076@log_async 077async def greet_async(name: str) -> str: 078 await asyncio.sleep(0) 079 return f"你好,{name}" 080 081async def build_report(name: str, times: int, role: str) -> dict[str, object]: 082 calls = [] 083 @repeat(times) 084 def greet(person: str) -> str: 085 calls.append(person) 086 print(f"第 {len(calls)} 次问候:{person}") 087 return f"你好,{person}" 088 089 repeated_result = greet(name) 090 try: 091 permission_result = {"allowed": True, "result": delete_article({"role": role}, 10)} 092 except PermissionError as error: 093 # 将这次教学用的权限失败作为结果展示,不吞掉其他异常。 094 permission_result = {"allowed": False, "error": type(error).__name__, "message": str(error)} 095 return { 096 "logged_add": add(2, 3), 097 "function_info": {"name": add.__name__, "docstring": add.__doc__}, 098 "repeat": {"times": times, "actual_calls": len(calls), "result": repeated_result}, 099 "order": {"prefix_outside": message(), "uppercase_outside": reversed_message()}, 100 "permission": permission_result, 101 "async_result": await greet_async(name), 102 } 103
01from typing import Literal 02 03from fastapi import FastAPI, Query 04 05from decorators_demo import build_report 06 07app = FastAPI() 08 09@app.get("/decorators") 10async def decorators( 11 name: str = Query("小微", min_length=1, max_length=80), 12 times: int = Query(3, ge=1, le=5), 13 role: Literal["admin", "reader"] = "reader", 14) -> dict[str, object]: 15 return await build_report(name, times, role) 16
01[project] 02name = "python-decorators" 03version = "0.1.0" 04description = "Python 装饰器" 05readme = "README.md" 06requires-python = ">=3.12" 07dependencies = [ 08 "fastapi[standard]==0.136.1; sys_platform != 'emscripten'", 09 "fastapi==0.136.1; sys_platform == 'emscripten'", 10 "pydantic==2.12.5", 11 "httpx==0.28.1", 12] 13 14[tool.uv] 15package = false 16
其余配置文件可在在线案例左侧的文件目录中查看,也会包含在下载包里。接口的输入有明确的长度、数量或数值范围,超出范围时 FastAPI 会返回 422。
422
打开在线案例,点击运行,等待环境就绪。案例预览默认使用 GET,地址是:
GET
1/decorators?name=小微×=3&role=reader
默认请求会让问候函数实际执行三次,repeat.actual_calls 为 3,日志也会出现三条问候记录。function_info.name 仍然是 add,文档字符串也被保留,这是 @wraps 的作用。
repeat.actual_calls
3
function_info.name
add
两个堆叠顺序分别返回 result: HELLO 和 RESULT: HELLO。在线实验使用英文前缀,因此改变外层的大小写装饰器会产生可见差异。把 role 改为 admin 后,权限检查会成功;默认 reader 的 PermissionError 被明确捕获到响应字段中,接口仍正常返回。
result: HELLO
RESULT: HELLO
role
admin
reader
PermissionError
异步函数确实由 await greet_async(name) 调用,日志会显示异步任务开始和结束,不使用 asyncio.run() 新建事件循环。可以修改 repeat() 或两个文本装饰器,保存并重新运行。次数限制在 1 到 5,避免重复实验占用过长时间。
await greet_async(name)
repeat()
1
5
下载 ZIP 并解压,在项目目录执行:
1uv run fastapi dev main.py
然后打开 http://127.0.0.1:8000/docs,选择对应接口,填写和在线案例相同的参数发送请求。
http://127.0.0.1:8000/docs
本机使用 .python-version 指定的 Python 3.12,浏览器使用当前 Pyodide 的 Python 版本。在线案例通过 ASGITransport 执行 FastAPI,不监听本机端口,无需安装本机 Python。每次请求都会新建本次实验的状态,本篇的代码草稿、Git、日志和 Agent 对话也与其他文章分开保存。
.python-version
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 包装
装饰器(decorator)是一种接收函数、再返回新函数的高阶函数。新函数通常会先执行一些附加逻辑,再调用原函数。
例如,很多函数都需要记录「开始执行」和「执行结束」。如果每个函数都手动写一遍,代码会重复。可以把这段公共逻辑放进装饰器:
log_call()接收原来的greet,返回一个新的wrapper。重新赋值后,调用greet()实际上是在调用包装函数,原来的问候逻辑仍然由function()执行。装饰器的重点是「在不修改原函数主体的情况下,为它增加行为」。日志、计时、权限检查、缓存和重试都适合抽成这种公共包装逻辑。
2. 语法
Python 提供
@语法,让装饰器的使用更直观:函数定义前的
@log_call等价于下面的重新赋值:装饰器在函数定义完成时执行一次,而不是每次调用函数时重新执行。也就是说,模块加载过程中先创建
greet,再调用log_call(greet)得到新的函数;以后每次greet()都只调用已经生成的包装函数。这也解释了装饰器的两个调用阶段:装饰阶段接收函数并返回包装函数,运行阶段才由包装函数接收真正的业务参数。
3. 参数
真实函数通常有位置参数、关键字参数和返回值,包装函数应该使用
*args与**kwargs接收它们,并把结果返回给调用方:*args收集位置参数,**kwargs收集关键字参数;调用原函数时再次展开它们,才能保持原函数的调用方式。return result也很重要,否则装饰后的函数会丢失原来的返回值。@wraps(function)来自functools,它会把原函数的名称、文档字符串等信息复制到包装函数上。没有它时,add.__name__会变成wrapper,调试、日志和框架读取函数信息时都不够准确。包装函数还可以处理异常,但不要无意中吞掉异常。下面的
finally无论成功还是失败都会执行,原异常仍然会继续抛出:4. 配置
有时装饰器本身也需要参数,例如希望调用函数三次。此时需要多包一层:最外层接收配置,中间层接收函数,最内层才接收业务参数:
@repeat(3)并不是把数字直接传给greet()。它会先执行repeat(3),得到decorator;再用decorator(greet)得到最终的wrapper。调用greet("小明")时,wrapper才会循环调用原函数三次。装饰器配置还可以用于权限检查。把权限名称提前传入后,同一个装饰器工厂就能生成不同规则:
在 FastAPI 项目中,鉴权、日志和限流也可以采用类似思路。不过框架通常已经提供了依赖注入或中间件机制,应该先使用框架的标准能力,再决定是否自定义装饰器。
5. 组合
一个函数可以同时使用多个装饰器。装饰器从下往上应用,但调用时从上往下进入:
上面的写法等价于:
调用
message()时,先进入外层的add_prefix包装函数;它内部再调用uppercase包装函数,最后才执行原始的message。装饰器较多时,要注意顺序,因为交换顺序可能改变最终结果。Python 自带和标准库中也有很多装饰器,例如类文章中介绍过的
@property、@classmethod、@staticmethod,以及数据类使用的@dataclass。它们本质上都在函数或类定义完成时,对定义结果进行包装或改造。异步函数需要使用异步包装函数,否则包装器无法正确等待原函数:
在 FastAPI 的异步接口中调用
await show_result(),就会实际等待装饰后的函数;异步开始、结束和问候结果也会依次输出。浏览器案例已经运行在事件循环中,直接使用await,无需再调用asyncio.run()。这类装饰器适合 FastAPI 的异步接口或异步 LangChain 调用。同步函数和异步函数不能直接使用同一种包装方式,需要保持
async和await的调用模型一致。6. 取舍
装饰器适合给多个函数增加相同的横切逻辑,但它也会增加调用链的间接层。看到一个被装饰的函数时,读者需要跳转到装饰器才能了解完整行为。
可以按照下面的原则判断是否使用装饰器:
@wraps,保留原函数的名称和文档信息;async def和await;装饰器不是为了让代码看起来更高级,而是为了把重复的外围逻辑集中维护。只要增加的抽象让调用关系更难理解,就应该考虑改回普通函数或使用更明确的服务对象。
7. 在线装饰器实验
本篇把前面的知识放进一个可修改的 Python 项目。
main.py只负责接收参数并调用实验函数,decorators_demo.py保存本篇的逻辑。默认接口不需要密钥,也不会调用外部模型。7.1 完整实验代码
7.2 接口与配置
其余配置文件可在在线案例左侧的文件目录中查看,也会包含在下载包里。接口的输入有明确的长度、数量或数值范围,超出范围时 FastAPI 会返回
422。7.3 运行和观察
打开在线案例,点击运行,等待环境就绪。案例预览默认使用
GET,地址是:默认请求会让问候函数实际执行三次,
repeat.actual_calls为3,日志也会出现三条问候记录。function_info.name仍然是add,文档字符串也被保留,这是@wraps的作用。两个堆叠顺序分别返回
result: HELLO和RESULT: HELLO。在线实验使用英文前缀,因此改变外层的大小写装饰器会产生可见差异。把role改为admin后,权限检查会成功;默认reader的PermissionError被明确捕获到响应字段中,接口仍正常返回。异步函数确实由
await greet_async(name)调用,日志会显示异步任务开始和结束,不使用asyncio.run()新建事件循环。可以修改repeat()或两个文本装饰器,保存并重新运行。次数限制在1到5,避免重复实验占用过长时间。7.4 本机运行
下载 ZIP 并解压,在项目目录执行:
然后打开
http://127.0.0.1:8000/docs,选择对应接口,填写和在线案例相同的参数发送请求。本机使用
.python-version指定的 Python 3.12,浏览器使用当前 Pyodide 的 Python 版本。在线案例通过 ASGITransport 执行 FastAPI,不监听本机端口,无需安装本机 Python。每次请求都会新建本次实验的状态,本篇的代码草稿、Git、日志和 Agent 对话也与其他文章分开保存。