mcpField
W
workers-best-practices

workers-best-practices

github.com/tejas-kale云与 DevOps038 次安装3 天前更新
代码仓库

关于 workers-best-practices

workers-best-practices 是面向 Cloudflare Workers 开发者和代码审查者的技能。它要求先检索当前文档、类型和配置架构，再应用规则并报告有证据支持的问题。

主要功能

  1. 01获取最新 Workers 文档与类型
  2. 02应用编写和审查规则
  3. 03检查 TypeScript 与 Promise lint
  4. 04按证据和严重性报告问题

适用场景

  1. 01按当前 Workers API 编写代码
  2. 02审查 Worker 文件中的反模式
  3. 03验证类型、绑定和配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tejas-kale/skills --skill workers-best-practices

安装后在 Claude Code 中输入/workers-best-practices确认已加载。

附带文件references/review.mdreferences/rules.md

详细介绍

Workers 最佳实践

你内置的 Workers API、配置字段和绑定结构知识已经过时。先检索：你提出的每个 API 签名、配置字段和绑定结构，都必须来自本次会话中获取的来源；无法引用来源的发现不得报告。

1. 检索

在编写或审查任何代码之前，先获取资料。优先采用最新发布版本，而不是 node_modules 锁定的版本。

# Latest workers types → /tmp/workers-types-latest/package/index.d.ts
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
来源位置用途
最佳实践页面https://developers.cloudflare.com/workers/best-practices/workers-best-practices/权威规则和反模式
Workers 类型上述 npm packAPI 签名、处理程序类型、绑定类型
Wrangler 配置架构node_modules/wrangler/config-schema.json配置字段、绑定结构、允许的值
Cloudflare 文档搜索，或访问 https://developers.cloudflare.com/workers/API 参考、兼容性日期和标志

完成标准：类型、配置架构和最佳实践页面都已纳入上下文。

2. 应用规则

references/rules.md 是所有规则的唯一事实来源，涵盖配置、请求处理、架构、可观测性、代码模式、安全和测试；每条规则都包含正确模式及其替代的反模式。阅读后，按规则集开展工作：

  • 编写代码 — 你编写的代码必须符合相关章节中的每条规则。
  • 审查代码 — 阅读完整文件，而不只是差异，因为只有结合上下文才能正确理解绑定访问和全局状态；然后逐条核对规则。

完成标准：已应用 references/rules.md 中的每条规则，或经过审慎判断确认其不适用；不能只检查那些显而易见的规则。

3. 验证并报告

运行 npx tsc --noEmit，并针对 no-floating-promises 运行 lint；工具能够检查的规则，就应交由工具检查，而不是靠目测。

对于代码审查，references/review.md 提供了审查专用参考资料，涵盖类型和配置验证、序列化边界、如何区分示例代码与可执行代码的评级、风险级别以及发现项格式。撰写发现项之前请先阅读。

完成标准：每条发现都注明文件和行号、引用证据，并标明严重级别。

需要标记的反模式

以下是常见问题，可作为扫描清单；每项的完整说明见 references/rules.md。

反模式重要原因
对无界数据执行 await response.text()内存耗尽 — 限制为 128 MB
在源代码或配置中硬编码机密通过版本控制泄露凭据
使用 Math.random() 生成令牌或 ID可预测，不具备密码学安全性
调用 fetch() 时未使用 await 或 waitUntilPromise 未处理 — 结果被丢弃，错误被吞掉
使用模块级可变变量保存请求状态请求间数据泄露、状态过期、I/O 错误
在 Worker 内调用 Cloudflare REST API增加网络跳转、身份验证开销和延迟
将 ctx.passThroughOnException() 用作错误处理隐藏错误，导致无法调试
手写 Env 接口与实际 wrangler 配置中的绑定定义不一致
直接比较字符串形式的机密存在计时侧信道 — 应使用 crypto.subtle.timingSafeEqual
解构 ctx（const { waitUntil } = ctx）丢失 this 绑定 — 运行时会出现 “Illegal invocation”
在 Env 或处理程序参数上使用 any破坏对所有绑定访问的类型安全检查
使用 as unknown as T 双重类型断言掩盖真实的类型不兼容 — 应修正设计
在平台基类上使用 implements已过时 — 会丢失 this.ctx 和 this.env；对 DurableObject、WorkerEntrypoint、Workflow 使用 extends
在平台基类中使用 env.X应使用 this.env.X

范围

仅限 Workers 本身。对于更广泛的平台功能 — Durable Objects、Workflows、Wrangler 命令、KV/D1/R2 — 请加载 cloudflare 总括技能，其 references/ 目录中为每种产品都提供了单独的文件。

评论

支持 Markdown