React 渲染性能优化与组件设计：上下文和工具该怎么分工

React 渲染性能优化与组件设计：上下文和工具该怎么分工

当流式文本、检索结果和工具执行状态共用一个 React Context 时，任一状态变更都可能让所有消费者参与更新。应先用 Profiler 确认实际的提交范围，再决定如何拆分状态。

1. 先确认订阅范围：不要让高频状态占用全局 Context

在 React 项目中接入检索与工具调用时，常见问题是一个 AgentProvider 同时保存 messages、retrievedDocs、isToolExecuting、currentToolName 等状态。

流式响应可能每 20 毫秒更新一次 messages。Provider 的 value 随之变化时，消费该 Context 的组件都会参与更新，即使组件只读取低频字段。

[以下为 Profiler 回放示例，结果会随组件与设备而变化]
老方案 (统一 AgentContext 包揽一切)：
- 1 次 SSE 打字流响应 -> 触发 42 个子组件 Render
- 单次打字卡顿帧率掉至 24 FPS
- React Component Tree 重渲染时长：140ms / 帧

重构方案 (Context 上下文与 Tool 执行器解耦)：
- 1 次 SSE 打字流响应 -> 仅 1 个 StreamingText 组件局部 Render
- 页面全程稳在 60 FPS
- React Component Tree 重渲染时长：3.2ms / 帧

问题通常不在 React 本身，而在状态的更新频率和订阅范围没有分开。

2. 状态流转与工具调用的切片拓扑

为了阻断无效重渲染，我们必须把静态的知识检索/上下文、与高频变动的流式响应、以及独立的工具执行状态做三层物理隔离。

拆分后可以缩小高频更新的影响范围；是否带来收益，仍应以实际 Profiler 数据为准。

3. 生产级 TypeScript 实践：解耦上下文 Context 与 Tool Executive

下面给出一套 React 18+ 的状态拆分示例。useSyncExternalStore 可以把高频状态移出 Context；示例的快照仍是整个 store，如需让单个工具卡片只在自身状态变化时更新，还要提供按 toolId 订阅的 store，或使用支持 selector 的状态方案。

import React, { createContext, useContext, useRef, useSyncExternalStore, ReactNode } from 'react';

// 1. 定义 Tool 执行状态的数据契约
export type ToolStatus = 'idle' | 'running' | 'success' | 'error';

export interface ToolState {
  toolName: string;
  status: ToolStatus;
  payload?: Record<string, any>;
  errorMessage?: string;
}

// 2. 自定义轻量级 Tool 执行状态订阅器 (独立于 React Context 树)
class ToolExecutionStore {
  private state: Record<string, ToolState> = {};
  private listeners = new Set<() => void>();

  subscribe = (listener: () => void) => {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  };

  getSnapshot = () => this.state;

  updateToolStatus(toolId: string, newState: ToolState) {
    this.state = { ...this.state, [toolId]: newState };
    this.listeners.forEach((listener) => listener());
  }
}

const globalToolStore = new ToolExecutionStore();

// 3. 基础订阅 Hook：订阅整个 store 后读取指定 Tool
export function useToolState(toolId: string): ToolState {
  const store = useSyncExternalStore(
    globalToolStore.subscribe,
    globalToolStore.getSnapshot
  );
  return store[toolId] || { toolName: '', status: 'idle' };
}

// 4. 低频 Knowledge Context（只存检索文档与上下文配置）
interface KnowledgeContextType {
  documents: Array<{ id: string; title: string; snippet: string }>;
  setDocuments: (docs: Array<{ id: string; title: string; snippet: string }>) => void;
}

const KnowledgeContext = createContext<KnowledgeContextType | null>(null);

export const KnowledgeProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
  const [documents, setDocuments] = React.useState<Array<{ id: string; title: string; snippet: string }>>([]);

  return (
    <KnowledgeContext.Provider value={{ documents, setDocuments }}>
      {children}
    </KnowledgeContext.Provider>
  );
};

export const useKnowledge = () => {
  const ctx = useContext(KnowledgeContext);
  if (!ctx) throw new Error('useKnowledge 必须在 KnowledgeProvider 内使用');
  return ctx;
};

// 5. Tool 渲染组件：实际更新范围取决于 store 的订阅实现
export const ToolExecutionCard: React.FC<{ toolId: string }> = React.memo(({ toolId }) => {
  const toolState = useToolState(toolId);

  if (toolState.status === 'idle') return null;

  return (
    <div className={`tool-card tool-card-${toolState.status}`}>
      <div className="tool-header">
        <span>工具名：{toolState.toolName}</span>
        <span className="status-badge">{toolState.status}</span>
      </div>
      {toolState.status === 'running' && <div className="loading-spinner">正在调用本地 API...</div>}
      {toolState.status === 'error' && (
        <div className="error-text">错误：{toolState.errorMessage || '未知异常'}</div>
      )}
    </div>
  );
});

4. 接口契约与错误语义设计：四类典型故障的语义隔离

在 AI 与前端交界处，错误语义设计极易混乱。很多人把 LLM 接口超时、Tool 执行报错、RAG 检索为空全当成“请求失败”抛给 UI。

工程化做法是定义清晰的错误契约：

前端可以根据 ErrorCode 选择恢复、降级或提示，不必把所有异常都处理为全屏提示。

5. 性能优化的本质：边界清晰，责任明确

useMemo 和 React.memo 不能替代状态边界设计。流式响应更新频繁时，先分清哪些状态需要共享、哪些状态只服务局部组件，再通过 Profiler 验证拆分是否减少了无效提交。

6. 先定位哪次提交拖慢了页面

排查时在真实操作中录制 Profiler，关注提交次数、耗时和触发源。搜索输入每敲一个字就刷新侧栏，通常应把输入留在局部组件，而不是先给侧栏包 memo；共享数据确实变化时再引入 selector 或拆分 context。列表需要稳定 key，回调需要稳定引用，但这些只是服务于明确的边界。修改后重复同一条操作录制一次，确认收益不是偶然，也没有把交互延迟转移到别的阶段。线上还可按低端设备抽样，避免只在开发机上得出结论。

7. 组件拆分要先看数据变化方向

一个组件过大不必然导致卡顿，真正影响渲染的是哪些状态变化会触达它。可以先画出数据来源：输入框的临时值、接口返回的数据、路由参数和全局主题各自影响哪些区域。频繁变化且只影响局部的值，留在局部最省事；跨页面共享且更新稀少的值，再放入 context 或外部状态。

拆分时别只把 JSX 挪到新文件。子组件若仍接收一个不停变化的大对象，渲染边界没有变。更好的做法是传入它真正需要的字段，或者在上层计算稳定的派生值。每次拆分后用同一条交互检查渲染次数，若没有改善，就不要为了“组件化”继续加包装层。