我们聊聊从头学服务器组件：在导航间保留状态_程序开发

我们聊聊从头学服务器组件：在导航间保留状态

创始人

2025-07-07 19:11:36

0次

存在的问题

到目前为止，访问每个页面，服务器返回的都是一个 HTML 字符串：

async function sendHTML(res, jsx) {
  const html = await renderJSXToHTML(jsx);
  res.setHeader("Content-Type", "text/html");
  res.end(html);
}

这对浏览器首次加载是非常友好的——浏览器有针对 HTML 渲染做针对性优化，会尽可能快地展示——但对于页面导航就不太理想了。我们希望页面支持布局刷新，即只更新 "发生变化的部分"，页面其他部分不受影响，也让交互变得流畅了。

为了说明这个问题，我们向 BlogLayout 组件的

中添加一个：


  Home

请注意，每次浏览博客时，输入框里的内容（或叫“状态”）都会消失：

图片

这对一个简单的博客来说可能没有问题，但如果要构建具有复杂交互的应用程序，这种行为在某些时候就会让人头疼。因此，你需要让用户在应用程序中随意浏览时，不会丢失页面状态。

接下来，我们将分 3 步骤来解决这个问题：

添加一些客户端 JS 逻辑拦截导航，修改默认行为（这样我们就可以手动重新获取内容，而无需重新加载整个页面）
修改服务端代码，支持在随后的导航中需要提供返回 JSX 响应（而不是 HTML）的支持
修改客户端代码，在不破坏 DOM 的情况下执行 JSX 更新（提示：这部分将使用 React）

局部更新支持

步骤 1：拦截导航

我们需要一些客户端逻辑，因此增加一个 client.js 文件。先修改服务端代码（即 server.js），增加静态资源的路由请求支持（即"/client.js"）。

createServer(async (req, res) => {
  try {
    const url = new URL(req.url, `http://${req.headers.host}`);
    // 增加静态资源 "/client.js" 的路由支持
    if (url.pathname === "/client.js") {
      await sendScript(res, "./client.js"); // 返回服务端本地的 client.js 文件
    } else {
      await sendHTML(res, );
    }
  } catch (err) {
    // ...
  }
}).listen(8080)

async function sendScript(res, filename) {
  const content = await readFile(filename, "utf8");
  res.setHeader("Content-Type", "text/javascript");
  res.end(content);
}

另外，在 sendHTML() 中为响应的 HTML 文本增加 `; res.setHeader("Content-Type", "text/html"); res.end(html); }

现在说回 client.js。在这个文件中，我们会覆盖网站内导航的默认行为（译注：此处指标签链接能力），改调我们自己的 navigate() 函数：

async function navigate(pathname) {
  // TODO
}

window.addEventListener("click", (e) => {
  // 只处理  标签的点击事件
  if (e.target.tagName !== "A") {
    return;
  }
  // Ignore "open in a new tab".
  if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
    return;
  }
  // Ignore external URLs.
  const href = e.target.getAttribute("href");
  if (!href.startsWith("/")) {
    return;
  }
  // 这里是核心代码。首先，阻止  标签默认的跳转行为
  e.preventDefault();
  // 然后，将跳转地址推入浏览历史，浏览器地址栏的地址也同步更新
  window.history.pushState(null, null, href);
  // 最后，执行自定义的导航行为
  navigate(href);
}, true);

window.addEventListener("popstate", () => {
  // When the user presses Back/Forward, call our custom logic too.
  navigate(window.location.pathname);
});

navigate() 函数就是编写自定义导航行为的地方。在 navigate() 函数中，我们使用 fetch API 请求下一个路由的 HTML 响应，并使用这个响应更新页面：

let currentPathname = window.location.pathname;

async function navigate(pathname) {
  currentPathname = pathname;
  // 获取当前导航路由下的 HTML 数据
  const response = await fetch(pathname);
  const html = await response.text();

  if (pathname === currentPathname) {
    // 获取 HTML 响应数据  标签里的内容
    const bodyStartIndex = html.indexOf("") + "".length;
    const bodyEndIndex = html.lastIndexOf("");
    const bodyHTML = html.slice(bodyStartIndex, bodyEndIndex);

    // 将拿到的 HTML 数据替换掉当前  里的内容
    document.body.innerHTML = bodyHTML;
  }
}

点击这里的线上 demo[7] 查看效果。

可以看到，在页面不刷新的情况下，页面内容被替换了，表示我们已经成功覆盖了浏览器默认导航行为。不过，由于目前是针对元素的整体覆盖，所以里的数据仍然会丢失。接下来，我们会修改服务器部分，增加返回 JSX 响应的支持。

步骤 2：增加返回 JSX 响应的支持

还记得我们之前使用 JSX 组成的对象树结构吧？

{
  $$typeof: Symbol.for("react.element"),
  type: 'html',
  props: {
    children: [
      {
        $$typeof: Symbol.for("react.element"),
        type: 'head',
        props: {
          // ... And so on ...

接下来，我们将为服务器增加以 ?jsx 结尾的请求支持。?jsx 请求返回的是一个 JSX 树结构，而不是 HTML，这更容易让客户端确定哪些部分发生了变化，并只在必要时更新 DOM，这将直接解决状态在每次导航时丢失的问题，但这并不是我们这样做的唯一原因。接下来，你将看到我们如何将新信息（不仅仅是 HTML）从服务器传递到客户端。

首先修改服务器代码，支持请求中携带 ?jsx 参数时调用一个新的 sendJSX() 函数：

createServer(async (req, res) => {
  try {
    const url = new URL(req.url, `http://${req.headers.host}`);
    if (url.pathname === "/client.js") {
      // ...
    } else if (url.searchParams.has("jsx")) {
      url.searchParams.delete("jsx"); // 确保传递给  的 url 是干净的
      await sendJSX(res, ); // 返回 JSX 数据
    } else {
      await sendHTML(res, );
    }
    // ...

在 sendJSX() 中，我们使用 JSON.stringify(jsx) 把的 JSX 树转换成一个 JSON 字符串，并通过网络返回：

async function sendJSX(res, jsx) {
  const jsxString = JSON.stringify(jsx, null, 2); // Indent with two spaces.
  res.setHeader("Content-Type", "application/json");
  res.end(jsxString);
}

要注意的是，我们并不是发送 JSX 语法本身（如 "" ），只是将 JSX 生成的树结构转换成 JSON 字符串。当然，真正的 RSC 实现使用的是并不是 JSON 格式，这里只是为了方便理解。真正的实现方式我们将在下一个系列进行探讨。

修改客户端代码，看看目前返回的数据：

async function navigate(pathname) {
  currentPathname = pathname;
  const response = await fetch(pathname + "?jsx");
  const jsonString = await response.text();
  if (pathname === currentPathname) {
    alert(jsonString);
  }
}

点击这里[8]，加载首页，然后点击一个链接会看到一个提示，类似下面这样：

{
  "key": null,
  "ref": null,
  "props": {
    "url": "http://localhost:3000/hello-world"
  },
  // ...
}

这并不是我们想要的结构，我们希望看到类似 ... 的 JSX 树。那是哪里出问题了呢？

我们分析一下，现在的 JSX 看起来是这样的：


// {
//   $$typeof: Symbol.for('react.element'),
//   type: Router,
//   props: { url: "http://localhost:3000/hello-world" } },
//    ...
// }

这种结构发送给客户端还“为时过早”，我们不知道 Router 具体的 JSX 内容，因为 Router 只存在服务器上。我们需要在服务端调用 Router 组件，才能得到需要发送给客户端的 JSX 内容。

如果，我们使用 { url: "http://localhost:3000/hello-world" } } 作为 prop 调用 Router 函数，会得到这样一段 JSX：

一样的，把这个结果发送回客户端还为时过早，因为我们不知道 BlogLayout 的内容，而且它只存在于服务器上，因此我们还必须调用 BlogLayout，得到最终传递给客户端的 JSX。

先想一下我们的结果——调用结束后，我们希望得到一个不引用任何服务器代码的 JSX 树。类似：


  ...
  
    
      Home
      
    
    
    
      Welcome to my blog
      
        ...
      
    
    
      
      
        
          (c) Jae Doe 2003

这个结果可以直接传递给 JSON.stringify() 并发送给客户端。

首先，编写一个 renderJSXToClientJSX() 函数。接收一段 JSX 作为参数，"解析 "服务器专有部分（通过调用相应组件获得），直到只剩下客户端可以理解的 JSX。

结构上看，这个函数类似于 renderJSXToHTML()，但它递归遍历返回的是对象，而不是 HTML：

async function renderJSXToClientJSX(jsx) {
  if (
    typeof jsx === "string" ||
    typeof jsx === "number" ||
    typeof jsx === "boolean" ||
    jsx == null
  ) {
    // Don't need to do anything special with these types.
    return jsx;
  } else if (Array.isArray(jsx)) {
    // Process each item in an array.
    return Promise.all(jsx.map((child) => renderJSXToClientJSX(child)));
  } else if (jsx != null && typeof jsx === "object") {
    if (jsx.$$typeof === Symbol.for("react.element")) {
      if (typeof jsx.type === "string") {
        // This is a component like .
        // Go over its props to make sure they can be turned into JSON.
        return {
          ...jsx,
          props: await renderJSXToClientJSX(jsx.props),
        };
      } else if (typeof jsx.type === "function") {
        // This is a custom React component (like ).
        // Call its function, and repeat the procedure for the JSX it returns.
        const Component = jsx.type;
        const props = jsx.props;
        const returnedJsx = await Component(props);
        return renderJSXToClientJSX(returnedJsx);
      } else throw new Error("Not implemented.");
    } else {
      // This is an arbitrary object (for example, props, or something inside of them).
      // Go over every value inside, and process it too in case there's some JSX in it.
      return Object.fromEntries(
        await Promise.all(
          Object.entries(jsx).map(async ([propName, value]) => [
            propName,
            await renderJSXToClientJSX(value),
          ])
        )
      );
    }
  } else throw new Error("Not implemented");
}

接下来编辑 sendJSX()，先将类似的 JSX 转换为 "客户端 JSX"，然后再对其字符串化：

async function sendJSX(res, jsx) {
  const clientJSX = await renderJSXToClientJSX(jsx);
  const clientJSXString = JSON.stringify(clientJSX, null, 2); // Indent with two spaces
  res.setHeader("Content-Type", "application/json");
  res.end(clientJSXString);
}

点击这里的线上 demo[9] 查看效果。

现在点击链接就会显示一个与 HTML 很类似的树状结构提示，这表示我们可以对它进行差异化处理了。

注意：目前我们的目标是能最低要求的工作起来，但在实现过程中还有很多不尽如人意的地方。例如，格式本身非常冗长和重复，真正的 RSC 使用的是更简洁的格式。就像前面生成 HTML 一样，整个响应被 await 是很糟糕的体验。理想情况下，我们希望将 JSX 分块进行流式传输，并在客户端进行拼接。同样，共享布局的部分内容（如和

）没有发生变化，现在也要重新发送这些内容。生产就绪的 RSC 实现并不存在这些缺陷，不过我们暂时接受这些缺陷，让代码看起来更容易理解。

步骤 3：在客户端执行 JSX 更新

严格来说，我们不必使用 React 来扩展 JSX。

到目前为止，我们的 JSX 节点只包含浏览器内置组件（例如：

、

）。为了实现对服务端返回的 JSX 数据，执行差异化处理和更新，我们会直接使用 React。

我们为 React 提供的 JSX 数据，会帮助它知道要创建的 DOM 节点信息，也方便将来安全地进行更改。同样，React 处理过程·中，也会遍历 DOM，查看每个 DOM 节点对应的 JSX 信息。这样，React 就能将事件处理程序附加到 DOM 节点，让节点具备交互性，我们把这个过程叫水合（hydration）。

传统上，要将服务器渲染的标记水合，需要调用 hydrateRoot()，需要为 React 提供一个挂载 DOM 节点，还有服务器上创建的初始 JSX。类似这样：

// Traditionally, you would hydrate like this
hydrateRoot(document, );

问题是我们在客户端根本没有像这样的根组件！从客户端的角度来看，目前我们的整个应用程序就是一大块 JSX，没有任何 React 组件。然而，React 真正需要的只是与初始 HTML 相对应的 JSX 树。这个树类似 ... 这样的：

import { hydrateRoot } from 'react-dom/client';

const root = hydrateRoot(document, getInitialClientJSX());

function getInitialClientJSX() {
  // TODO: return the ... client JSX tree mathching the initial HTML
}

这个过程会非常快，因为客户端返回的 JSX 树中没有任何自定义组件。React 将会以近乎瞬时的速度遍历 DOM 树和 JSX 树，并构建稍后更新树时所需要的一些内部数据结构。

然后，在每次用户导航时，我们获取下一页的 JSX，并通过 root.render[10] 更新 DOM：

async function navigate(pathname) {
  currentPathname = pathname;
  const clientJSX = await fetchClientJSX(pathname);
  if (pathname === currentPathname) {
    root.render(clientJSX);
  }
}

async function fetchClientJSX(pathname) {
  // TODO: fetch and return the ... client JSX tree for the next route
}

补充完 getInitialClientJSX() 和 fetchClientJS() 的内容后。React 就会按照我们预期的方式，创建并托管我们的项目，同时也不会丢失状态。

现在，就让我们来看看如何实现这两个功能。

从服务器获取 JSX

我们先从实现 fetchClientJSX() 开始，因为它更容易实现。

首先，让我们回顾一下 ?jsx 服务器端的实现。

async function sendJSX(res, jsx) {
  const clientJSX = await renderJSXToClientJSX(jsx);
  const clientJSXString = JSON.stringify(clientJSX);
  res.setHeader("Content-Type", "application/json");
  res.end(clientJSXString);
}

我们在客户端向服务端发送 JSX 请求，然后将响应代入 JSON.parse()，再将其转换为 JSX：

async function fetchClientJSX(pathname) {
  const response = await fetch(pathname + "?jsx");
  const clientJSXString = await response.text();
  const clientJSX = JSON.parse(clientJSXString);
  return clientJSX;
}

这样实现之后[11]，点击链接渲染 JSX 时就会报错：

Objects are not valid as a React child (found: object with keys {type, key, ref, props, _owner, _store}).

原因是我们传递给 JSON.stringify() 的对象是这样的：

{
  $$typeof: Symbol.for("react.element"),
    type: 'html',
    props: {
    // ...

但是查看客户端 JSON.parse() 结果，$$typeof 属性在传输过程中丢失了：

{
  type: 'html',
  props: {
    // ...

对 React 来说，如果 JSX 节点中没有 $$typeof: Symbol.for("react.element") 属性，就不会被看作是有效节点。这是一种有意为之的安全机制——默认情况下，React 不会随意将一个任意 JSON 对象视为 JSX 标记。因此，就利用了 Symbol 值无法在 JSON 序列化过程中存在的特性，为 JSX 增加了一个Symbol.for('react.element') 属性。

不过，我们确实在服务器上创建了这些 JSX 节点，而且确实希望在客户端上呈现它们。因此，我们需要调整逻辑，以 "保留" $$typeof: Symbol.for("react.element") 属性。

幸运的是，这个问题并不难解决。JSON.stringify() 接受一个替换函数[12]，可以让我们自定义 JSON 的生成行为。在服务器上，我们将用 "$RE" 这样的特殊字符串替换 Symbol.for('react.element')：

async function sendJSX(res, jsx) {
  // ...
  const clientJSXString = JSON.stringify(clientJSX, stringifyJSX); // Notice the second argument
  // ...
}

function stringifyJSX(key, value) {
  if (value === Symbol.for("react.element")) {
    // We can't pass a symbol, so pass our magic string instead.
    return "$RE"; // Could be arbitrary. I picked RE for React Element.
  } else if (typeof value === "string" && value.startsWith("$")) {
    // To avoid clashes, prepend an extra $ to any string already starting with $.
    return "$" + value;
  } else {
    return value;
  }
}

在客户端，我们将向 JSON.parse() 传递一个 reviver 函数，将 "$RE" 替换为 Symbol.for('react.element') ：

async function fetchClientJSX(pathname) {
  // ...
  const clientJSX = JSON.parse(clientJSXString, parseJSX); // Notice the second argument
  // ...
}

function parseJSX(key, value) {
  if (value === "$RE") {
    // This is our special marker we added on the server.
    // Restore the Symbol to tell React that this is valid JSX.
    return Symbol.for("react.element");
  } else if (typeof value === "string" && value.startsWith("$$")) {
    // This is a string starting with $. Remove the extra $ added by the server.
    return value.slice(1);
  } else {
    return value;
  }
}

点击这里的线上 demo[13] 查看效果。

现在，在页面间进行导航，不过更新全部是以 JSX 形式获取并在客户端应用的！

如果你在输入框中输入内容，然后点击链接，会发现状态在所有导航中都得到了保留，除第一个导航除外。这是因为我们还没有告诉 React 页面的初始 JSX 是什么，所以它无法正确关联服务器返回的 HTML。

将初始 JSX 内联到 HTML 中

还有这段代码：

const root = hydrateRoot(document, getInitialClientJSX());

function getInitialClientJSX() {
  return null; // TODO
}

我们需要将根节点与初始客户端 JSX 相结合，但客户端上的 JSX 怎么来？

为了解决这个问题，我们可以把初始 JSX 字符串作为客户端的全局变量：

const root = hydrateRoot(document, getInitialClientJSX());

function getInitialClientJSX() {
  const clientJSX = JSON.parse(window.__INITIAL_CLIENT_JSX_STRING__, reviveJSX);
  return clientJSX;
}

在服务器上，我们修改 sendHTML() 函数，以便将应用程序渲染为客户端 JSX，并将其内联到 HTML 末尾：

async function sendHTML(res, jsx) {
  let html = await renderJSXToHTML(jsx);

  // Serialize the JSX payload after the HTML to avoid blocking paint:
  const clientJSX = await renderJSXToClientJSX(jsx);
  const clientJSXString = JSON.stringify(clientJSX, stringifyJSX);
  html += ``;
  // ...

最后，我们需要对文本节点生成 HTML 的方式进行一些小调整[14]，以便 React 可以将它们水合。

点击这里的线上 demo[15] 查看效果。

现在你可以输入一些内容，其数据不会在导航间丢失：

图片

这就是我们最初设定的目标！当然，保存这个输入框数据并不是重点，重要的是，我们的应用程序实现了“就地 ”刷新和导航，而不必丢失任何状态。

注意：虽然真正的 RSC 实现确实会在 HTML payload 对 JSX 进行编码，但仍存在一些重要的差异。生产就绪的 RSC 设置会在生成 JSX 块时发送它们，而不是在最后发送单个大 Blob 数据。当 React 加载时，水合作用可以立即开始——React 使用已经可用的 JSX 块遍历树，而不是非要等到它们全部到达。 RSC 还允许将某些组件标记为客户端组件，这时候它们仍然会 SSR 到 HTML 中，但它们的代码会包含在捆绑包中。对于客户端组件，只有其 props 的 JSON 被序列化。将来，React 可能会添加额外的机制来删除 HTML 和嵌入的 payload之间的重复内容。

总结

本文，我们为服务端增加了返回 JSX 数据的支持，并使用 React 在客户端进行消费，实现基于 JSX 结构的页面初始化和页面局部更新。出于安全考虑，React 要求 JSX 节点中需要包含一个 $$typeof: Symbol.for("react.element") 属性。为此，我们在序列化和解析的时候，对 $$typeof 做了特殊的转换处理。

至此，现在我们的代码实际上可以工作了，而且架构已经很接近真正的 RSC 了（虽然没有引入流式传输这样的复杂机制）。在下一篇，也就是本系列的终篇，我们将对现在的代码做一些清理工作，修复一些缺陷，并为下一波功能做好准备。

上一篇：利用属性选择器对外部链接进行样式设计

下一篇：从问题分析的入口谈国产数据库与Oracle在可观测性方面的差距

我们聊聊从头学服务器组件：在导航间保留状态

存在的问题

相关内容

热门资讯