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

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

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

Именно поэтому Data Connect предоставляет вам среду разработки и инструменты, позволяющие создавать прототипы схем, запросов и мутаций, развёртываемых на сервере. Кроме того, Data Connect автоматически генерирует клиентские SDK во время создания прототипа.

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

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

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

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

Подводя итог, чтобы использовать сгенерированные Web 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

Сгенерированный код уже содержит предопределённые ссылки запросов. Вам остаётся только импортировать их и вызвать метод 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 с префиксом use для 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 .