--- title: "示例" description: "展示可复制、可运行的完整代码，让读者直接拿走并改造。" --- > Documentation Index > Fetch the complete documentation index at: https://nimbus.ndjp.net/llms.txt > Use this file to discover all available pages before exploring further. # 示例 > **需求** > > 处于工作、正在行动 —— 读者想要能复制并改造的可运行代码。他们的第一个问题：*“给我看 X 的可运行代码。”* 不是要遵循的流程（操作指南），不是课程（教程），而是展示某件事*怎么完成*的代码。 > > 这是当今杠杆最高的类型：人们从代码示例开始读，智能体会把示例逐字粘贴进代码库。 ## 适用场景 当**代码就是内容**时写示例 —— 一个模式、一次集成、一份值得整体复制的配置。它不是： - **操作指南。** 操作指南是*流程* —— 跨多个界面的动作（控制台、CLI、代码），最后做验证。示例是*清单* —— 读者唯一的动作是复制和改造。如果读者必须在代码之外做事情才能跑通，要么把它们收进一行假设说明，要么写操作指南。 - **参考。** 参考完整且中立，按产品界面索引。示例有选择、有观点，按读者目标索引。参考展示 `send()` 接受的每个字段；示例只展示你用来批量发送的那三个。 - **教程。** 没有叙述、没有教学、没有分部。示例假设读者已具备能力，然后让开。 本类型的两条定律： 1. **完整且可运行。** 完整导入、完整配置、没有省略行 —— 一个 “你需要自己改改” 的片段不是示例，是作业。复制粘贴必须产生页面展示的结果。 2. **经过测试。** 不能运行的示例代码比没有更糟 —— 它会在读者编辑器里失败，却顶着产品的名字。尽量在 CI 中运行它们；无论如何都要盖上 `lastVerified`。 ## 标题与描述 - **标题：目标加技术栈。** “**在 Next.js 路由处理器中**验证签名” · “**用 Redis** 消除 webhook 突发流量。” 操作指南陈述中立目标（“轮换签名密钥”）；示例要写出代码所处的环境，因为代码就是内容。不要 “示例 3” 或 “杂项片段”。 - **描述公式：**“*代码做什么*，写在*它面向的技术栈*里。” —— 例如 “在 Next.js 路由处理器中验证 Hookline 签名，并拒绝重放。” ## 脚手架生成本页 安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整： ```sh npx @cloudflare/nimbus-docs add content-example yarn nimbus-docs add content-example pnpm nimbus-docs add content-example bunx @cloudflare/nimbus-docs add content-example ``` **食谱式（cookbook）页面。** 若干相关示例可以共用一个页面，用**名词短语作分类标题**（“签名验证”“批量处理”）。每个 `##` 条目遵循单页骨架但去掉 frontmatter：目标行、假设行、代码、展示结果、工作原理。 页面的 `lastVerified` 指其中*验证时间最早*的条目。先把相关示例加到分类页，等某个条目的代码超过一屏时再拆出去。 ## 组件建议 - **带标题的代码块**（`title="app/api/hooks/route.ts"`）是标志性组件 —— 文件名是承重上下文。多文件示例用代码分组；如果诚实地只有一个文件，那就更好。 - **代码内的注释**承载使用现场说明（`// rejects deliveries signed >5 min ago`）—— 这是代码注释胜过散文的唯一地方，因为它们能挺过复制粘贴。 - **不适合：** Steps（这里没有要执行的操作）、卡片、折叠面板（藏起来的代码既找不到也提不出）、按语言分标签页*除非每个标签页都维护并测试过* —— 未测试的标签页是藏在已测试标签页背后的坏示例。 ## 结尾 **展示结果 → 工作原理（需要时）→ 另见。** 没有验证分节（那是操作指南的动作 —— 这里由展示结果和测试承担），没有下一步旅程（读者是为代码而来，也会带着代码离开）。 ## 阈值 - **每个示例一个目标。** 标题测试：如果需要 “和”，就拆开。 - **解释不能超过代码。** 当 “工作原理” 开始需要成段文字而不是要点时，说明有个概念或操作指南想逃出来 —— 链接过去。 - **处理该模式相关的错误；其余让它抛出。** 开头就说明错误处理约定，避免条目在裸正常路径和生产加固之间来回摇摆。为目标不需要的代码加防御，是伪装的散文。 - **食谱页面：每个条目使用相同内部模板**，按目标索引，最想要的排在最前。 ## 链接与时效 链接模式背后的概念，以及每个魔法值对应的参考，并从相关操作指南*反向*链接到示例（“只要代码？→”）。 时效性是这个类型的全部声誉。在每个触及相关 API 的版本上重跑示例，尽量放进 CI，并盖上 `lastVerified`。不再能编译的代码，是产品无人维护最响亮的信号。 ## 智能体说明 - 智能体会逐字搬用示例，所以**完整就是正确**：省略的导入会在别人的代码库里变成臆造的导入；代码里的 `...` 会变成任何东西。 - 把假设写成页面上可核对的事实（版本、环境变量）—— 智能体无法从你项目的渲染截图推断它们。 - 全程使用真实值；占位符只放在尖括号里（``），且只在真实值不可能存在时使用。 - “工作原理” 要点是检索金矿：它们把不直观的那行代码和原因放在同一个块里，这正是阻止智能体 “简化” 承重部分（`req.text()` → `req.json()`）的关键。任何依赖特定提供商行为的要点都要明确标出，让改造中的智能体知道要重新核对什么。 ## 检查清单 建议性 —— 供作者或智能体自检，永不作为构建闸门： - [ ] 标题是目标加技术栈（食谱页：名词短语分类）；一个目标 - [ ] 假设用一行写出，作为可核对的事实（版本、环境） - [ ] 代码完整、粘贴即可运行 —— 完整导入、零省略、在严格设置下通过类型检查 - [ ] 有展示结果：粘贴代码产生的输出，以及如何触发它 - [ ] 使用真实值；占位符只放在尖括号中 - [ ] “工作原理” 只覆盖不直观的行；标出提供商特定假设 - [ ] 错误处理限定在该模式相关范围内 - [ ] 变体是链接，不是硬塞进来的清单；食谱条目共用一种内部模板 - [ ] 已针对当前版本测试（尽量放进 CI）；已盖上 `lastVerified`（食谱页：最早条目） Source: https://nimbus.ndjp.net/style-guide/example/index.mdx