返回专栏
专栏 ·

7.1 装饰器完全指南:无参装饰器、带参装饰器及 @functools.wraps 元信息保留

作者: 九路 共 12 章 · 48 小节

欢迎回到 HelloWorld 技术社区(www.helloworld.net) 《Python 现代开发实战》专栏。

如果说哪项特性最能体现 Python 的优雅与元编程魅力,那一定是 装饰器(Decorator)。它的本质就是第 3 章学过的高阶函数 + 闭包——在不修改原函数任何一行源码的前提下,为函数动态织入日志、鉴权、缓存或耗时统计等横切关注点(AOP)。

标准工业级带参装饰器模板

编写装饰器时有一条绝对不可违背的铁律:永远在内部 wrapper 上加上 @functools.wraps(func),否则原函数的 __name__、__doc__ 和类型签名全会被覆盖成 wrapper,导致 FastAPI 路由注册和自动化文档直接崩溃!

import functools
import time
from collections.abc import Callable
from typing import Any, ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")


def log_slow_calls(threshold_ms: float = 100.0) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """带参装饰器:监控函数执行耗时,超过阈值自动发出慢调用警告"""

    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        @functools.wraps(func)
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            start = time.perf_counter()
            try:
                return func(*args, **kwargs)
            finally:
                elapsed_ms = (time.perf_counter() - start) * 1000
                if elapsed_ms > threshold_ms:
                    print(f"⚠️ [慢函数告警] {func.__name__} 耗时 {elapsed_ms:.2f}ms (阈值 {threshold_ms}ms)")

        return wrapper

    return decorator


@log_slow_calls(threshold_ms=50.0)
def query_hot_articles(limit: int) -> list[str]:
    """查询社区热门文章"""
    time.sleep(0.06)
    return [f"Article-{i}" for i in range(limit)]


query_hot_articles(3)
print("保留的原函数名:", query_hot_articles.__name__)  # query_hot_articles

💬 HelloWorld 社区实战打卡

手写一个无参装饰器 @require_admin,假设原函数的第一个关键字或位置参数是字典 user={"role": "..."},若 role != "admin" 则直接抛出 PermissionError。带 #Python专栏打卡 贴出实现!