Rust

Cloudflare Workers 通过 workers-rs crate ↗ 提供 Rust 支持，该 crate 使运行时 API 以及到开发者平台产品（如 Workers KV、R2 和 Queues）的绑定（binding）可直接从你的 Rust 代码中使用。

按照本指南，你将学习如何完全使用 Rust 编程语言构建 Worker。

在开始本指南之前，请确保你拥有：

• 最新版本的 Rust ↗
• npm ↗
• Rust wasm32-unknown-unknown 工具链：

rustup target add wasm32-unknown-unknown

• 以及通过运行以下命令安装 cargo-generate 子命令：

cargo install cargo-generate

打开终端窗口，运行以下命令以生成 Rust Worker 项目模板：

cargo generate cloudflare/workers-rs

你的项目将在你命名的目录中创建，其中包含以下文件和文件夹：

• Cargo.toml - Rust Cargo ↗ 包管理器的标准项目配置文件。模板预填充了在 Workers 上构建 Wasm 的最佳实践设置。
• wrangler.toml - Wrangler 配置，预填充了调用 worker-build 的自定义构建命令（请参阅 Wrangler 打包）。
• src - Rust 源代码目录，预填充了 Hello World Worker。

创建第一个 Worker 后，运行 wrangler dev 命令以启动用于开发 Worker 的本地服务器。这将允许你在开发中测试 Worker。

npx wrangler dev

如果你以前没有使用过 Wrangler，它将尝试打开 Web 浏览器以使用 Cloudflare 账户登录。

访问 http://localhost:8787 ↗ 查看正在运行的 Worker。对代码的任何更改都会触发重新构建，刷新页面将显示 Worker 的最新输出。

生成新项目后，编写 Worker 代码。在 src/lib.rs 中找到 Worker 的入口点：

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    Response::ok("Hello, World!")
}

workers-rs 提供了与 Worker 的 JavaScript API 紧密匹配的运行时 API，并支持与 Worker 平台功能的集成。有关 API 的详细文档，请参阅 docs.rs/worker ↗。

此宏允许你定义 Worker 的入口点。event 宏支持以下事件：

• fetch - 由传入的 HTTP 请求调用。
• scheduled - 由 Cron Triggers 调用。
• queue - 由来自 Queues 的传入消息批次调用（需要在 Cargo.toml 中启用 queue 功能，请参阅 workers-rs GitHub 仓库和 queues 功能标志 ↗）。
• start - 在 Worker 首次启动时调用（例如，安装 panic hooks）。

fetch 处理程序提供三个与 JavaScript API 匹配的参数：

1. Request ↗

表示传入请求的对象。这包括访问 headers、method、path、Cloudflare 属性和 body 的方法（支持使用 Serde ↗ 进行异步流式传输和 JSON 反序列化）。

2. Env ↗

提供对 Worker 绑定（binding）的访问。

• Secret ↗ - 在 Cloudflare 仪表板中配置或使用 wrangler secret put 设置的密钥值。
• Var ↗ - 在 wrangler.toml 中定义的环境变量。
• KvStore ↗ - Workers KV 命名空间绑定。
• ObjectNamespace ↗ - Durable Objects 绑定。
• Fetcher ↗ - 到另一个 Worker 的服务绑定（Service binding）。
• Bucket ↗ - R2 Bucket 绑定。
• D1Database ↗ - D1 数据库绑定。
• Queue ↗ - Queues 生产者绑定。
• Ai ↗ - Workers AI 绑定。
• Hyperdrive ↗ - Hyperdrive 绑定。
• AnalyticsEngineDataset ↗ - Analytics Engine 绑定。
• DynamicDispatcher ↗ - Dynamic Dispatch 绑定。
• SecretStore ↗ - Secrets Store 绑定。
• RateLimiter ↗ - Rate Limiting 绑定。

3. Context ↗

提供对 waitUntil（延迟异步任务）和 passThroughOnException（失败时放行）功能的访问。

fetch 处理程序期望 Response ↗ 返回类型，支持异步流式响应到客户端。这也是从 Worker 发出的任何子请求的返回类型。有访问状态码和 headers 的方法，以及异步流式传输 body 或使用 Serde ↗ 从 JSON 反序列化的方法。

实现便捷的路由 API ↗，从一个 Worker 提供多个路径。请参阅 worker-rs GitHub 仓库中的 Router 示例 ↗。

配置项目后，你现在可以将 Worker 部署到 *.workers.dev 子域，或自定义域（如果已配置）。如果你尚未配置任何子域或域，Wrangler 将在部署过程中提示你设置一个。

npx wrangler deploy

在 <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev 预览你的 Worker。

完成这些步骤后，你将部署一个基本的基于 Rust 的 Worker。从这里，你可以添加依赖项并编写 Rust 代码来实现 Worker 应用程序。如果你想了解更多关于 Workers 如何支持编译为 Wasm 的 Rust 的内部工作原理，下一节概述了涉及的库和工具。

使用 workers-rs 时，Wasm Workers 从自动为你创建的 JavaScript 入口脚本调用。

要访问平台功能（如绑定），Wasm Workers 必须能够访问 JavaScript 运行时 API 的方法。

这种互操作性通过 wasm-bindgen ↗ 实现，它提供了将运行时 API 导入 Wasm 模块以及从 Wasm 模块导出事件处理程序所需的粘合代码。wasm-bindgen 还提供 js-sys ↗，它实现了与 JavaScript 对象交互的类型。实际上，这是一个实现细节，因为 workers-rs 的 API 会为你处理与 JavaScript 对象的转换以及与导入的 JavaScript 运行时 API 的交互。

wasm-bindgen-futures ↗（wasm-bindgen 项目的一部分）提供 Rust Futures 和 JavaScript Promises 之间的互操作性。workers-rs 使用 spawn_local 调用整个事件处理函数，这意味着你可以使用 async Rust 编程，它被转换为单个 JavaScript Promise 并在 JavaScript 事件循环上运行。对导入的 JavaScript 运行时 API 的调用会自动转换为可以从 async Rust 函数调用的 Rust Futures。

要在 Workers 上运行生成的 Wasm 二进制文件，workers-rs 包含一个名为 worker-build ↗ 的构建工具，它：

1. 创建一个 JavaScript 入口脚本，使用 wasm-bindgen 的 JavaScript API 正确调用模块。
2. 调用 web-pack 来压缩和打包 JavaScript 代码。
3. 输出 Wrangler 可用于打包和部署最终 Worker 的目录结构。

worker-build 默认在模板项目中通过 wrangler.toml 文件中指定的自定义构建命令调用。

未优化的 Rust Wasm 二进制文件可能很大，可能超出 Worker 包大小限制或经历较长的启动时间。模板项目在 Cargo.toml 文件中预配置了几个有用的体积优化：

[profile.release]
lto = true
strip = true
codegen-units = 1

最后，worker-bundle 在上传前自动调用 wasm-opt ↗ 以进一步优化二进制大小。

• Rust Wasm Book ↗