Используйте сгенерированные веб-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 из вашей схемы и работе с клиентскими запросами и мутациями.

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

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

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

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

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

В этом случае установите 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

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

Реализовать клиентский код для 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.

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

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;
}),

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

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

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

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

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

firebase dataconnect:sdk:generate --watch

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

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

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