workers-code-review

你对 Cloudflare Workers API、类型和 wrangler 配置的了解可能已经过时。审查 Workers 代码时，优先检索，而不是依赖预训练知识。

参考来源

使用仓库中的本地副本——不要运行 npm pack 或安装软件包来获取类型。

来源	查找位置	用途
Wrangler 配置架构	node_modules/wrangler/config-schema.json	配置字段、绑定形状、允许的值
Workers 类型	node_modules/@cloudflare/workers-types/index.d.ts	API 用法、处理程序签名、绑定类型
Cloudflare 文档搜索	使用 cloudflare-docs 搜索工具，或读取此仓库中的文件	API 参考、兼容性日期/标志、绑定文档

需要验证类型、配置字段或 API 签名时，请直接读取这些文件。本文件夹中的指南说明了需要验证什么，而不是如何获取软件包。

审查流程

1. 构建上下文

阅读完整文件，而不只是差异或孤立片段。单独看起来有问题的代码，结合周边逻辑后可能是正确的。

• 确定代码的用途：它是完整的 Worker、代码片段，还是配置示例？
• 查看 git 历史以了解背景：git log --oneline -5 -- <file>
• 了解代码依赖的绑定、类型和模式

2. 对代码分类

每个代码块都属于以下三类之一。请结合其类别的上下文进行审查。

类别	定义	预期要求
说明性	演示某个概念；大部分逻辑通过注释说明	API 名称正确，签名合理
演示性	功能完整但不完整；放在合适的上下文中即可运行	语法有效，API 和绑定访问正确
可执行	独立且完整；无需修改即可运行	能编译、能运行，并包含导入和配置

3. 使用工具验证

运行类型检查和 lint。工具输出是证据，而非观点。

npx tsc --noEmit                    # TypeScript errors
npx eslint <files>                  # Lint issues

对于配置文件，请根据最新的 wrangler 配置架构进行验证（检索方法见 wrangler-config.md），并检查所有字段、绑定类型和值是否符合要求。

4. 对照规则检查

类型系统规则见 workers-types.md，配置验证见 wrangler-config.md，正确的 API 用法模式见 common-patterns.md。

快速参考规则：

规则	详情
绑定访问	模块导出处理程序中使用 env.X；扩展平台基类的类中使用 this.env.X。参见 common-patterns.md。
不使用 any	绑定类型、处理程序参数或 API 响应中绝不使用 any。请使用合适的泛型。
不走类型系统捷径	标记 as unknown as T、无正当理由的 @ts-ignore 和不安全的类型断言。参见 workers-types.md。
配置与代码一致	wrangler 配置中的绑定名称必须与代码中使用的 env.X 一致。参见 wrangler-config.md。
必填配置字段	根据 wrangler 配置架构进行核验——不要假设哪些字段是必填的。
简洁示例	示例应聚焦核心逻辑。尽量减少会分散读者对代码所教内容注意力的样板代码。
未处理的 Promise	每个 Promise 都必须经过 await、return、void 处理，或传递给 ctx.waitUntil()。参见 common-patterns.md。
序列化	跨越 Queue、Workflow 步骤或 DO 存储边界的数据必须可通过结构化克隆序列化。参见 common-patterns.md。
流式处理	大型或大小未知的负载必须采用流式处理，而不是缓冲。标记对无界数据调用的 await response.text()。
错误处理	应尽量精简，但不能缺失——对可为空的返回值进行空值检查，并进行基本的 fetch 错误处理。不要加入冗长的 try/catch，以免分散注意力。

5. 评估风险

风险	触发因素
高	身份验证、加密、外部调用、价值转移、移除验证、访问控制、绑定配置错误
中	业务逻辑、状态变更、新增公共 API、错误处理、配置变更
低	注释、日志记录、格式调整、细微的代码风格问题

重点深入分析高风险项。对于关键路径，请检查影响范围：还有多少其他文件引用了这段代码？

安全逻辑升级审查：对于加密、身份验证和对时间敏感的代码，不要只确认 API 调用是否正确。还要检查周边逻辑中是否存在会破坏安全属性的缺陷（例如，timingSafeEqual 调用正确，但长度不匹配时提前返回）。参见 common-patterns.md 的 Security 部分。

应标记的反模式

反模式	重要原因
Env 或处理程序参数使用 any	会破坏后续所有绑定访问的类型安全
使用 as unknown as T 双重类型断言	隐藏实际的类型不兼容问题——应修复底层设计
使用 @ts-ignore / @ts-expect-error 却不作说明	会默默掩盖错误；每次抑制错误都必须附上说明
缓冲无界数据（对流调用 await res.text()、await res.json()）	大型负载可能耗尽内存；应使用流式处理
硬编码机密信息或 API 密钥	使用 env 绑定和 wrangler secret
对每个请求都使用 blockConcurrencyWhile	仅用于初始化；会阻塞所有并发请求
使用单个全局 Durable Object	会造成瓶颈；应按协调键分片
DO 中仅保存在内存中的状态	驱逐时会丢失；应持久化到 SQLite 存储
配置中缺少 DO 迁移	新的 DO 类需要迁移条目，否则部署会失败
未等待的 Promise（step.do()、未使用 await 的 fetch()）	会导致隐蔽错误——丢弃结果、破坏 Workflow 持久性并忽略错误
跨边界传递不可序列化的值（step/queue 中的 Response、Error）	编译通过，但运行时会失败；跨越边界前应提取纯数据
对平台基类使用 implements 而非 extends	这是过时模式——无法通过基类访问 this.ctx、this.env

不应标记的内容

• 代码风格问题（lint 工具未强制检查）
• 代码正确且清晰时，仅仅“可以写得更整洁”
• 缺乏证据的理论性能问题
• 示例范围之外缺失的功能
• 未修改代码中已有的问题

输出格式

**[SEVERITY]** Brief description
`file.ts:42` — explanation with evidence (tool output, type error, config mismatch)
Suggested fix: `code` (if applicable)

严重性：CRITICAL（安全、数据丢失、崩溃）| HIGH（类型错误、错误的 API、配置损坏）| MEDIUM（缺少验证、边缘情况、过时模式）| LOW（风格、小幅改进）

最后按严重性汇总问题数量。如果未发现问题，请直接说明。

原则

• 确保判断准确。 标记问题前先调查。如果无法确认某个 API、绑定模式或配置字段，请先查阅文档或架构定义。
• 提供证据。 引用行号、工具输出、架构字段或类型定义。
• 正确性优先于完整性。 简洁且有效的示例，胜过内容全面却有错误的示例。
• 遵循现有模式。 除非现有约定确实有害，否则不要标记代码库中已经确立的惯例。
• 关注开发者会复制的内容。 文档中的代码会被粘贴到生产环境中，应认真对待。