rdc-setup

用途

rdc-setup 用于在既有项目中安装和配置 Reactive Data Client（@data-client/react 或 @data-client/vue）。它先做环境检测，再执行安装，并在应用顶层接入 Provider 或 Plugin，最后引导用户进入协议相关的后续设置。

检测步骤

在安装之前，技能会通过检查文件来检测项目类型与协议。

1. 检测包管理器

检查存在哪个锁文件：

yarn.lock → 使用 yarn add
pnpm-lock.yaml → 使用 pnpm add
package-lock.json 或 bun.lockb → 使用 npm install 或 bun add

2. 检测项目类型

检查 package.json 的 dependencies：

包含 "next" → NextJS
包含 "expo" → Expo
包含 "vue" → Vue
包含 "react-native"（且不含 expo）→ React Native
包含 "react" → 纯 React

3. 检测协议类型

扫描代码库以判断使用哪种数据获取协议：

REST 检测：

带 REST 风格 URL（/api/、/users/ 等）的 fetch() 调用
package.json 中的 HTTP 客户端库：axios、ky、got、superagent
含 REST 模式的文件：api.ts、client.ts、services/*.ts
带路径参数的 URL 模式：/users/:id、/posts/:postId/comments
代码中的 HTTP 方法：method: 'GET'、method: 'POST'、.get(、.post(

GraphQL 检测：

package.json 中的 @apollo/client、graphql-request、urql、graphql-tag
项目中的 .graphql 或 .gql 文件
gql 模板字符串标签
GraphQL 查询模式：query {、mutation {、subscription {
GraphQL 端点 URL：/graphql

自定义协议检测（针对不匹配 REST 或 GraphQL 的异步操作）：

返回 Promise 的自定义异步函数
第三方 SDK 客户端（Firebase、Supabase、AWS SDK 等）
IndexedDB 或其他本地异步存储

安装

核心包

React（全部场景）：@data-client/react，开发依赖 @data-client/test
Vue：@data-client/vue（已包含测试）

安装命令示例

React（NextJS、Expo、React Native、纯 React）：

npm install @data-client/react && npm install -D @data-client/test

yarn add @data-client/react && yarn add -D @data-client/test

pnpm add @data-client/react && pnpm add -D @data-client/test

Vue：

npm install @data-client/vue

yarn add @data-client/vue

pnpm add @data-client/vue

Provider 设置

安装后，在顶层组件添加 provider。

NextJS（App Router）

编辑 app/layout.tsx：

import { DataProvider } from '@data-client/react/nextjs';

export default function RootLayout({ children }) {
  return (
    <html>
      <DataProvider>
        <body>
          {children}
        </body>
      </DataProvider>
    </html>
  );
}

注意：NextJS 使用 @data-client/react/nextjs 导入路径。

Expo

编辑 app/_layout.tsx：

import { Stack } from 'expo-router';
import { DataProvider } from '@data-client/react';

export default function RootLayout() {
  return (
    <DataProvider>
      <Stack>
        <Stack.Screen name="index" />
      </Stack>
    </DataProvider>
  );
}

React Native

编辑入口文件（如 index.tsx）：

import { DataProvider } from '@data-client/react';
import { AppRegistry } from 'react-native';

const Root = () => (
  <DataProvider>
    <App />
  </DataProvider>
);
AppRegistry.registerComponent('MyApp', () => Root);

纯 React（Vite、CRA 等）

编辑入口文件（如 index.tsx、main.tsx 或 src/index.tsx）：

import { DataProvider } from '@data-client/react';
import ReactDOM from 'react-dom/client';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <DataProvider>
    <App />
  </DataProvider>,
);

Vue

编辑 main.ts：

import { createApp } from 'vue';
import { DataClientPlugin } from '@data-client/vue';
import App from './App.vue';

const app = createApp(App);

app.use(DataClientPlugin, {
  // optional overrides
  // managers: getDefaultManagers(),
  // initialState,
  // Controller,
  // gcPolicy,
});

app.mount('#app');

协议相关设置

在完成 provider 设置之后，依据检测到的协议应用相应技能：

REST APIs：应用技能 "rdc-rest-setup"，它会：

安装 @data-client/rest
提供创建扩展 RestEndpoint 的自定义 BaseEndpoint 类的选项
配置常见行为：urlPrefix、认证、错误处理

GraphQL APIs：应用技能 "rdc-graphql-setup"，它会：

安装 @data-client/graphql
创建并配置 GQLEndpoint 实例
设置认证 headers

自定义异步操作：应用技能 "rdc-endpoint-setup"，它会：

安装 @data-client/endpoint
提供用 new Endpoint() 包装现有异步函数的选项
配置 schemas 与缓存选项

多种协议：若检测到多种协议，可应用多个设置技能。每个协议包可与其他包一同安装。

验证清单

设置完成后，验证：

核心包已安装在 package.json 中
Provider/Plugin 在根层级包裹应用
使用了正确的导入路径（尤其 NextJS 使用 @data-client/react/nextjs）
组件树中没有重复的 provider
已通过相应技能完成协议相关设置

常见问题

NextJS：导入路径错误错误写法：

import { DataProvider } from '@data-client/react';

NextJS 正确写法：

import { DataProvider } from '@data-client/react/nextjs';

Provider 未在根层级：DataProvider 必须包裹所有使用 data-client hooks 的组件。应将其放在尽可能顶层的层级。

后续步骤

在核心设置与协议相关设置之后：

使用 Entity 定义数据 schema —— 见技能 "rdc-schema"
使用 useSuspense、useQuery、useController 等 hooks —— 见技能 "rdc-react" 或 "rdc-vue"
定义 REST 资源 —— 见技能 "rdc-rest"

参考资料

详细 API 文档见 references 目录：

DataProvider —— 根 provider 组件
installation —— 安装指南
getDefaultManagers —— 默认 managers