gateway-workers

Gateway Workers

实现 Worker 之前，请先阅读当前的 Forward 指南。该指南定义了 Gateway 如何在允许的 HTTP 流量上调用 Worker。请检索下方的相关页面，不要凭记忆将设置步骤、API 负载或限制复制到项目中。

工作流

1. 检查现有 Worker，并根据所需的转换、合成响应或后台任务，选择一个 Worker 模板。
2. 从 cloudflare:workers 导出一个名为 GatewayMiddleware、扩展 WorkerEntrypoint 的类。实现 handle(request, context, next) 并返回 Response。Gateway 通过 RPC 调用此方法。仅有默认的 fetch() 处理程序并不符合 Forward 契约。
3. 对于 TypeScript，请按照所选模板当前的程序包安装说明和类型导入说明进行操作。
4. 使用第二个参数获取 Gateway 上下文。它描述原始请求；即使 Worker 修改了请求，该上下文也保持不变。请将它与 this.ctx（Workers 执行上下文）和 this.env（绑定）区分开来。
5. 使用 next(request) 继续处理用户请求，最多调用一次；也可以不调用它，直接返回合成响应。next() 始终指向原始目标。对目标 URL 或主机的修改会被忽略，并且它无法重定向、重试或扇出。使用 fetch() 将请求发送到其他目标。这会创建一个独立的子请求，不会继承用户的 Gateway 策略或出口配置。

上下文

请使用已发布的类型和上下文参考来确认字段名称及其可用性。将虚值身份（!identity）视为匿名身份，并对可选的态势值进行保护。仅在需要时调用 await context.identity() 或 await context.devicePosture()。这两个 getter 都可能拒绝。请将查询失败与值缺失分别捕获，并根据 Worker 对这些值的依赖决定如何处理。请使用 Gateway 提供的身份，而不要使用客户端提供的身份标头。

Gateway 行为

• 只有第一个匹配的 Forward 策略会调用 Worker。调用 Worker 并不代表已成功检查请求正文。请遵循 Forward 指南中的检查顺序。
• Gateway 会检查最终响应，包括合成响应。修改后的请求字节在到达源站前不会再次接受检查。
• 选择流量前，请查看 Forward 指南中的限制：HTTPS 需要解密，WebSockets 会绕过 Worker，匹配的 Workers VPC 流量会被丢弃。Worker 调用失败时会采用失败关闭策略。

验证

请根据已安装的 Gateway 类型进行类型检查，并测试命名的 RPC 入口点，包括零次或一次后续调用，以及 Worker 使用的上下文值。然后，通过范围受限的 Gateway Forward 策略测试允许的请求。直接向默认的 fetch() 处理程序发送请求，无法验证 Gateway 路径。请遵循所选模板的测试流程和 Forward 指南中的故障排除步骤。

请查看响应和流式传输规则：返回 200 到 599 之间的最终状态码；对于 HEAD 请求或状态码 204、205 和 304，不返回正文；并以流的方式传输正文，而不是对其进行缓冲。

相关技能

• cloudflare-one：Gateway 策略设计、流量路径、身份、TLS 和发布。
• workers-best-practices：流式处理、绑定、生成的环境类型、后台工作、可观测性和运行时测试。
• CLI selection：选择现有的 cf-cli 或 wrangler 技能来进行项目设置和部署。