00.范式-装饰器介绍

本文件是 02.开发-02.python-装饰器 下装饰器工具专篇的作者侧写作规范。
目标：读者打开任意一篇，能快速查到「装饰什么、参数怎么填、最小示例怎么跑」。
正式对外的装饰器正文，禁止出现对本地其他文件包括本文件或「按范式写作」的任何引用（见「绝对禁区」）。

改结构时先改本文件，再回写样例，保持「范式 → 样例」单向一致。

命名约定

专篇文件名格式：

{作用对象}-{使用场景}-{名称}.md

字段	约束	说明
作用对象	≤4 字	装饰器主要修饰谁
使用场景	≤4 字	解决什么问题
名称	通行写法	保留官方名；带括号写主名（如 mcp.tool、click）

硬性：文件名、配图目录、图片文件名均不得含空格，用 - 分隔。

作用对象词库

值	覆盖范围
函数	普通函数、协程、生成器
类	类装饰器，或类内描述符（@property 等）
枚举	enum 相关
模块	按需

使用场景词库

值	典型装饰器
属性访问	@property、@cached_property
方法绑定	@classmethod、@staticmethod
缓存	@lru_cache、@cache
CLI	click 系列
日志	logging 装饰器
性能	计时、profiling
校验	参数/返回值校验
中间件	Web 框架中间件式装饰器
服务注册	@mcp.tool、@app.route
多态分发	@singledispatch
生命周期	@atexit.register
唯一约束	@enum.unique
元编程	@dataclass、@wraps

同一库的多装饰器族（如 click.group / click.command / click.option）：优先一篇专篇 + 分节，文件名用库名：函数-CLI-click.md。

索引与概念文命名：

文类	文件名
写作范式	00.范式-装饰器介绍.md
读者索引	00.索引-装饰器速查.md
机制概念	00.概念-装饰器机制.md

读者与文体

读者：会写 Python，需要查阅装饰器用法，不需要从零讲语言基础。

文体：工具参考手册——定位表 + 参数表 + 可复制示例；不写聊天体，不推完整实现原理。

与相邻目录边界：

文类	放哪里
单个装饰器用法	本目录专篇
FastAPI 中间件整体	02.开发-02.python-FastAPI/
装饰器实现原理（闭包、描述符）	00.概念-装饰器机制.md 或 Python 基础专题

单篇专篇结构

新稿默认顺序如下；定位表 / 重点参数 / 最小示例 / 易踩坑 建议必有。

0. 一句话定位

定位表四行：

维度	内容
作用对象	…
使用场景	…
来源	标准库 / 第三方包及版本
语法形式	@xxx 或 @xxx(...)

缩写首次出现按项目体例：中文全称（英文全称，缩写）；段末可用引用块短注。

1. 做什么

2～4 句：装饰后调用方式、返回值、与原函数/类的关系变化。

2. 重点参数

表头固定：

| 参数 | 类型 | 默认值 | 作用 | 配置建议 |

• 只列实务中常改的 3～8 个参数；无参装饰器写一行「无参」
• 配置建议须可执行，禁止空话

装饰器族专篇（如 Click）：按子装饰器分 ### @click.command 等小节，每节各一张参数表 + 示例。

3. 最小可运行示例

10～40 行，可复制；有预期输出时用 shell 块。

4. 常见变体（可选）

同一装饰器的组合用法、参数变体。

5. 适用 / 不适用

各 2～4 条，带具体场景。

6. 易踩坑（≥1 条）

7. 近邻替代（可选）

8. 参考

官方文档 1～2 条。

索引文档结构

00.索引-装饰器速查.md 用表格索引，不在索引里堆长示例：

| 作用对象 | 使用场景 | 名称 | 来源 | 专篇 |

可按「使用场景」再分组浏览。

绝对禁区

专篇正文禁止：

1. 「见范式」「按本目录模板」「详见 00.范式…」
2. 同目录互引（「上一篇讲了 @wraps」）
3. 教科书开场、套话、踩雷词（「说白了」「本质上」「综上所述」等）
4. 把命名约定写进读者正文

允许：外链官方文档、PyPI、GitHub。

质量自检清单

• 文件名 {作用对象}-{使用场景}-{名称}.md 三段齐全
• 有定位表四行
• 有重点参数表（或明确无参）
• 最小示例可独立运行
• ≥1 条易踩坑
• 无范式互引
• 已写入 00.索引-装饰器速查.md
• 缩写体例符合项目约定

迭代记录（作者备注）

版本	日期	变更
v0.1	2026-08-03	初版：命名、专篇骨架、Click 族一篇多节规则；旧稿拆分重构