使用 React 開始使用 Firebase Data Connect

在本快速入門教學中，您將建立並部署一個小型範例資料庫，並從 React 前端存取它。

事前準備

要完成此快速入門指南，您需要以下物品：

  • 具備 NPM 的 Node.js 環境。
  • 一個谷歌帳號。

教學課程

教學課程

1. 建立新的 Firebase 專案

首先，請在 Firebase 控制台中建立新的 Firebase 專案。然後將專案升級至 Blaze 方案。

2. 初始化您的專案

建立新目錄，並在其中初始化 Firebase 專案。系統提示時，請選擇下列選項：

  • 選擇您在上一個步驟中建立的專案。
  • 請勿使用 Gemini 建立結構定義 (在本教學課程中，您將使用預先建構的結構定義範例)。
  • 建立新的 Cloud SQL 執行個體。
  • 建立 React 範本。
 
npx -y firebase-tools@latest login --reauth
npx -y firebase-tools@latest init dataconnect

3. 查看 GraphQL 定義範例

在 Data Connect 中，您可以使用 GraphQL 定義所有資料庫結構定義和作業。初始化專案時，Firebase CLI 會建立一些範例定義，協助您開始使用。

 dataconnect/schema/schema.gql (摘錄) 
type Movie @table {
  title: String!
  imageUrl: String!
  genre: String
}

type MovieMetadata @table {
  movie: Movie! @unique
  rating: Float
  releaseYear: Int
  description: String
}
 dataconnect/example/queries.gql (excerpt) 
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

4. 部署結構定義和作業

無論何時對資料庫架構、查詢或變更進行更改，都必須部署這些變更才能使變更在資料庫中生效。

 
npx -y firebase-tools@latest \
    deploy --only dataconnect

5. 使用範例資料初始化資料庫

這些種子資料將在您測試範例應用程式時提供參考。請注意，在此步驟中，您將執行任意 GraphQL 語句，這在管理任務中是允許的。

 
npx -y firebase-tools@latest \
    dataconnect:execute dataconnect/seed_data.gql

6. 產生 JavaScript 用戶端 SDK

這項指令會使用 GraphQL 定義產生專為資料庫設計的 JavaScript 程式庫，並提供完整的型別定義。您可以在用戶端應用程式中使用這個程式庫，執行所有資料庫作業。

您可以在 connector.yaml 中新增定義，為多個平台產生程式庫，包括 Android 適用的 Kotlin、iOS 適用的 Swift 和 Flutter。

 
npx -y firebase-tools@latest \
    dataconnect:sdk:generate
 自動產生的 React SDK (節錄) 
export interface ListMoviesData {
  movies: ({
    id: UUIDString;
    title: string;
    imageUrl: string;
    genre?: string | null;
  } & Movie_Key)[];
}

export function useListMovies(
  options?: useDataConnectQueryOptions&<ListMoviesData>
): UseDataConnectQueryResult&<ListMoviesData, undefined>;

7. 建立一個 Web 應用程式

執行這些指令，將新的網頁應用程式新增至 Firebase 專案。

 
npx -y firebase-tools@latest \
    apps:create web react-example
npx -y firebase-tools@latest \
    apps:sdkconfig web -o web-app/src/firebase-config.json
cd web-app ; npm i firebase ; cd ..

8. 編寫一個 React 用戶端範例

將 web-app/src/App.jsx 的內容替換為這個簡單的 React 應用程式。

請注意，該應用程式使用生成的 SDK 中的函數完成必要的資料庫存取。為 React 產生的 SDK 會使用 TanStack Query 處理狀態管理。

 
import { initializeApp } from 'firebase/app';
import firebaseConfig from './firebase-config.json';
import {
  QueryClient,
  QueryClientProvider
} from '@tanstack/react-query';

import { useListMovies } from '@dataconnect/generated/react';
import './App.css';

const app = initializeApp(firebaseConfig);
const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Movies />
    </QueryClientProvider>
  );
}

function Movies() {
  const { isLoading, data } = useListMovies();
  if (isLoading) {
    return <h1>...</h1>
  }
  return (
    <>
      {data?.movies.map(
        movie => <h1 key={movie.id}>{movie.title}</h1>
      )}
    </>
  );
}

export default App;

9. 試用網頁應用程式

啟動開發伺服器，查看實際運作的範例應用程式。

 
npm run dev

後續步驟

試試 Visual Studio Code 擴充功能

使用 Data Connect 進行開發時，強烈建議使用 Visual Studio Code 擴充功能。即使您不使用 Visual Studio Code 做為主要開發環境，擴充功能仍提供多項功能，讓結構定義和作業開發更便利：

  • GraphQL 語言伺服器，提供專屬於 Data Connect 的語法檢查和自動完成建議
  • 程式碼行中的 CodeLens 按鈕，可讓您從結構定義檔案讀取及寫入資料，並從作業定義執行查詢和突變。
  • 自動將產生的 SDK 與 GraphQL 定義保持同步。
  • 簡化本機模擬器設定。
  • 簡化部署至實際工作環境的作業。

使用 Data Connect 模擬器進行本地開發

雖然本教學示範如何將 Data Connect 模式和操作直接部署到生產環境，但在積極開發應用程式的過程中，您可能不希望變更生產資料庫。因此，請設定 Data Connect 模擬器，並在其上進行開發工作，而不是直接在生產環境中進行開發。此模擬器會設定一個本地 PGlite 實例，其行為類似於 CloudSQL 上的即時 Postgres 實例。

瞭解如何為應用程式編寫結構定義和作業

使用 Data Connect 開發應用程式時，架構和操作的設計是您將完成的首要且最重要的開發任務之一。

  • Firebase 控制台中的 Gemini 是一項 AI 工具，可根據應用程式的自然語言說明生成 Data Connect 結構定義。如果您從未處理過關聯式資料庫，這項工具可協助您快速入門。
  • 或者，您也可以直接使用 GraphQL 撰寫資料庫結構定義、查詢和異動。 請先前往「設計架構」Data Connect頁面，然後繼續前往後續頁面，瞭解如何編寫作業。