企业官网建设流程全解析

Cloudflare Workers 兼容性标志 fetcher_no_get_put_delete：移除 Fetcher 上的 get/put/delete 辅助方法

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs

导读

本文围绕 Cloudflare Docs 仓库中的兼容性标志文档 fetcher-no-get-put-delete.md 展开，深入解析 Workers 运行时中Durable Object stub 与 Service Bindings 上遗留的get()/put()/delete()辅助方法被移除的前因后果、启用方式与迁移影响。读完本文，你将理解该兼容性标志（fetcher_no_get_put_delete）与反向标志（fetcher_has_get_put_delete）的作用机制，掌握通过compatibility_date、compatibility_flags、Cloudflare Dashboard 或 API 配置该行为的方法，并了解这一变更如何为自定义同名方法铺平道路。

背景：Fetcher 类型对象的fetch()方法

在 Workers 运行时中，有两类 API 对象实现了与全局fetch()行为类似、但路由方式完全不同的fetch()方法：

• Durable Object stub：通过DurableObjectNamespace#get()/getByName()获取的客户端句柄，用于向远端 Durable Object 发送请求。其接口定义见 durable-objects/api/stub.mdx，stub 的fetch()会将请求直接投递到该对象实例，而非依据 URL 路由。
• Service Bindings（服务绑定）：Worker A 声明对 Worker B 的绑定后，可通过绑定对象上的fetch()把Request对象转发给 Worker B。典型用法见 service-bindings/http.mdx。

这些fetch()方法与全局fetch()的关键区别在于：请求的目标不是由 URL 决定的，而是由被调用对象所代表的目标实体决定的。也就是说，调用env.WORKER_B.fetch(request)时，请求会被送往WORKER_B绑定的 Worker，而不是按 URL 域名解析。

遗留辅助方法：get()/put()/delete()

原文档指出，历史上凡是实现了fetch()方法的此类 API 对象，同时还会暴露get()、put()、delete()三个方法。它们是围绕fetch()的"薄封装"（thin wrappers）：

• 自动执行对应的 HTTP 方法（GET / PUT / DELETE）；
• 自动处理请求体与响应体的写入与读取。

换句话说，开发者原本可以写出类似下面这样的调用模式（示意，因为该 API 从未被正式文档化）：

// 示意代码：遗留的辅助方法语义 await stub.put(request, body); // 相当于 fetch(request, { method: "PUT", body }) const value = await stub.get(request); // 相当于 fetch(request, { method: "GET" }) await stub.delete(request); // 相当于 fetch(request, { method: "DELETE" })

变更内容与生效方式

核心变更

原文档明确说明：这些辅助方法是"许多年前非常早期的想法"，从未被正式文档化，因此"很少（甚至从不）被使用"。Cloudflare 决定将其移除，具体触发条件有两个，满足其一即生效：

1. 显式开启标志：在配置中启用fetcher_no_get_put_delete；
2. 兼容日期达标：设置compatibility_date为2024-03-26或之后的日期。

从标志文件的 Frontmatter 可以看到完整的元数据定义（fetcher-no-get-put-delete.md）：

name: "Fetchers no longer have get/put/delete helper methods" sort_date: "2024-03-26" enable_date: "2024-03-26" enable_flag: "fetcher_no_get_put_delete" disable_flag: "fetcher_has_get_put_delete"

其中：

• enable_flag（fetcher_no_get_put_delete）：移除辅助方法；
• disable_flag（fetcher_has_get_put_delete）：保留辅助方法，用于在较新的兼容日期下主动恢复旧行为；
• enable_date/sort_date（2024-03-26）：该变更随兼容日期默认生效的时间点。

这一组元数据字段与仓库中的兼容性标志 schema 严格对应。见 src/schemas/compatibility-flags.ts，其中定义了name、enable_date、enable_flag、disable_flag、sort_date、experimental等字段，本标志属于普通（非实验性）标志。

配置方式一：Wrangler（推荐）

最常用的方式是在wrangler.jsonc中同时设置兼容日期与标志列表。参考 compatibility-dates.mdx 与 compatibility-flags.mdx 中的通用配置模式：

{ // 设置兼容日期为 2024-03-26 或之后，即可默认禁用辅助方法 "compatibility_date": "2024-03-26" }

如果你希望把compatibility_date保持在2024-03-26之前（保留旧行为），但又要单独开启本次变更，可以显式列出标志：

{ "compatibility_date": "2024-03-02", "compatibility_flags": ["fetcher_no_get_put_delete"] }

反过来，如果你已经使用了2024-03-26及之后的兼容日期，但出于某些原因仍依赖这些辅助方法，可以显式反向恢复：

{ "compatibility_date": "2025-01-01", "compatibility_flags": ["fetcher_has_get_put_delete"] }

注意：compatibility_flags既可以提前启用未来变更，也可以关闭过去已默认生效的变更。修改后需重新运行npx wrangler deploy才会对线上 Worker 生效。

配置方式二：Cloudflare Dashboard

在 Cloudflare Dashboard 的Workers 设置中更新兼容日期与兼容标志。通过 Dashboard 新建 Worker 时，compatibility_date会自动设置为当前日期——也就是说，凡是 2024-03-26 之后通过 Dashboard 新建的 Worker，默认即不再具备get/put/delete辅助方法。

配置方式三：Cloudflare API

通过 Workers Script API 或 Workers Versions API 上传 Worker 时，可在请求体的metadata字段中携带compatibility_date与compatibility_flags。需要注意：API 未显式指定兼容日期时，会回退到最老的兼容日期（2021-11-02，早于任何标志生效），因此通过 API 创建新 Worker 时强烈建议把compatibility_date设置为当前日期。

变更动机：为自定义同名方法让路

原文档给出了移除这些辅助方法的核心理由：

This change paves a future path for you to be able to define your own custom methods using these names. Without this change, you would be unable to define your ownget,put, anddeletemethods, since they would conflict with these built-in helper methods.

也就是说，只要内建的get/put/delete还挂在 Fetcher 类型对象上，开发者就无法用自己的自定义方法覆盖这些名字——名字冲突会直接导致自定义方法不可用或行为歧义。移除内建辅助方法后：

• Durable Object 可以通过 RPC（如 Cap'n Proto 支撑的 E-order 语义调用）自由定义名为get、put、delete的业务方法；
• Service Bindings 场景下的 Worker 接口设计也不再受限于这三个保留字。

从源码结构看，DurableObjectStub在仓库文档中被描述为"用于在远端 Durable Object 上调用 RPC 方法的客户端"，其类型是泛型的，允许在 stub 上调用 RPC 方法（stub.mdx）。这也印证了未来自定义方法将主要通过泛型 stub 的 RPC 机制承载，而非旧的薄封装辅助方法。

影响范围与迁移建议

谁可能受影响

• 几乎不受影响：由于这些方法从未被官方文档化，绝大多数现有 Worker 并没有使用它们。这也是 Cloudflare 敢于直接在2024-03-26兼容日期下默认移除的原因。
• 可能受影响：极少数基于早期运行时行为、自行依赖这三个辅助方法的内部代码或第三方库。这类代码在兼容日期提升后会抛出TypeError（方法不存在）。

迁移路径

1. 搜索代码中所有对 Durable Object stub 或 Service Binding 对象调用.get(/.put(/.delete(的地方；
2. 将其改写为显式的fetch()调用并指定 HTTP 方法，例如stub.fetch(request, { method: "PUT", body })；
3. 若短期无法完成迁移，可在compatibility_flags中加入fetcher_has_get_put_delete临时保留旧行为，但应尽快排期移除，避免长期依赖未文档化 API。

总结

fetcher_no_get_put_delete是 Cloudflare Workers 兼容性机制"渐进式移除历史遗留 API"的一个典型示例：通过enable_date = 2024-03-26与配套的disable_flag，Cloudflare 在保证旧 Worker 不受影响的前提下，为开发者释放了get/put/delete三个方法名，使其未来可以定义自己的同名自定义方法。理解这套"正向标志 + 反向标志 + 兼容日期"的组合配置，是管理 Workers 运行时演进、避免隐式行为变更的关键能力。

进一步参考：本标志的原始定义见 fetcher-no-get-put-delete.md；完整的兼容性机制说明见 compatibility-dates.mdx 与 compatibility-flags.mdx；相关 API 对象定义见 stub.mdx 与 service-bindings/http.mdx。

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs