调试与检查

使用 agent 调试

对于许多调试任务，最快的方式是使用一个已经掌握 @data-client/react 调试流程的 agent。

在你的编程 agent 中安装 data-client-react skill，然后让它检查当前页面或应用的状态。

agent 调试的工作原理

在开发模式下，DevToolsManager 会暴露正在运行的 Controller 实例，让 agent 可以直接从运行中的应用里检查缓存状态、endpoint 元数据以及已 dispatch 的 action。

从技术上讲，这些 controller 存储在 globalThis.__DC_CONTROLLERS__ 上，它是一个浏览器全局的 Map。你可以把它看作一个临时的开发模式注册表，让工具和 agent 能够查找当前页面中活跃的 DataProvider store。

概括来说，agent 可以：

• 发现活跃的 DataProvider controller
• 读取规范化或反规范化的缓存状态
• 检查最近的请求、响应、错误和失效
• 将 store 的变化与浏览器的网络活动关联起来
• 为排查问题触发安全的 controller 操作，例如使数据失效或过期

当你想快速回答“为什么这里没有重新获取？”、 “缓存里现在有什么？”或“是哪个 action 更新了这个 Entity？”之类的问题，而又不想手动逐个点开检查面板时，这会非常有用。

该 skill 通过 Chrome DevTools MCP 完成这些操作。

手动调试

如果你更愿意亲自检查一切，下面的浏览器 devtools 流程仍然是标准的手动方式。

安装

添加浏览器扩展： chrome 扩展或 firefox 扩展

打开 dev tools

安装完成并以 开发模式 加载你的网站后，你可以点击 Data Client 的 logo（默认位于窗口右下角），也可以点击地址栏中的 redux-devtool logo。

点击后会打开检查器，你可以在其中观察已 dispatch 的 action、它们对 store 状态的影响，以及 store 当前的状态。

Data Client 的 logo 只会在开发模式下出现。不过，你可以通过设置 DataProvider 的 devButton prop 来移动它的位置或完全禁用它。

Controller 负责 dispatch action，因此可以借助该页面来理解你看到的各个 action。这里我们可以看到常见的 fetch 和 setResponse action。

备注

默认情况下，devtool 集成会过滤重复的 fetch action。可以通过 skipLogging 选项更改此行为。

控制流

Data Client 采用 flux store 模式，每一次变化都可追踪且含义明确，因此调试起来非常直接。

进一步了解控制流

状态检查

使用 schema 时，响应会被规范化到 entities 和 endpoints 表中。相比简单的键值式请求缓存，这能自动带来性能优势，对于动态（不断变化的）数据尤其有益。同时还能消除数据不一致的 bug。

点击 devtools 中的 'state' 标签页即可查看 store 的完整状态。这有助于准确定位数据所在的位置。缓存中还有一个 'meta' 部分，记录诸如请求发生时间之类的信息（对 TTL 很有用）。

状态差异

如果要监控某个特定请求的响应，查看 store 如何更新可能更有用。点击 'Diff' 标签页即可查看发生了哪些变化。

这里我们通过乐观更新切换了一个 todo 的 'completed' 状态。

Action 追踪

由于计算开销很大，追踪功能默认不启用。不过，在查找 action 是从哪里 dispatch 的时候，它会非常有用。通过 getDefaultManagers 将 trace 选项设为 true，即可自定义 DevToolsManager：

index.tsx

import { DataProvider, getDefaultManagers } from '@data-client/react';
import { createRoot } from 'react-dom/client';
import App from './App';

const managers = getDefaultManagers({
  devToolsManager: { trace: true },
});

createRoot(document.body).render(
  <DataProvider managers={managers}>
    <App />
  </DataProvider>,
);