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

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

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

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

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

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

Если вы следовали инструкциям в разделе «Начало работы» , вы познакомились с общим процессом разработки Data Connect . В этом руководстве вы найдете более подробную информацию о создании веб-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 CLI для настройки сгенерированных Data Connect SDK в ваших приложениях. Команда init должна обнаружить все приложения в текущей папке и автоматически установить сгенерированные SDK.

firebase init dataconnect:sdk

Подключите ваше приложение к сервису Data Connect .

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Обновляйте SDK во время прототипирования.

Если у вас установлено расширение Data Connect для VS Code, оно всегда будет поддерживать сгенерированные SDK в актуальном состоянии.

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

firebase dataconnect:sdk:generate --watch

Генерация SDK в конвейерах сборки

С помощью Firebase CLI можно генерировать SDK для Data Connect в процессах сборки CI/CD.

firebase dataconnect:sdk:generate

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

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

Используйте запросы из JavaScript SDK.

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

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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

Вызов методов запроса SDK

Вот пример использования этих функций быстрого доступа к действиям:

import { listMovies } from '@dataconnect/generated';
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`

Обработка изменений в полях перечисления

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

По мере изменения дизайна приложения вы можете добавлять новые значения, поддерживаемые перечислениями. Например, представьте, что на более позднем этапе жизненного цикла вашего приложения вы решили добавить значение FULLSCREEN в перечисление AspectRatio .

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

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

Пример отказоустойчивой реализации

В операторе switch всегда добавляйте ветвь default для проверки значений перечисления, а в блоке if/else if ветвь else для сравнения значений перечисления. Это не является обязательным требованием языка JavaScript/TypeScript, но позволяет сделать клиентский код более устойчивым в случае добавления новых значений перечисления.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

Используйте мутации из JavaScript SDK.

Изменённые значения доступны так же, как и запросы.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

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

Подключитесь к эмулятору Data Connect .

При желании вы можете подключиться к эмулятору, вызвав метод connectDataConnectEmulator и передав в него экземпляр Data Connect , следующим образом:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

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

Сгенерируйте свой SDK для React или Angular.

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

Если вы только что добавили React или Angular в свой проект, повторно запустите firebase init dataconnect:sdk , чтобы перенастроить сгенерированные SDK и включить дополнительные привязки фреймворка.

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

Для инициализации клиентского кода React или Angular необходимы четыре набора импортов: общие импорты Data Connect , общие импорты TanStack и специфические импорты для SDK, сгенерированных вашим JavaScript и 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 '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/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 '@dataconnect/generated';

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

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

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

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

import { useListAllMovies } from '@dataconnect/generated/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 '@dataconnect/generated/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 '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/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 во время прототипирования.

Если у вас установлено расширение Data Connect для VS Code, оно всегда будет поддерживать сгенерированные SDK в актуальном состоянии.

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

firebase dataconnect:sdk:generate --watch

Генерация SDK в конвейерах сборки

С помощью Firebase CLI можно генерировать SDK для Data Connect в процессах сборки CI/CD.

firebase dataconnect:sdk:generate