Как использовать сгенерированные веб-SDK

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

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

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

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

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

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

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

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

Затем:

  1. Разработайте схему приложения.
  2. Инициализируйте клиентский код с помощью JavaScript SDK.
  3. Настройте создание SDK:
    • С помощью кнопки Add SDK to app (Добавить SDK в приложение) в расширении SQL Connect для VS Code.
    • Обновите connector.yaml для JavaScript SDK.
  4. Импортируйте библиотеки и сгенерированный код с помощью JavaScript SDK.
  5. Реализуйте вызовы запросов и изменений с помощью JavaScript SDK.
  6. Протестируйте, настроив эмулятор SQL Connect с помощью JavaScript SDK.

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

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

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

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

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

initializeApp({...});

Установите сгенерированный JavaScript SDK

Используйте CLI Firebase, чтобы настроить сгенерированные SDK SQL Connect в своих приложениях. Команда init должна обнаружить все приложения в текущей папке и автоматически установить сгенерированные SDK.

firebase init dataconnect:sdk

Подключите приложение к сервису SQL 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 во время создания прототипа

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

Если вы не используете расширение SQL Connect VS Code, то можете обновлять сгенерированные SDK с помощью интерфейса командной строки Firebase.

firebase dataconnect:sdk:generate --watch

Генерируйте SDK в конвейерах сборки

Вы можете использовать интерфейс командной строки Firebase, чтобы генерировать SDK SQL Connect в процессах сборки CI/CD.

firebase dataconnect:sdk:generate

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

Чтобы инициализировать код клиента, нужно импортировать два набора: общие импорты SQL 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

В сгенерированном коде уже будут ссылки на запросы. Вам нужно только импортировать их и вызвать метод 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);
}

Подписаться на изменения

Подробнее о том, как получать обновления от SQL Connect в реальном времени…

Как обрабатывать изменения в полях перечисления

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

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

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

Однако до выпуска обновленной версии клиентов старые развернутые клиенты могут перестать работать.

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

Всегда добавляйте ветвь default в оператор switch по значениям перечисления или ветвь else в блок if/else if, сравнивающий значения перечисления. Это не обеспечивается языком 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' }));

Как подключиться к эмулятору SQL Connect

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

Чтобы переключиться на рабочие ресурсы, закомментируйте строки для подключения к эмулятору.

Включить клиентское кеширование

В SQL Connect есть необязательная функция клиентского кеширования, которую можно включить, отредактировав файл connector.yaml. Если эта функция включена, сгенерированные клиентские SDK будут локально кешировать ответы на запросы. Это может уменьшить количество запросов к базе данных, которые делает ваше приложение, и позволит зависящим от базы данных частям вашего приложения работать при прерывании доступности сети.

Чтобы включить клиентское кеширование, добавьте конфигурацию клиентского кеширования в конфигурацию коннектора:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

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

  • maxAge – максимальный срок хранения кешированного ответа, по истечении которого клиентский SDK запрашивает новые значения. Примеры: "0", "30s", "1h30m".

    Значение по умолчанию для maxAge – 0. Это означает, что ответы кешируются, но клиентский SDK всегда будет получать новые значения. Кешированные значения будут использоваться, только если для CACHE_ONLY задано executeQuery() и получен первоначальный результат от subscribe().

  • storage. Клиентский SDK можно настроить так, чтобы ответы кешировались в хранилище persistent или memory. Результаты, сохраненные в хранилище persistent, будут доступны после перезапуска приложения. В веб-SDK поддерживается только хранилище memory.

После обновления конфигурации кеширования коннектора повторно сгенерируйте клиентские SDK и пересоберите приложение. После этого executeQuery() и subscribe() будут кешировать ответы и использовать кешированные значения в соответствии с настроенным правилом. Обычно это происходит автоматически, без каких-либо дополнительных действий с вашей стороны. Однако обратите внимание на следующее:

  • Поведение executeQuery() по умолчанию описано выше: если результат запроса кеширован и кешированное значение не старше maxAge, используется кешированное значение. Такое поведение по умолчанию называется правилом PREFER_CACHE.

    Вы также можете указать, чтобы отдельные вызовы executeQuery() либо показывали только кешированные значения (CACHE_ONLY), либо безусловно получали новые значения с сервера (SERVER_ONLY).

    await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
    
    await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
    
  • При вызове subscribe() всегда сразу возвращается кешированный контент, если он есть, независимо от настройки maxAge. Последующие вызовы executeQuery() будут уведомлять прослушиватели в соответствии с настроенным значением maxAge.

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

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

Тип SQL Connect TypeScript
Временная метка string
Дата string
UUID string
Int64 string
Двуспальная Количество
Число с плавающей запятой Количество

Генерируйте SDK для React и Angular с помощью TanStack

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

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

В TanStack есть собственная реализация клиентского кеширования и подписок в реальном времени, которая может работать вместе со встроенной поддержкой реального времени в SQL Connect, но это может быть сложно. Мы рекомендуем использовать либо привязки на основе TanStack, либо встроенную поддержку реального времени SQL Connect, но не то и другое одновременно.

Обратите внимание, что собственная реализация SQL Connect в реальном времени имеет некоторые преимущества перед привязками TanStack:

  • Нормализованное кеширование. SQL Connect реализует нормализованное кеширование, которое повышает согласованность данных, а также эффективность использования памяти и сети по сравнению с кешированием на уровне запросов. При нормализованном кэшировании, если объект обновляется в одной области вашего приложения, он также будет обновляться в других областях, которые используют этот объект.
  • Удаленная аннуляция. SQL Connect может удаленно аннулировать кешированные объекты на всех устройствах, на которых оформлена подписка.

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

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

initializeApp({...});

Установите пакеты TanStack Query Firebase

Установите пакеты для TanStack Query в своем проекте.

React;

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

Angular

ng add @angular/fire

Как создать SDK для React или Angular

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

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

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

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

Обратите внимание на тип ConnectorConfig, включенный в общий импорт.

React;

// 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";

Angular

// 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 для Angular. Оба метода взяты из сгенерированного SDK.

React;

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

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

Angular

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

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

React;

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

Angular

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

Как подключиться к эмулятору SQL Connect

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

React;

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

Angular

// 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 во время создания прототипа

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

Если вы не используете расширение SQL Connect VS Code, то можете обновлять сгенерированные SDK с помощью интерфейса командной строки Firebase.

firebase dataconnect:sdk:generate --watch

Генерируйте SDK в конвейерах сборки

Вы можете использовать интерфейс командной строки Firebase, чтобы генерировать SDK SQL Connect в процессах сборки CI/CD.

firebase dataconnect:sdk:generate