从 Y.js 到 React UI —— 响应式状态投影架构

万籁俱寂，万字将成。

青屏微亮，尺素将传。

从 Y.js 到 React UI —— 响应式状态投影架构 - Wibus.log

在上一篇文章中，我们构建了一个基于 "Map-Reduce" 理念的健壮 CRDT Schema。然而，拥有一个完美的数据模型只是第一步。在前端工程中，真正的挑战在于：如何将这个基于 Mutation（突变）和事件驱动的 Y.js 数据源，高效、合规且优雅地投影到基于 Immutability（不可变性）和 Render Cycle（渲染周期）的 React 组件树中。

如果处理不当，不仅会导致代码中充斥着难以维护的 useEffect 胶水代码，还会引发严重的性能问题（如全量重渲染）甚至无限循环。本文将详细阐述我基于 Jotai 原子化状态管理库构建的 "Atoms Projection" 架构。

TL;DR;

通过这套架构，我们将协同数据流构造为确定性的 React 数据流：

稳定性：UI 组件不再直接接触可变的 Y.js 对象，永远只消费不可变的快照。
高性能：通过 atomFamily 实现按需订阅，通过 eventFilter 阻断无关更新，实现了 O(1) 复杂度的更新性能，与文档总大小无关。
可维护性：所有的转换逻辑、空值检查、类型守卫都封装在 Atom 定义层。组件代码极其干净，只关注渲染逻辑。

这套投影架构构成了前端应用的骨架。而在下一篇文章中，我们将探讨如何通过纯函数和 Origin 机制，安全、规范地修改这些数据。

Impedance Mismatch: 可变源与不可变视图

Y.js 和 React 在设计哲学上存在本质的 Impedance Mismatch：

Y.js (Mutable & Observable): 数据是就地修改的（Mutable）。当我们调用 yMap.set('key', 'value') 时，内存中的对象直接发生了变化。组件需要通过监听 observe 事件来感知变化。
React (Immutable & Snapshot): UI 是状态的函数 UI = f(State)。React 依赖引用的变化（Reference Equality Check）来决定是否更新 DOM。

错误的实践：直接订阅

初学者常犯的错误是在每个组件内部直接订阅 Y.js 数据：

// ❌ 反模式：在组件内直接管理订阅
function CellComponent({ cell }) {
  const [source, setSource] = useState(cell.get('source').toString());

  useEffect(() => {
    const handler = () => setSource(cell.get('source').toString());
    cell.get('source').observe(handler); // 🔴 每个单元格都在独立监听
    return () => cell.get('source').unobserve(handler);
  }, [cell]);

  return <Editor value={source} />;
}

这种做法在 Notebook 场景下（可能包含数百个单元格）会导致：

内存泄漏风险：忘记清理 unobserve 是常态。
渲染瀑布：状态分散，父子组件难以协调。
调试黑洞：无法通过 React DevTools 或 Redux DevTools 追踪状态变更流。

三层原子投影架构

为了解决上述问题，我们引入了 Jotai 以及 y-jotai 库，构建了一个严格分层的状态投影体系。其核心思想是：将 Y.js 的数据结构“投影”为 React 可消费的原子状态（Atoms）。

y-jotai 是我自己的一个库：https://github.com/wibus-wee/jotai-yjs
相较于其他的库而言，这个库的上手难度很高，心智负担较为严重，但是它能做到的，真的是独一无二的能力了，至少看一圈都没人做... 我不想老是重新搓轮子了，直接自己写一个轮子就好

我在之前的博文当中也有提到我的这个项目的来路

架构分为三层：Core Refs（核心引用） -> Snapshots（快照数据） -> UI Components（UI 组件）。

Layer 1: Core Refs

最底层是核心引用层。这些 Atom 并不持有具体的数据值，而是持有 Y.js 数据结构的引用。

CodeBlock Loading...

关键点：cellMapRefAtom 的值本身（即 Y.Map 对象）几乎不会改变，除非整个 Notebook 被重新加载。这为上层提供了极其稳定的依赖锚点，避免了不必要的重新计算。

Layer 2: Snapshots

我们使用 y-jotai 的 createYAtom 和 atomFamily 将 Y.js 的数据切片投影为不可变的快照。

2.1 单元格列表的投影

对于单元格顺序（Order），我们将其投影为一个纯字符串数组：

CodeBlock Loading...

2.2 单元格数据的投影（atomFamily）

对于成百上千个单元格，我们不能将其全部加载到一个大对象中。我们使用 atomFamily 为每个单元格动态创建独立的 Atom：

CodeBlock Loading...

我这里使用到了 y-jotai 的 eventFilter： Y.js 的 observe 事件非常粗粒度，任何该 Map 下的变动（例如 source 文本变动）都会触发回调。但对于 cellCoreFamily 这个 Atom，我们只关心 kind 或 id 的变化。通过 eventFilter，当用户疯狂打字修改 source 时，尽管底层的 Y.Map 在不断触发事件，cellCoreFamily Atom 会直接忽略这些事件，不会通知 React 组件重渲染。 只有当用户切换单元格类型（Markdown/SQL）时，该 Atom 才会更新。

Layer 3: UI Components

到达 UI 层时，所有复杂的 CRDT 逻辑、订阅管理、性能优化都已被屏蔽。组件只需要像消费普通状态一样消费这些 Atom。

CodeBlock Loading...

幽灵更新：Resubscribe

在我们的场景下，可能会发生极其特殊的 Case：引用的替换。例如，我们的 auto-stale 机制在极端情况下可能会替换掉单元格内的 source（Y.Text 对象）。如果我们仅订阅了旧的 Y.Text 对象，新对象的变更将无法被感知。

为此，我们在 createYAtom 中启用了 resubscribeOnSourceChange: true。这确保了当 Atom 依赖的上游 Y.js 对象引用发生物理变化（被另一个 Y.Text 覆盖）时，订阅会自动销毁并重建，指向新的对象。这保证了状态链路在任何动态结构变更下的鲁棒性。

TL;DR;

通过这套架构，我们将协同数据流构造为确定性的 React 数据流：

稳定性：UI 组件不再直接接触可变的 Y.js 对象，永远只消费不可变的快照。
高性能：通过 atomFamily 实现按需订阅，通过 eventFilter 阻断无关更新，实现了 O(1) 复杂度的更新性能，与文档总大小无关。
可维护性：所有的转换逻辑、空值检查、类型守卫都封装在 Atom 定义层。组件代码极其干净，只关注渲染逻辑。

这套投影架构构成了前端应用的骨架。而在下一篇文章中，我们将探讨如何通过纯函数和 Origin 机制，安全、规范地修改这些数据。

Impedance Mismatch: 可变源与不可变视图

Y.js 和 React 在设计哲学上存在本质的 Impedance Mismatch：

Y.js (Mutable & Observable): 数据是就地修改的（Mutable）。当我们调用 yMap.set('key', 'value') 时，内存中的对象直接发生了变化。组件需要通过监听 observe 事件来感知变化。
React (Immutable & Snapshot): UI 是状态的函数 UI = f(State)。React 依赖引用的变化（Reference Equality Check）来决定是否更新 DOM。

错误的实践：直接订阅

初学者常犯的错误是在每个组件内部直接订阅 Y.js 数据：

// ❌ 反模式：在组件内直接管理订阅
function CellComponent({ cell }) {
  const [source, setSource] = useState(cell.get('source').toString());

  useEffect(() => {
    const handler = () => setSource(cell.get('source').toString());
    cell.get('source').observe(handler); // 🔴 每个单元格都在独立监听
    return () => cell.get('source').unobserve(handler);
  }, [cell]);

  return <Editor value={source} />;
}

这种做法在 Notebook 场景下（可能包含数百个单元格）会导致：

内存泄漏风险：忘记清理 unobserve 是常态。
渲染瀑布：状态分散，父子组件难以协调。
调试黑洞：无法通过 React DevTools 或 Redux DevTools 追踪状态变更流。

三层原子投影架构

y-jotai 是我自己的一个库：https://github.com/wibus-wee/jotai-yjs
相较于其他的库而言，这个库的上手难度很高，心智负担较为严重，但是它能做到的，真的是独一无二的能力了，至少看一圈都没人做... 我不想老是重新搓轮子了，直接自己写一个轮子就好

我在之前的博文当中也有提到我的这个项目的来路

架构分为三层：Core Refs（核心引用） -> Snapshots（快照数据） -> UI Components（UI 组件）。

Layer 1: Core Refs

最底层是核心引用层。这些 Atom 并不持有具体的数据值，而是持有 Y.js 数据结构的引用。

// /atoms/notebook/projection/refs.ts

// 根节点引用：整个 Notebook 的入口
export const rootRefAtom = atom((get) => {
  const state = get(notebookRuntimeStateAtom);
  return state.root; // 返回 Y.Doc 中的根 Map
});

// 单元格 Map 引用：从根节点派生
export const cellMapRefAtom = atom((get) => {
  const root = get(rootRefAtom);
  return root ? getCellMapRef(root) : null;
});

CodeBlock Loading...

Layer 2: Snapshots

我们使用 y-jotai 的 createYAtom 和 atomFamily 将 Y.js 的数据切片投影为不可变的快照。

2.1 单元格列表的投影

对于单元格顺序（Order），我们将其投影为一个纯字符串数组：

// /atoms/notebook/projection/snapshots/order.ts
export const cellIdsAtom = createYAtom({
  yAtom: orderRefAtom, // 依赖 Layer 1 的引用
  read: (arr) => arr?.toArray() ?? [], // 将 Y.Array 转换为 JS Array
  equals: shallowEqual, // 只有当 ID 列表真正变化时，Atom 才会更新
  resubscribeOnSourceChange: true,
});

CodeBlock Loading...

2.2 单元格数据的投影（atomFamily）

对于成百上千个单元格，我们不能将其全部加载到一个大对象中。我们使用 atomFamily 为每个单元格动态创建独立的 Atom：

// /atoms/notebook/projection/snapshots/cells.ts

// 1. 定位：获取特定 ID 的 Y.Map 引用
export const cellEntryFamily = atomFamily((cellId: string) =>
  createYMapEntryAtom(cellMapRefAtom, cellId, { ... })
);

// 2. 投影：读取关键字段，并应用精准过滤
export const cellCoreFamily = atomFamily((cellId: string) =>
  createYAtom({
    yAtom: cellEntryFamily(cellId),
    read: (cell) => ({
      id: cell.get(CELL_ID),
      kind: cell.get(CELL_KIND),
    }),
    // 🟢 性能核心：Event Filter
    eventFilter: (evt) =>
      evt.keysChanged.has(CELL_KIND) || evt.keysChanged.has(CELL_ID),
  })
);

CodeBlock Loading...

Layer 3: UI Components

到达 UI 层时，所有复杂的 CRDT 逻辑、订阅管理、性能优化都已被屏蔽。组件只需要像消费普通状态一样消费这些 Atom。

const CellContainer = ({ cellId }) => {
  // 只订阅核心元数据，打字时不会重渲染
  const { kind } = useAtomValue(cellCoreFamily(cellId));

  if (kind === 'sql') return <SqlCell cellId={cellId} />;
  return <MarkdownCell cellId={cellId} />;
};

CodeBlock Loading...