t3code 基于 Effect 的 Alchemy 2.0.0-beta.61 解读：Workers Cache、Zone Routes 与状态同步

t3code 基于 Effect 的 Alchemy 2.0.0-beta.61 解读Workers Cache、Zone Routes 与状态同步【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本指南以开源仓库 alchemy-effect 的 v2.0.0-beta.61 版本说明为骨架逐项剖析该版本引入的 Workers Cache 与 Effect 原生ExecutionContext、Wrangler 风格 Zone Routes、alchemy sync状态收敛、完整 Workflows API、资源类型别名等能力并结合 alchemy-effect 源码 印证其底层实现与调用链帮助你掌握这套 Effect 原生基础设施即代码框架的版本演进与迁移要点。版本概览与破坏性变更beta.61 是一个以可靠性修复为主、能力扩充为辅的版本Workers Cache 以绑定和 prop 双重形态落地、WorkerExecutionContext升级为 Effect 包装、Zone Routes 支持 Wrangler 风格配置、alchemy sync可修复云端漂移、Workflows API 补全重试/回滚/事件、资源类型别名修复 beta.59 重命名遗留问题。升级前需注意以下三处破坏性变更workflow.create改用原生 options 对象create(input)变为create({ params: input })同时解锁id与retention配置对应 PR #611。WorkerExecutionContext变为 Effect 包装不再直接暴露原始cf.ExecutionContextwaitUntil接收Effect并需yield*使用对应 PR #752。最低要求 effect4.0.0-beta.93effect 将UrlParams.makeUrl迁移至Url.makepeer 依赖下限随之抬高对应 PR #748。Workers Cache绑定与 prop 双形态落地Workers Cache 是 Cloudflare 置于 Worker 入口前的区域性分层缓存。本版本中它同时以绑定binding与prop两种形态出现对应 PR #752。Effect 原生 Worker 的Cloudflare.cache()Effect 原生的 Worker 通过Cloudflare.cache()启用 Workers Cache该调用同时返回带类型的 purge 客户端Effect.gen(function* () { // init: enables Workers Cache on this Worker at deploy time const { purge } yield* Cloudflare.cache({ crossVersionCache: true }); return { fetch: Effect.gen(function* () { const request yield* HttpServerRequest; if (request.url.startsWith(/invalidate)) { yield* purge({ tags: [products] }); // typed CachePurgeError return HttpServerResponse.text(purged); } return HttpServerResponse.text(hello, { headers: { Cache-Control: public, max-age300, stale-while-revalidate3600, Cache-Tag: products, }, }); }), }; })从源码看Cache.ts 中cache()的实现逻辑是在 init 阶段通过Worker宿主向 Namespace 推送一个cache: { enabled, crossVersionCache }绑定从而在部署时开启缓存返回的CacheClient.purge则委托给 init 阶段延迟解析的exec.cache.purge在请求处理器中解析为真实逐事件上下文。CacheOptions支持两个选项enabled是否在调用 Worker 前检查缓存默认truecrossVersionCache是否跨 Worker 版本共享缓存响应默认false缓存默认按单版本隔离每次部署都会冷启动。Async Worker 的 prop 形态非 Effect 的 Async Worker 使用 prop 形态配置项一致const worker yield* Cloudflare.Worker(Api, { main: ./src/api.ts, cache: { enabled: true, crossVersionCache: true }, });缓存命中与否由标准响应头控制Cache-Control含stale-while-revalidate控制有效期、Cache-Tag支持按标签 purge、Vary用于内容协商——这与 Cache.ts 中的注释描述完全一致。Effect 原生ExecutionContext旧版WorkerExecutionContext直接把原始cf.ExecutionContext交给你现在它是 Effect 包装——与DurableObjectState类似可以从 Worker 的init 闭包或任意 Layer中yield*其方法会解析到真实的逐事件上下文Effect.gen(function* () { const exec yield* Cloudflare.WorkerExecutionContext; // init return { fetch: Effect.gen(function* () { // respond now, finish work in the background yield* exec.waitUntil(journal.record(entry).pipe(Effect.delay(5 seconds))); return HttpServerResponse.text(ok); }), }; })迁移是机械性的ctx.waitUntil(promise)变为yield* exec.waitUntil(effect)。对应实现位于 Worker.tsWorkerExecutionContext是基于 EffectContext.Service的服务提供deferredExecutionContext延迟解析与liveExecutionContext实时解析两种形态init 阶段可访问而raw仅在请求处理器内可用。Workers 上的 Zone RoutesCloudflare.Worker通过新增的routesprop 支持 Wrangler 风格的 zone 路由对应 PR #438由社区贡献者 utopy 提供yield* Cloudflare.Worker(Api, { main: import.meta.filename, routes: [ { pattern: api.example.com/*, zoneName: example.com }, { pattern: example.com/api/*, zoneId: YOUR_ZONE_ID }, ], });每条路由项接受zoneName/zoneId对应 Wrangler 的等价物或zone引用省略 zone 时从 pattern 的 hostname 自动推断。路由在部署时进行 reconcile、销毁时清理。alchemy sync修复云端状态漂移云状态会漂移有人在 dashboard 里改了一个资源、某个 bucket 被删除、标签被改乱。alchemy sync在不重新运行 stack 程序的前提下将云端收敛回最后一次部署的状态对应 PR #766alchemy sync ./alchemy.run.ts --stage prod # detect repair alchemy sync ./alchemy.run.ts --stage prod --dry-run # detect only对每个资源它执行 observe → compare → converge 三步read观察真实云状态与持久化属性做深度比较判定unchanged或 drifted漂移则用持久化 props 作为期望状态交由reconcile修复。从 CLI 注册逻辑看syncCommand与deploy共享边界处的新鲜状态存储见 Cli/main.ts确保收敛基于最近部署的期望状态。关键行为被外部删除的资源按同一 instance id 重建因此确定性物理名会以完全相同的方式重新生成资源并发同步全部尝试完成后才聚合失败结果。Workflows重试、回滚与事件Effect 原生 Workflow 包装现在完整覆盖 Workers API 面与原生 binding 1:1 对应对应 PR #611由 Gerben Mulder 贡献。create的原生 options 对象create接收原生 options 对象——即上文提到的破坏性变更——同时解锁id和retention- const instance yield* workflow.create({ orderId: abc }); const instance yield* workflow.create({ id: order-abc, params: { orderId: abc }, retention: { successRetention: 1 day, errorRetention: 7 days }, });task的重试与回滚task新增 retries、timeout 和 rollbackWorkflowStepContext暴露当前尝试次数const result yield* Cloudflare.Workflows.task( call-api, Effect.gen(function* () { const context yield* Cloudflare.Workflows.WorkflowStepContext; return { attempt: context.attempt }; }), { retries: { limit: 3, delay: 5 seconds, backoff: linear }, rollback: ({ output }) (output ? cleanup(output.id) : Effect.void), }, );waitForEvent事件等待waitForEvent将实例挂起直到匹配的sendEvent到达// inside the workflow const approval yield* Cloudflare.Workflows.waitForEvent{ approved: boolean }( approval, { type: approval, timeout: 1 day }, ); // from outside yield* instance.sendEvent({ type: approval, payload: { approved: true } });这些 API 与原生step.waitForEvent一一对应见 Workflow.ts。createBatch、restart、rollback 状态与扩展的事件元数据补齐了整个 API 面详见 Workflows 文档。资源类型别名修复 beta.59 重命名重命名资源的类型字符串曾会让旧名下持久化的状态孤立——provider 查找在旧类型上失败。现在资源可以声明旧名称对应 PR #765export const Queue ResourceQueue(Cloudflare.Queues.Queue, { aliases: [Cloudflare.Queue], });从 Resource.ts 看ResourceOptions.aliases作为字符串数组保存旧类型名并复制到资源的Aliases元数据中。plan、apply、destroy、logs、tail全部通过别名解析 provider一次 noop deploy 会将状态行迁移到规范名称。beta.59 命名空间对齐中改名的全部74 个资源都标注了改名前的别名——因此 beta.58 及更早版本写入的状态现在可以干净地 deploy、destroy、replace而不再在旧类型上报错。AI Gateway BYOKAI.ProviderKeyAI Gateway 上的自带密钥BYOKprovider 需要两个协调资源——Secrets Store 中名称严格为{gatewayId}_{providerSlug}_{alias}的Secret以及引用它的GatewayProvider。Cloudflare.AI.ProviderKey将这一契约封装为单个资源对应 PR #586由 Alex 贡献const { secret, gatewayProvider } yield* Cloudflare.AI.ProviderKey(OpenAiKey, { store, gatewayId: gateway.gatewayId, providerSlug: openai, value: yield* Config.redacted(OPENAI_API_KEY), });value通过Config.redacted从环境读取敏感密钥避免明文写入 stack 程序。详见 AI Gateway 文档。Lambda 异步调用配置Lambda 的异步调用设置——重试、事件年龄、成功/失败目标——以eventInvokeConfigprop 落在Function和Alias上对应 PR #627由 José Netto 贡献const fn yield* AWS.Lambda.Function(AsyncFn, { main: ./src/handler.ts, eventInvokeConfig: { maximumRetryAttempts: 0, maximumEventAgeInSeconds: 60, destinationConfig: { OnFailure: { Destination: queue.queueArn }, }, }, });源码中eventInvokeConfig在 Function.ts 与 Alias.ts 均有声明且支持通过AliasProps.eventInvokeConfig将配置限定到特定 alias配置详情见 EventInvokeConfig.ts。R2 Bucket 的cors恢复v1 中Cloudflare.R2.Bucket就有的corsprop 在本版本恢复对应 PR #771)——面向浏览器 range-read如 PMTiles的公开 bucket 可以在 stack 中声明 CORS而不再需要带外配置const bucket yield* Cloudflare.R2.Bucket(Tiles, { domains: [{ name: tiles.example.com }], cors: [ { allowedMethods: [GET, HEAD], allowedOrigins: [https://map.example.com], allowedHeaders: [range], exposeHeaders: [etag, content-range], maxAgeSeconds: 3600, }, ], });规则使用扁平的 S3 风格 shape并像lifecycleRules一样做 observed vs desired 的 reconcile——带外漂移与既有资源采纳都能正确收敛。可靠性修复清单本版本还包含一批面向可靠性的修复Also in this releaseWorker 元数据变更现在真正部署#747compatibility flags/date、observability、placement、limits、binding 变更通过元数据哈希并入更新 diff此前它们会被计划为 noop 而静默不发布。升级后首次部署会对每个 Worker 做一次性更新以回填哈希。由 Alex 贡献。Wedged stacks 可恢复#767、#770部署在 create 中途被打断曾导致持久化一行 Output 值属性无法往返的状态使后续每次plan/deploy/destroy崩溃。现在审计了每个 provider 的read/diff引擎会重新驱动 createreconcile 收敛到半创建的资源上。脚本上传对每个 binding-target-not-found 错误重试#753覆盖 KV、R2、D1、Queues、DO classes、Hyperdrive、Vectorize 等应对 Cloudflare 部署期的传播延迟。Resource.ref值在 Workerenv中原生绑定#756作为 env 绑定传入的 ref 此前会退化为纯 JSON 环境变量并在运行时出错现在 ref 与本地声明的资源精确同等地分类。单个 Worker 支持多个队列消费者#466事件分发对每个事件类型运行全部 listener不再让第一个队列订阅吞掉其余。由 Leonardo E. Dominguez 贡献。状态存储错误信息可操作#737梳理了 30 天的生产 traces空StateStoreError:消息、不透明的 decode 错误、JSON 解析崩溃现在会暴露真实消息未授权 store 会提示运行alchemy login。测试套件通过 Windows#735包含两个真实产品修复——Drizzle.Schema曾把 OS 原生路径传给 drizzle-kit反斜杠是 glob 转义符Bundle.PurePlugin可能被node_modules之上的散落package.json劫持。Drizzle 查询链是真正的 Effect#750db.select()...链现在暴露完整 Effect 协议可与Effect.all等组合而不再自旋 run loop。PlanetScale 继承角色按成员资格比较#761API 返回顺序不再强制PostgresRole替换。由 Gerben Mulder 贡献。globalOutbound: null在WorkerLoader中被保留#746文档化的阻止所有出站网络访问信号不再被静默强制转为默认访问。由 Alex 贡献。Binding 托管的 DO classes 加入 precreate stub#764修复 worker↔container 循环的首次部署上Worker did not expose Durable Object namespace。由 Daniel Gangl 贡献。alchemy dev不再打印 bun 的良性 tsconfig fd 警告#768。后续阅读WorkflowsWorkersCustom Domains RoutesAI Gateway完整变更记录见仓库 CHANGELOG.mdv2.0.0-beta.61条目【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考