생성된 웹 SDK 사용

Firebase SQL Connect 클라이언트 SDK를 사용하면 Firebase 앱에서 서버 측 쿼리 및 변형을 직접 호출할 수 있습니다. SQL Connect 서비스에 배포할 스키마, 쿼리, 변형을 설계할 때 맞춤 클라이언트 SDK를 동시에 생성합니다. 그런 다음 이 SDK의 메서드를 클라이언트 로직에 통합합니다.

다른 곳에서 언급했듯이 SQL Connect 쿼리와 변형은 클라이언트 코드에 의해 제출되지 않고 서버에서 실행됩니다. 대신 배포 시 SQL Connect 작업은 Cloud Functions와 같은 서버에 저장됩니다. 즉, 기존 사용자 (예: 이전 앱 버전)가 중단되지 않도록 해당하는 클라이언트 측 변경사항을 배포해야 합니다.

따라서 SQL Connect는 서버에 배포된 스키마, 쿼리, 변형을 프로토타입으로 만들 수 있는 개발자 환경과 도구를 제공합니다. 프로토타입을 제작하는 동안 클라이언트 측 SDK도 자동으로 생성됩니다.

서비스 및 클라이언트 앱에 대한 업데이트를 반복하면 서버 측 및 클라이언트 측 업데이트를 모두 배포할 수 있습니다.

클라이언트 개발 워크플로란 무엇인가요?

시작하기를 따른 경우 SQL Connect의 전반적인 개발 흐름을 살펴봤을 것입니다. 이 가이드에서는 스키마에서 웹 SDK를 생성하고 클라이언트 쿼리 및 변형을 사용하는 방법에 관한 자세한 정보를 확인할 수 있습니다.

요약하자면 클라이언트 앱에서 생성된 웹 SDK를 사용하려면 다음 필수 단계를 따르세요.

웹 앱에 Firebase를 추가합니다.

그런 다음 아래를 실행합니다.

앱 스키마를 개발합니다.
JavaScript SDK를 사용하여 클라이언트 코드를 초기화합니다.
SDK 생성 설정:
- SQL Connect VS Code 확장 프로그램의 앱에 SDK 추가 버튼을 사용합니다.
- JavaScript SDK의 connector.yaml를 업데이트합니다.
JavaScript SDK를 사용하여 라이브러리와 생성된 코드를 가져옵니다.
JavaScript SDK를 사용하여 쿼리 및 변이에 대한 호출을 구현합니다.
JavaScript SDK로 SQL Connect 에뮬레이터를 설정하여 테스트합니다.

Firebase JavaScript SDK로 클라이언트 코드 구현

이 섹션에서는 Firebase JavaScript SDK를 사용하여 클라이언트를 구현하는 방법을 설명합니다.

React 또는 Angular를 사용하는 경우 대체 설정 안내와 프레임워크용 SQL Connect SDK 생성에 관한 추가 문서 링크를 참고하세요.

앱 초기화

먼저 표준 Firebase 시퀀스를 사용하여 앱을 초기화합니다.

initializeApp({...});

생성된 JavaScript SDK 설치

Firebase CLI를 사용하여 앱에서 SQL Connect 생성 SDK를 설정합니다. 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 확장 프로그램을 사용하지 않는 경우 Firebase CLI를 사용하여 생성된 SDK를 최신 상태로 유지할 수 있습니다.

firebase dataconnect:sdk:generate --watch

빌드 파이프라인에서 SDK 생성

Firebase CLI를 사용하여 CI/CD 빌드 프로세스에서 SQL Connect SDK를 생성할 수 있습니다.

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의 쿼리 사용

생성된 코드에는 사전 정의된 쿼리 참조가 이미 포함되어 있습니다. 가져와서 실행하기만 하면 됩니다.

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 쿼리를 통해 액세스할 수 있습니다.

앱의 디자인이 변경되면 지원되는 새 enum 값을 추가할 수 있습니다. 예를 들어 애플리케이션의 수명 주기 후반에 AspectRatio enum에 FULLSCREEN 값을 추가한다고 가정해 보겠습니다.

SQL Connect 워크플로에서는 로컬 개발 도구를 사용하여 쿼리와 SDK를 업데이트할 수 있습니다.

하지만 업데이트된 클라이언트 버전을 출시하기 전에 이전 배포 클라이언트가 중단될 수 있습니다.

복원력 있는 구현 예

열거형 값에 대한 switch 문에 항상 default 브랜치를 추가하거나 열거형 값과 비교하는 if/else if 블록에 else 브랜치를 추가합니다. JavaScript/TypeScript 언어에서 강제하지는 않지만 새 enum 값이 추가되는 경우 클라이언트 코드를 강력하게 만드는 방법입니다.

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 정책이라고 합니다.

캐시된 값만 제공 (CACHE_ONLY)하거나 서버에서 최신 값을 무조건 가져오도록 (SERVER_ONLY) executeQuery()의 개별 호출에 지정할 수도 있습니다.
```
await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
```
```
await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
```
subscribe()를 호출하면 maxAge 설정과 관계없이 캐시된 콘텐츠가 있는 경우 항상 즉시 반환됩니다. executeQuery()에 대한 후속 호출은 구성된 maxAge에 따라 리스너에게 알립니다.

SDK의 데이터 유형

SQL Connect 서버는 일반적인 GraphQL 데이터 유형을 나타냅니다. 이는 SDK에서 다음과 같이 표현됩니다.

SQL Connect 유형	TypeScript
타임스탬프	문자열
날짜	문자열
UUID	문자열
Int64	문자열
Double	숫자
부동 소수점 수	숫자

TanStack으로 React 및 Angular SDK 생성

Firebase SQL Connect는 Invertase의 파트너가 제공하는 라이브러리인 TanStack Query Firebase를 사용하여 React 및 Angular용 후크가 있는 생성된 SDK를 제공합니다.

이 라이브러리는 애플리케이션에서 Firebase를 사용하여 비동기 작업을 처리하는 작업을 크게 간소화하는 후크 세트를 제공합니다.

TanStack에는 자체 클라이언트 측 캐싱 및 실시간 구독이 구현되어 있으며, 이는 SQL Connect의 기본 제공 실시간 지원과 함께 작동할 수 있지만 약간의 어려움이 있습니다. TanStack 기반 바인딩 또는 SQL Connect의 내장 실시간 지원 중 하나를 사용하는 것이 좋습니다. 둘 다는 안 됩니다.

SQL Connect 자체 실시간 구현에는 TanStack 바인딩에 비해 몇 가지 장점이 있습니다.

정규화된 캐싱: SQL Connect는 정규화된 캐싱을 구현하여 쿼리 수준 캐싱에 비해 데이터 일관성과 메모리 및 네트워크 효율성을 개선합니다. 정규화된 캐싱을 사용하면 앱의 한 영역에서 항목이 업데이트될 경우 해당 항목을 사용하는 다른 영역에서도 업데이트됩니다.
원격 무효화: SQL Connect는 구독된 모든 기기에서 캐시된 항목을 원격으로 무효화할 수 있습니다.

앱 초기화

먼저 모든 Firebase 웹 앱과 마찬가지로 표준 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

React 또는 Angular SDK 생성

앞서 설명한 표준 웹 SDK와 마찬가지로 Firebase 도구는 스키마와 작업을 기반으로 SDK를 자동으로 생성합니다.

프로젝트에 React 또는 Angular를 방금 추가한 경우 firebase init dataconnect:sdk를 다시 실행하여 생성된 SDK를 재구성하여 추가 프레임워크 바인딩을 포함하세요.

라이브러리 가져오기

React 또는 Angular 클라이언트 코드를 초기화하는 데 필요한 가져오기는 일반 SQL Connect 가져오기, 일반 TanStack 가져오기, JS 및 React 생성 SDK의 특정 가져오기 등 네 가지가 있습니다.

일반 가져오기에 포함된 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의 메서드를 통합할 수 있습니다.

다음 스니펫에서 생성된 SDK의 React용 use 접두사가 붙은 메서드 useListAllMovies와 Angular용 inject 접두사가 붙은 메서드 injectListAllMovies를 확인하세요.

React

생성된 SDK의 모든 작업(쿼리 및 변이)은 TanStackQuery 바인딩을 호출합니다.

호출을 쿼리하고 TanStack useDataConnectQuery 후크를 반환합니다.
변형은 TanStack useDataConnectMutation 후크를 호출하고 반환합니다.

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 확장 프로그램을 사용하지 않는 경우 Firebase CLI를 사용하여 생성된 SDK를 최신 상태로 유지할 수 있습니다.

firebase dataconnect:sdk:generate --watch

빌드 파이프라인에서 SDK 생성

Firebase CLI를 사용하여 CI/CD 빌드 프로세스에서 SQL Connect SDK를 생성할 수 있습니다.

firebase dataconnect:sdk:generate

생성된 웹 SDK 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

클라이언트 개발 워크플로란 무엇인가요?

Firebase JavaScript SDK로 클라이언트 코드 구현

앱 초기화

생성된 JavaScript SDK 설치

프로토타입 제작 중에 SDK 업데이트

빌드 파이프라인에서 SDK 생성

라이브러리 가져오기

JavaScript SDK의 쿼리 사용

SDK 쿼리 메서드 호출

변경사항 구독

열거형 필드 변경사항 처리

복원력 있는 구현 예

JavaScript SDK의 변이 사용

SQL Connect 에뮬레이터에 연결

클라이언트 측 캐싱 사용 설정

SDK의 데이터 유형

TanStack으로 React 및 Angular SDK 생성

앱 초기화

TanStack Query Firebase 패키지 설치

React

Angular

React 또는 Angular SDK 생성

라이브러리 가져오기

React

Angular

React 또는 Angular 클라이언트에서 쿼리 및 변형 사용

React

Angular

React 및 Angular에서 자동 새로고침 쿼리 사용

React

Angular

SQL Connect 에뮬레이터에 연결

React

Angular

프로토타입 제작 중에 SDK 업데이트

빌드 파이프라인에서 SDK 생성

생성된 웹 SDK 사용