Используйте сгенерированные веб-SDK.

Клиентские SDK Firebase Data Connect позволяют вам вызывать ваши серверные запросы и мутации непосредственно из приложения Firebase. Вы генерируете пользовательский клиентский SDK параллельно с разработкой схем, запросов и мутаций, которые вы развертываете в своей службе Data Connect . Затем вы интегрируете методы из этого SDK в свою клиентскую логику.

Как мы уже упоминали в другом месте, важно отметить, что запросы и мутации Data Connect не отправляются клиентским кодом и не выполняются на сервере. Вместо этого при развертывании операции Data Connect сохраняются на сервере, как Cloud Functions. Это означает, что вам необходимо развернуть соответствующие изменения на стороне клиента, чтобы не нарушить работу существующих пользователей (например, в старых версиях приложения).

Вот почему Data Connect предоставляет вам среду разработки и инструменты, которые позволяют вам прототипировать ваши развернутые на сервере схемы, запросы и мутации. Он также автоматически генерирует клиентские SDK, пока вы прототипируете.

После итерационного обновления сервисных и клиентских приложений обновления как на стороне сервера, так и на стороне клиента готовы к развертыванию.

Каков рабочий процесс развития клиента?

Если вы следовали Get started , вы ознакомились с общим процессом разработки для Data Connect . В этом руководстве вы найдете более подробную информацию о создании Web SDK из вашей схемы и работе с клиентскими запросами и мутациями.

Вы можете изучить разработку клиентских приложений с помощью репозитория приложений для быстрого старта и создать полнофункциональное приложение Data Connect следуя нашей практической работе по кодированию для веб-приложений .

Подводя итог, можно сказать, что для использования сгенерированных веб-SDK в клиентских приложениях вам необходимо выполнить следующие предварительные действия:

1. Добавьте Firebase в свое веб- приложение.

Затем:

1. Разработайте схему своего приложения.
2. Инициализируйте клиентский код с помощью JavaScript SDK или библиотек React или Angular .
3. Для React и Angular установите пакеты Tanstack Query

4. Настройте генерацию SDK:

   • С помощью кнопки «Добавить SDK в приложение» в нашем расширении Data Connect VS Code
   • Обновив connector.yaml для JavaScript SDK , React или Angular .

5. Импортируйте библиотеки и сгенерированный код с помощью JavaScript SDK , React или Angular .

6. Реализуйте вызовы запросов и мутации с помощью JavaScript SDK , React или Angular .

7. Протестируйте, настроив эмулятор Data Connect с помощью JavaScript SDK , React или Angular .

Реализуйте клиентский код с помощью Firebase JavaScript SDK

В этом разделе рассматривается, как можно реализовать клиенты с помощью Firebase JavaScript SDK.

Если вы используете React или Angular, ознакомьтесь с альтернативными инструкциями по настройке и ссылками на дополнительную документацию о создании SDK Data Connect для фреймворков .

Инициализируйте свое приложение

Сначала инициализируйте свое приложение, используя стандартную последовательность Firebase .

initializeApp({...});

Создайте свой JavaScript SDK

Как и в большинстве проектов Firebase, работа над клиентским кодом Firebase Data Connect происходит в локальном каталоге проекта. Как расширение Data Connect VS Code, так и Firebase CLI являются важными локальными инструментами для генерации и управления клиентским кодом.

Параметры генерации SDK привязаны к нескольким записям в файле dataconnect.yaml , созданном при инициализации проекта.

Инициализировать генерацию SDK

В файле connector.yaml добавьте outputDir , package и (для веб-SDK) packageJsonDir .

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

outputDir указывает, куда должен выводиться сгенерированный SDK.

package указывает имя пакета.

packageJsonDir указывает, куда установить пакет.

Примечание: для генерации мы добавляем "firebase": "^10.14.0" как peerDependency . В зависимости от вашего менеджера зависимостей (например, pnpm ), эти зависимости могут не устанавливаться автоматически.

В этом случае установите firebase@latest чтобы убедиться, что эта зависимость однорангового узла выполнена.

Инициализируйте JavaScript SDK

Инициализируйте свой экземпляр Data Connect используя информацию, которую вы использовали для настройки Data Connect (все доступно на вкладке Data Connect консоли Firebase ).

Объект ConnectorConfig

Для SDK требуется объект конфигурации коннектора.

Этот объект автоматически генерируется из serviceId и location в dataconnect.yaml и connectorId в connector.yaml .

Импорт библиотек

Для инициализации клиентского кода необходимы два набора импортов: общие импорты 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

Сгенерированный код уже будет содержать предопределенные Query Refs. Все, что вам нужно сделать, это импортировать и вызвать execute для них.

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

Для переключения на производственные ресурсы закомментируйте строки подключения к эмулятору.

Примечание: Вызов getDataConnect требуется только в том случае, если вы хотите подключиться к эмулятору Data Connect . В противном случае сгенерированный SDK автоматически создаст для вас экземпляр объекта DataConnect .

Реализовать клиентский код для React и Angular

Firebase Data Connect предоставляет сгенерированный SDK с хуками для React и Angular с использованием библиотек, доступных у наших партнеров Invertase, TanStack Query Firebase .

Эта библиотека предоставляет набор хуков, которые значительно упрощают обработку асинхронных задач с помощью Firebase в ваших приложениях.

Инициализируйте свое приложение

Сначала, как и в случае с любым веб-приложением Firebase, инициализируйте свое приложение, используя стандартную последовательность 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

Угловой

ng add @angular/fire

Создайте свой React или Angular SDK

Как и в случае со стандартным веб-SDK, описанным ранее , инструментарий Firebase обеспечивает автоматическую генерацию SDK на основе вашей схемы и операций.

Чтобы сгенерировать React SDK для вашего проекта, добавьте ключ react в файл конфигурации connector.yaml .

Реагировать

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

Угловой

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

Импорт библиотек

Для инициализации клиентского кода React или Angular необходимы четыре набора импортов: общий импорт Data Connect , общий импорт TanStack и специальный импорт для ваших SDK, созданных на JS и React.

Обратите внимание на тип 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";

Угловой

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

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

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

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";

Используйте запросы и мутации в вашем клиенте React или Angular

После завершения настройки вы можете включить методы из сгенерированного SDK.

В следующем фрагменте обратите внимание на use метода useListAllMovies с префиксом для React и метода injectListAllMovies с inject для Angular, оба из сгенерированного SDK.

Реагировать

Все подобные операции в сгенерированном SDK, как запросы, так и мутации, вызывают привязки TanStackQuery:

• Запросы вызывают и возвращают хук TanStack useDataConnectQuery
• Мутации вызывают и возвращают хук TanStack useDataConnectMutation

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>
}

Угловой

Примечание: ng add @angular/fire автоматически сделает это за вас, но если вы решите настроить это вручную, вы можете сделать это с помощью следующего кода:

import { injectAllMovies, connectorConfig } from '@movies-app/movies/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Используйте запросы автоматической перезагрузки с React и Angular

Вы можете настроить автоматическую перезагрузку запросов при изменении данных.

Реагировать

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

Угловой

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Подключитесь к эмулятору 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);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

Угловой

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Для переключения на производственные ресурсы закомментируйте строки подключения к эмулятору.

Примечание: Вызов getDataConnect требуется только в том случае, если вы хотите подключиться к эмулятору Data Connect . В противном случае сгенерированный SDK автоматически создаст для вас экземпляр объекта DataConnect .

Типы данных в SDK

Сервер Data Connect представляет общие типы данных GraphQL. Они представлены в SDK следующим образом.

Тип подключения данных	Машинопись
Временная метка	нить
Дата	нить
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 , исходные файлы SDK автоматически генерируются и обновляются, пока вы изменяете файлы .gql определяющие схемы, запросы и мутации. Это может быть полезной функцией в рабочих процессах горячей (пере)загрузки.

В других сценариях, если вы используете эмулятор Data Connect из Firebase CLI, вы можете установить отслеживание обновлений .gql , а также автоматически обновлять исходные коды SDK.

Кроме того, вы можете использовать CLI для повторной генерации SDK при каждом изменении файлов .gql:

firebase dataconnect:sdk:generate --watch

Создание SDK для интеграции и производственных выпусков

В некоторых сценариях, например при подготовке исходных кодов проекта к отправке на CI-тесты, можно вызвать Firebase CLI для пакетного обновления.

В этих случаях используйте firebase dataconnect:sdk:generate .