使用生成的 Web SDK

借助 Firebase Data Connect 客户端 SDK，您可以直接从 Firebase 应用调用服务器端查询和更改。在设计要部署到 Data Connect 服务的架构、查询和更改时，您可以并行生成自定义客户端 SDK。然后，将此 SDK 中的方法集成到您的客户端逻辑中。

正如我们在其他地方提到的那样，请务必注意，Data Connect 查询和更改不是由客户端代码提交并在服务器上执行的。而是在部署后，Data Connect 操作会存储在服务器上（就像 Cloud Functions 函数一样）。这意味着，您需要部署相应的客户端更改，以免影响现有用户（例如，在旧版应用中）。

因此，Data Connect 为您提供了开发者环境和工具，可让您对部署在服务器上的架构、查询和更改进行原型设计。它还会在您进行原型设计时自动生成客户端 SDK。

迭代服务和客户端应用的更新后，服务器端和客户端更新都已准备好部署。

使用 Firebase JavaScript SDK 实现客户端代码

本部分介绍了如何使用 Firebase JavaScript SDK 实现客户端。

如果您使用的是 React，请参阅其他设置说明以及有关为 Data Connect 生成 React SDK 的其他文档链接。

初始化您的应用

首先，使用标准 Firebase 序列初始化应用。

initializeApp({...});

生成 JavaScript SDK

与大多数 Firebase 项目一样，Firebase Data Connect 客户端代码的工作在本地项目目录中进行。Data Connect VS Code 扩展程序和 Firebase CLI 都是生成和管理客户端代码的重要本地工具。

SDK 生成选项的键值对应于您在初始化项目时生成的 dataconnect.yaml 文件中的多个条目。

初始化 SDK 生成

在 connector.yaml 中，添加 outputDir、package 和（对于 Web SDK）packageJsonDir。 
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir 用于指定生成的 SDK 应输出到何处。

package 指定软件包名称。

packageJsonDir 用于指定软件包的安装位置。

在本例中，请安装 firebase@latest，以确保满足此对等依赖项。

初始化 JavaScript SDK

使用您设置 Data Connect 时所用的信息初始化 Data Connect 实例（所有信息均可在 Firebase 控制台的“Data Connect”标签页中找到）。

ConnectorConfig 对象

SDK 需要连接器配置对象。

此对象由 dataconnect.yaml 中的 serviceId 和 location，以及 connector.yaml 中的 connectorId 自动生成。

导入库

初始化客户端代码需要两组导入：常规 Data Connect 导入和特定的生成 SDK 导入。

请注意常规导入中包含的 ConnectorConfig 对象。

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

使用 JavaScript SDK 中的查询

生成的代码将已包含预定义的查询引用。您只需导入这些模块并调用其执行方法即可。

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

调用 SDK 查询方法

以下示例展示了如何使用这些操作快捷方式函数：

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out // to the server.
listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

订阅更改

您可以订阅更改（每当您执行查询时，这些更改都会更新）。

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`

使用 JavaScript SDK 中的更改

您可以通过与查询相同的方式访问更改。

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

连接到 Data Connect 模拟器

（可选）您可以通过调用 connectDataConnectEmulator 并传入 Data Connect 实例来连接到模拟器，如下所示：

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

如需切换到正式版资源，请注释掉用于连接到模拟器的行。

为 React 实现客户端代码

Firebase Data Connect 使用 Invertase 合作伙伴提供的库 TanStack Query Firebase，提供一个包含 React 钩子的生成 SDK。

此库提供了一组钩子，可大大简化在应用中使用 Firebase 处理异步任务的操作。

初始化您的应用

首先，与任何 Firebase Web 应用一样，使用标准 Firebase 序列初始化您的应用。

initializeApp({...});

安装 TanStack Query Firebase 软件包

在项目中安装 TanStack Query 的软件包。

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

生成 React SDK

与标准 Web SDK 一样（如前面所述），Firebase 工具会根据您的架构和操作自动生成 SDK。

如需为项目生成 React SDK，请将 react 键添加到 connector.yaml 配置文件中。

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

导入库

初始化 React 客户端代码需要四组导入：常规 Data Connect 导入、常规 TanStack 导入，以及适用于 JS 和 React 生成的 SDK 的特定导入。

请注意常规导入中包含的 ConnectorConfig 类型。

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

在 React 客户端中使用查询和更改

设置完成后，您可以纳入生成的 React SDK 中的方法。

在以下代码段中，请注意生成的 React SDK 中带有 use 前缀的方法 useListAllMovies。生成的 SDK 中的所有此类 use 操作（包括查询和更改）都会调用 TanStack 查询绑定：

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
   const queryClient = new QueryClient();
   return <QueryClientProvider client={queryClient}>
     <MyComponent />
   </QueryClientProvider>
}

连接到 Data Connect 模拟器

（可选）您可以通过调用 connectDataConnectEmulator 连接到模拟器，然后将 Data Connect 实例传入到生成的钩子，如下所示：

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

如需切换到正式版资源，请注释掉用于连接到模拟器的行。

SDK 中的数据类型

Data Connect 服务器代表常见的 GraphQL 数据类型。这些参数在 SDK 中表示如下。

Data Connect 类型 TypeScript
时间戳 字符串
日期 字符串
UUID 字符串
Int64 字符串
双精度型 数字
浮点数 数字

SDK 生成的特殊注意事项

配置相对于 node_modules 的路径

对于 JavaScript SDK，由于 Data Connect 使用 npm link 安装您的 SDK，因此您生成的 SDK 需要输出到与 node_modules 路径同级的目录，或输出到可以访问 node_modules 的子目录。

换句话说，生成的 SDK 需要有权访问 firebase 节点模块才能正常运行。

例如，如果您的 node_modules 位于 my-app/ 中，则输出目录应为 my-app/js-email-generated，以便 js-email-generated 可以从其父级 node_modules 文件夹导入。

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

或者，如果您使用的是将模块托管在根目录下的单体仓库，则可以将输出目录放在单体仓库中的任何文件夹中。

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

在进行原型设计时更新 SDK

如果您使用 Data Connect VS Code 扩展程序及其 Data Connect 模拟器进行交互式原型设计，则在您修改用于定义架构、查询和更改的 .gql 文件时，系统会自动生成和更新 SDK 源文件。这在热（重新）加载工作流中非常有用。

在其他情况下，如果您使用的是 Firebase CLI 中的 Data Connect 模拟器，则可以对 .gql 更新设置监视，还可以自动更新 SDK 源代码。

或者，您也可以在 .gql 文件发生更改时使用 CLI 重新生成 SDK：

firebase dataconnect:sdk:generate --watch

生成用于集成和正式版的 SDK

在某些情况下（例如准备项目源代码以提交 CI 测试），您可以调用 Firebase CLI 进行批量更新。

在这种情况下，请使用 firebase dataconnect:sdk:generate。

其他框架注意事项

Angular

生成代码时，Angular CLI 不会因其依赖项优化代码而检测到新更改。要解决此问题，您需要修改 angular.json。

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }