react-router 设计决策解析：为什么不应该克隆请求对象（decisions/0002-do-not-clone-request）

本文围绕 React Router 仓库中一份已接受（accepted）的架构决策记录（ADR）展开：为何框架在向用户代码（action、数据/文档请求处理器）转发 Request 时不应调用 clone()，以及为何 loader 收到的请求永远不应该携带 body。读完本文，你能理解 HTTP 请求体"一次性消费"的平台语义、该决策对 loader/action 行为的实际约束，并能在需要重复读取 body 的场景下正确评估 .clone() 的取舍。

决策背景：请求 body 是一次性流

Request 对象的 body 在 Web 平台（fetch 规范）层面是一条只能被消费一次的流。React Router 在把请求转发给用户代码时，如果先对请求执行 request.clone()，会引发两个问题，这也是决策文档 decisions/0002-do-not-clone-request.md 中 Context 部分阐述的核心矛盾：

1. 运行时被迫缓冲 body。为了让 clone 出来的副本还能独立读取，部分运行时（Node.js 的不同版本、浏览器、边缘运行时等）必须先把 body 完整缓冲下来再分发给多个消费者。这意味着内存占用与响应延迟的隐性成本，且行为因运行时而异，难以统一保证。
2. 违背"平台"语义。平台明确约定请求体只应被消费一次。框架层偷偷复制请求，实际上是把"多次消费"这一平台层面被禁止的模式扩散给了所有用户代码。

该决策记录于 2022-05-13，状态为 accepted，遵循仓库 decisions/template.md 定义的 Context / Decision / Consequences 三段式 ADR 格式。

决策内容：不克隆，且把 loader 视作 GET/HEAD 处理器

决策本身包含两条相互关联的规则：

• 在向用户代码传递前，不克隆请求。这里的"用户代码"在文档中列举为 actions、handleDocumentRequest、handleDataRequest（注意：后两者是 Remix V2 时期的术语，对应当前框架模式下的服务端渲染入口，如 entry.server）。
• 传给 loader 的请求必须剥离 body。决策要求把 loader 理解为 "GET / HEAD" 请求处理器——而 HTTP 规范中这两种请求方法不允许携带 body。因此，你不应该在 loader 函数里读取 request.body。

这两条规则的共同思想是：与其让框架用 clone 掩盖"多次消费 body"的反模式，不如从 API 设计上把责任划清楚——写操作（POST，带 body）归 action，读操作（GET/HEAD，无 body）归 loader。

后果与影响：loader 永远拿到 null body

文档 Consequences 部分给出了两条明确的运行结果，值得逐条理解：

1. loader 收到的请求 body 恒为 null。这是框架保证的行为，而不是"当前恰好如此"。任何依赖在 loader 里 await request.text() / request.formData() 的代码都建立在错误假设之上。
2. 在 action 和文档/数据请求处理器中同时读取同一请求的 body，会失败。因为 body 是流，第一个消费者读走之后，第二个消费者会拿到已消费的流。如果你确实需要在一个请求的多个位置读取 body（文档明确说这是"反建议"的用法），可以考虑在读取前自己调用 .clone()——但要清楚这会把前面讨论的缓冲开销重新引入你的应用，这是明确的 tradeoff 而非免费能力。

当前源码中的落地验证

虽然 ADR 写于 2022 年，其约束在仓库当前源码中依然可以被直接验证。

1. action 执行后，路由层为 loader 重建了一个不带 body 的 GET 请求

在核心路由实现 packages/react-router/lib/router/router.ts 中，action 处理完成后，后续需要执行 loader 时，代码显式注释并构造了新的请求：

// Create a GET request for the loaders
let loaderRequest = new Request(request.url, {
  headers: request.headers,
  redirect: request.redirect,
  signal: request.signal,
});

注意 new Request(url) 不指定 method 时默认为 GET，且 init 中没有 body 字段——这正是"loader 收到 null body"决策在数据路由层的直接实现：loader 拿到的 loaderRequest 与原始带 body 的提交请求在 body 上彻底解耦。

2. RSC/服务端渲染路径同样重建无 body 请求

在 packages/react-router/lib/rsc/server.rsc.ts 中，用于触发 loader 再验证的请求同样被构造为纯 GET：

const getRevalidationRequest = () =>
  new Request(request.url, {
    method: "GET",
    headers: request.headers,
    signal: request.signal,
  });

同文件 packages/react-router/lib/rsc/server.rsc.ts 还展示了另一种"丢弃 body"的场景：当检测到潜在的 CSRF 攻击时，框架会把请求重建为一个不带 body 的 GET 请求，使提交失效——这与"body 只应被消费一次、且消费位置必须受控"的思路一脉相承。

3. .clone() 作为逃生舱口的实际用法

ADR 建议"确需多处读取时自己 .clone()"，而这一建议在 RSC 层就有真实用例。packages/react-router/lib/rsc/server.rsc.ts 在处理表单请求时需要读取两次 body（一次用于检测 $ACTION_* 键、一次用于实际解析），因此先克隆再消费：

} else if (isFormRequest) {
  const formData = await request.clone().formData();

从源码结构看，这里正是文档所说"如果你要坚持多处读取，自己负责 clone 并承担 tradeoff"的官方示范：框架核心路径不 clone，只在确有必要且可控的位置自行克隆。

开发者实操要点

结合本 ADR 与当前源码，可以整理出以下实践规则：

场景	正确做法	依据
在 loader 中取数据	依赖 URL、params、request.headers 等，不要读 body	ADR Consequences：loader body 恒为 null
在 action 中处理表单	await request.formData() 或按 Content-Type 解析 body，且只消费一次	fetch 平台语义
同一请求需要在多处读 body	在首次读取前 request.clone()，并接受缓冲开销	ADR Consequences 第 2 条
表单提交后触发 loader 再验证	由框架自动重建 GET 请求，无需也不应手动传递 body	router.ts

action 中读取 body 的标准用法在官方 API 的文档注释中也能看到，例如 packages/react-router/lib/hooks.tsx 中 useActionData 附带的示例：

export async function action({ request }) {
  const body = await request.formData();
  const name = body.get("visitorsName");
  // ...
}

适用前提与小结

需要说明的适用边界：本 ADR 中列举的 handleDocumentRequest / handleDataRequest 属于 Remix V2 时代的服务端处理器命名，当前仓库的服务端渲染入口已演进为 framework mode 的 entry.server.tsx 等形态，但"不克隆、loader 无 body、body 单次消费"这三条核心约束在数据路由（createBrowserRouter 等）与服务端渲染路径中均被保留并可通过上文源码位置验证。

一言以蔽之：React Router 选择站在"平台"一侧——请求 body 是只读一次的资源，框架不帮你 clone，也不允许 loader 假装自己是 POST 处理器；确有需要时，.clone() 的代价由调用者显式承担。 这一决策让请求生命周期在不同运行时上保持一致、可预测，是理解 React Router 数据加载模型（loader 读、action 写）的一条底层设计原则。