一、装饰器本质是什么Python 装饰器本质上是接收函数并返回新函数的高阶函数。decorator只是语法糖等价于func decorator(func)。它适合处理横切逻辑例如日志、鉴权、重试、缓存、指标和事务。用途装饰器价值日志统一记录入参和耗时权限在业务函数前校验重试封装异常处理缓存避免重复计算装饰器要克制使用。业务逻辑藏得太深会让代码阅读和调试变困难。二、保留函数元信息最常见的坑是装饰器返回的 wrapper 覆盖了原函数的__name__、__doc__和类型信息影响日志、文档和框架路由。应使用functools.wraps。importfunctoolsimporttimedeflog_time(func):functools.wraps(func)defwrapper(*args,**kwargs):starttime.perf_counter()try:returnfunc(*args,**kwargs)finally:cost(time.perf_counter()-start)*1000print(f{func.__name__}cost{cost:.2f}ms)returnwrapperlog_timedefquery_order(order_id:int):return{id:order_id}生产中不要直接print应接入结构化日志或指标系统。装饰器负责通用行为具体字段要避免泄露密码、Token 等敏感信息。三、带参数的装饰器带参数装饰器多包一层函数用于配置重试次数、缓存时间或权限标识。下面示例实现有限重试只对指定异常生效。importfunctoolsimporttimedefretry(times3,delay0.2,errors(Exception,)):defdeco(func):functools.wraps(func)defwrapper(*args,**kwargs):foriinrange(times):try:returnfunc(*args,**kwargs)excepterrors:ifitimes-1:raisetime.sleep(delay*(i1))returnwrapperreturndeco重试不是万能补救。只能用于幂等操作并设置最大次数和退避。对写接口盲目重试可能造成重复扣款、重复发消息或数据错乱。四、异步函数和框架集成装饰器用于异步函数时wrapper 也必须是async def并且用await调用原函数。同步装饰器包住异步函数会返回协程对象而不是执行结果。defrequire_user(func):functools.wraps(func)asyncdefwrapper(request,*args,**kwargs):ifnotrequest.user:raisePermissionError(login required)returnawaitfunc(request,*args,**kwargs)returnwrapper生产级装饰器要做到三点行为清晰、异常透明、元信息完整。它应减少重复代码而不是制造隐式流程。对于复杂逻辑优先考虑显式中间件、依赖注入或服务对象装饰器只保留真正通用且稳定的部分。测试装饰器时既要测正常返回也要测异常、重试次数和元信息是否保留。多个装饰器叠加时执行顺序从下到上应用、从外到内调用顺序不同可能改变鉴权、缓存和日志行为。团队最好把公共装饰器集中维护并写清楚适用边界。一个好的装饰器应该像薄薄的协议层让业务函数更专注而不是让调用链变得不可见。类型标注也值得保留。复杂项目可以使用ParamSpec和TypeVar描述被装饰函数的参数与返回值减少 IDE 和静态检查失效。对框架接口来说签名信息可能被路由、依赖注入或文档生成读取随意包装会造成运行期问题。装饰器越接近基础设施越要重视可测试性和类型透明度。如果装饰器需要读取配置应在应用启动时完成校验避免第一次请求才暴露错误。日志中也要能看出装饰器是否生效。 本文是《工程化编码实战》系列持续更新关注不迷路。 下一篇《可复用项目脚手架该包含什么》讲公共能力如何从函数包装扩展成可维护的项目骨架。 你在实际项目里遇到过装饰器叠加后调用顺序混乱或函数签名丢失的问题吗评论区聊聊。觉得有用点个赞收藏方便回头查阅 相关可运行源码/资料已整理成资源包可在我主页的资源里自取。