workerd 高级 .wd-test 配置实战Durable Objects、多服务、网络访问与 TypeScript 测试【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd.wd-test是 workerdCloudflare Workers 的 JavaScript/Wasm 运行时测试框架使用的 Capn Proto 配置文件格式用于声明测试 Worker 及其依赖的服务、存储与网络环境。本文基于仓库中 advanced-configs.md 的完整内容结合 workerd.capnp 的底层 schema 定义与 BUILD.bazel 的真实测试规则系统讲解 Durable Objects、多服务通信、出站网络访问、外部服务对接与 TypeScript 测试这五类进阶配置模式。读完本文你将能独立编写覆盖 DO 状态持久化、服务间 fetch 调用、socket/RPC 通信等复杂场景的.wd-test测试配置并理解每项配置在运行时的真实语义。一、.wd-test进阶配置概览基础单服务测试只需要一个services列表、一个模块入口和若干compatibilityFlags而进阶场景通常需要回答四类问题场景需要的配置要素对应 schema 类型测试 Durable ObjectsdurableObjectNamespacesdurableObjectStorage 绑定DurableObjectNamespaceworkerd.capnp多服务互相调用多个services条目 service bindingService/ServiceDesignatorworkerd.capnp测试 Worker 发起出站请求network服务 allow规则Networkworkerd.capnp对接 socket / 外部服务external服务条目ExternalServerworkerd.capnp用 TypeScript 编写测试.ts-wd-test配置文件构建系统自动编译这些能力全部由 workerd.capnp 中的Workerd.Configschema 驱动services是命名的服务列表每个服务可以是 Worker、network、external或disk四种形态之一见 Service 联合体定义名称仅供本配置文件内部引用除非显式配置绑定否则服务之间互不可见。二、Durable Objects 测试配置2.1 基础配置namespace、storage 与绑定测试 Durable Objects 时需要在 Worker 中定义 namespace 与存储并配一个磁盘服务作为 DO 数据的落盘位置const unitTests :Workerd.Config ( services [ ( name do-test, worker ( modules [(name worker, esModule embed do-test.js)], compatibilityDate 2024-01-01, durableObjectNamespaces [ (className MyDurableObject, uniqueKey 210bd0cbd803ef7883a1ee9d86cce06e), ], durableObjectStorage (localDisk TEST_TMPDIR), bindings [ (name MY_DO, durableObjectNamespace MyDurableObject), ], ), ), # Disk service for DO storage (name TEST_TMPDIR, disk (writable true)), ], );配置要点拆解className实现 Durable Object 的导出类名必须与 JS 模块中的export class MyDurableObject一致。uniqueKey唯一标识 namespace 的十六进制字符串。schema 注释明确说明该字符串用于确保该类对象的标识符与其他一切地方都不冲突workerd.capnp同时指出只要uniqueKey保持不变修改类名不会破坏与既有存储的兼容性。测试场景下使用任意 32 字符十六进制串即可关键是保证不同测试之间不重复。durableObjectStorageDO 状态存储位置。(localDisk TEST_TMPDIR)表示状态持久化到磁盘TEST_TMPDIR必须是一个disk类型服务名。绑定bindings中的(name MY_DO, durableObjectNamespace MyDurableObject)让测试代码通过env.MY_DO拿到 namespace 并get()具体对象。2.2 localDisk 与 inMemory两种存储语义如果测试不需要跨请求持久化可以用内存存储替代磁盘durableObjectStorage (inMemory void),两种模式在 workerd.capnp 中有明确语义inMemorystate.storageAPI 只存在内存中数据在整个进程生命周期内有效进程退出即丢失单个对象空闲时仍会正常关闭只有通过state.storage接口写入的数据才随进程存活。schema 注释明确标注此模式面向本地测试目的。localDiskDO 数据存储于本地磁盘目录字段值是一个DiskDirectory服务名。对每个 DO 类会以uniqueKey为名创建子目录对象数据以id.ext命名存放目前主存储文件后缀为.sqlite特定情况下还会出现.sqlite-wal与.sqlite-shm文件对应 SQLite 的 WAL 机制。该字段被标注为EXPERIMENTAL可能发生不兼容变更。据此可以总结选型建议单测追求隔离性与速度选inMemory需要验证数据持久化、重启恢复等行为时选localDisk。另外注意 workerd.capnp 中的 TODO 注释目前对象始终运行在单实例运行时上尚不支持跨集群分布。2.3 磁盘服务DiskDirectory说明(name TEST_TMPDIR, disk (writable true))中的disk形态对应DiskDirectoryworkerd.capnp它把磁盘目录暴露为 HTTP 服务支持基础的 GET/PUT但 schema 注释强调它非常简陋不猜测Content-Type对目录的 GET 会返回 JSAN 格式的目录列表通常不适合直接对外服务一般要再包一层 Worker 补充元数据。在测试配置中它的职责就是给 DO 的localDisk存储提供一个可写目录。三、多服务配置通过 service binding 联调3.1 多服务互相调用测试中经常需要模拟主 Worker 调用后端的拓扑此时只需在services中并列声明多个 Worker 服务并在主 Worker 上用 service binding 指过去const unitTests :Workerd.Config ( services [ ( name main-test, worker ( modules [(name worker, esModule embed main-test.js)], compatibilityDate 2024-01-01, bindings [ (name BACKEND, service backend), ], ), ), ( name backend, worker ( modules [(name worker, esModule embed backend.js)], compatibilityDate 2024-01-01, ), ), ], );测试 JS 中即可通过env.BACKEND.fetch(http://example.com/)触发对backend服务的调用URL 的 host 在 service binding 场景下只作为占位符请求总是路由到绑定指向的服务。这正是 SKILL.md 中 bindings 章节所述Service binding — env.OTHER_SERVICE is a fetch-able service的落地形态。service binding 还支持指定 entrypoint例如(name MY_RPC, service (name my-service, entrypoint MyClass))用于访问另一个服务中特定导出类的 RPC 接口——这在 Durable Objects 与多服务 RPC 联测中很常见。3.2 大型配置用命名常量因子化 Worker当配置变得庞大时可以把每个 Worker 定义抽成顶层命名常量services中只留一行引用避免层层嵌套难以维护const unitTests :Workerd.Config ( services [ (name main, worker .mainWorker), (name helper, worker .helperWorker), ], ); const mainWorker :Workerd.Worker ( modules [(name worker, esModule embed main.js)], compatibilityDate 2024-01-01, bindings [(name HELPER, service helper)], ); const helperWorker :Workerd.Worker ( modules [(name worker, esModule embed helper.js)], compatibilityDate 2024-01-01, );worker .mainWorker中的前导点号是 Capn Proto 的顶层作用域引用语法指向同文件内定义的const mainWorker。这种写法让每个 Worker 的模块、兼容性与绑定一目了然也便于多个测试常量复用同一份 Worker 定义。四、出站网络访问Network 服务4.1 基础配置需要测试 Worker 发起真实出站请求时声明一个network类型的服务并在 Worker 中通过 service binding 或全局出站配置引用它( name internet, network ( allow [private], tlsOptions ( trustedCertificates [ embed test-cert.pem, ], ), ) ),allow可取[private]回环 / 局域网或[public]公网绝大多数测试使用private。4.2 allow/deny 的底层语义workerd.capnp 对Network给出了精确的访问控制语义这是理解配置行为的关键allow与deny都是 CIDR 记法IPv4 与 IPv6 皆可的列表如192.0.2.0/24、2001:db8::/32流量放行的条件是地址命中 allow 列表至少一项且不命中 deny 列表任何一项。除 CIDR 外还支持四个特殊字符串private匹配标准保留的私网地址如10.0.0.0/8、192.168.0.0/16是local的超集publicprivate的反面local匹配仅本机可访问的地址如127.0.0.0/8或 Unix 域套接字networklocal的反面。allow的默认值是[public]默认只允许访问公网可路由地址正是为了防止 SSRF。schema 注释建议优先使用ExternalServer绑定来精确放行特定后端而不是放开整段内网。因此allow [private]意味着测试 Worker 的fetch()可以打到本机回环与局域网服务例如测试期间由测试 harness 在本地启动的 mock 服务。4.3 TLS 信任配置tlsOptions.trustedCertificates用embed内嵌 PEM 证书使 Worker 在发起 TLS 连接时信任测试用自签名证书——适用于测试 HTTPS 后端。embed与modules中内嵌文件语义一致构建期把文件内容直接写入配置。五、外部服务socket 与 RPC 通信对于基于 socket 的 RPC 或与外部服务通信的测试使用external形态的服务( name my-external, external ( address loopback:my-external, http (capnpConnectHost cappy) ) ),ExternalServer在 workerd.capnp 中的语义是把来自绑定的所有fetch()请求无条件转发到指定服务器无论 URL 中的 hostname 或协议是否与真实服务器匹配——这正是反向代理的典型用法后端通常没有真实公网主机名只能通过代理访问且转发后请求保留原始 host。address loopback:my-external使用loopback:前缀指定一个本地 Unix 域套接字地址http.capnpConnectHost则用于配置 Capn Proto RPC 连接时的目标 host 名例如cappy从而在测试中模拟经 socket 通信的 RPC 服务。此类配置常与 sample 目录中的 RPC 示例如 samples/extensions 的 binding/RPC 模式配合理解。六、TypeScript 测试.ts-wd-test6.1 配置与构建规则TypeScript 测试的配置文件使用.ts-wd-test扩展名但embed的模块必须是编译后的.js产物配置文件my-test.ts-wd-testusing Workerd import /workerd/workerd.capnp; const unitTests :Workerd.Config ( services [( name my-test, worker ( modules [(name worker, esModule embed my-test.js)], compatibilityDate 2024-01-01, ), )], );BUILD.bazel 中引用.ts源文件wd_test( src my-test.ts-wd-test, args [--experimental], data [my-test.ts], )构建系统会把data中的.ts源码自动编译为.js供配置文件中embed my-test.js使用。仓库内 src/workerd/api/tests/BUILD.bazel 是.ts-wd-test的实际使用处可作为参考。6.2 与普通.wd-test的差异维度普通测试TypeScript 测试配置扩展名my-test.wd-testmy-test.ts-wd-testsrc指向.wd-test配置文件.ts-wd-test配置文件data内容.js测试文件与 fixture.ts源文件构建期自动编译embed 的模块my-test.js编译产物my-test.js仍写.js无论哪种形式测试 JS/TS 的结构一致每个具名导出对象含test()方法即是一个用例异步用例的签名是async test(ctrl, env)其中env携带.wd-test配置中的所有 bindings详见 SKILL.md。七、把进阶配置跑起来BUILD.bazel 与运行命令7.1 标准 wd_test 规则形态仓库中真实测试规则的典型写法见 src/workerd/api/tests/BUILD.bazelwd_test( src stdio-writesync-reentry-uaf-test.wd-test, args [--experimental], data [stdio-writesync-reentry-uaf-test.js], )src.wd-test或.ts-wd-test配置文件args [--experimental]启用实验特性所必需data测试 JS/TS 文件与 fixture如fixtures/cert.pem、fixtures/key.pem。7.2 三种自动生成的测试变体每个wd_test()会自动生成三个变体见 SKILL.md分别覆盖不同的兼容性配置目标后缀兼容日期说明2000-01-01默认变体使用最老的兼容日期all-compat-flags2999-12-31启用全部兼容标志all-autogates2000-01-01启用全部自动门控运行特定变体just stream-test //src/workerd/api/tests:my-test just stream-test //src/workerd/api/tests:my-testall-compat-flags编写包含 Durable Objects 或多服务的进阶配置时建议至少把all-compat-flags变体跑一遍验证配置在各兼容标志组合下均不失效。7.3 脚手架命令just new-test可以自动生成新测试的三件套——.wd-test配置、.js测试文件并把wd_test()规则追加到对应BUILD.bazeljust new-test //src/workerd/api/tests:my-test生成后再按本文的进阶模式补充 DO、多服务、网络等配置即可。八、进阶配置速查与自检清单编写高级.wd-test配置时建议逐项自检Durable ObjectsuniqueKey是否为全局唯一的 32 字符十六进制串存储选择inMemory进程内、易失还是localDisk落盘 SQLite、需配套disk服务绑定名是否与 JS 中env.MY_DO一致多服务所有services条目是否有唯一nameservice binding 指向的服务名是否拼写一致大配置是否已用顶层const常量因子化网络访问allow是否收窄到测试所需的最小范围通常[private]是否误用了默认的[public]是否需要deny进一步收紧、是否需要tlsOptions.trustedCertificates信任自签证书外部服务external.address的 socket 地址与capnpConnectHost是否正确对应测试 harness 启动的 mock 服务TypeScript配置扩展名是否为.ts-wd-testembed是否指向编译产物.jsBUILD.bazel的data是否列出了.ts源文件运行wd_test()是否带args [--experimental]三个自动变体、all-compat-flags、all-autogates是否都通过掌握上述模式后你便可以在 workerd 仓库中编写覆盖 Durable Objects 持久化、服务间 RPC、真实出站请求与 TypeScript 场景的高质量测试——其背后每一处语义存储模式、SSRF 防护、请求转发规则都能在 workerd.capnp 中找到对应注释作为依据。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考