使用 React 開始使用 Firebase Data Connect

在本快速入門導覽課程中，您將建立及部署小型資料庫範例，並從 React 前端存取該資料庫。

事前準備

如要完成本快速入門導覽課程，請務必符合以下條件：

  • 具備 NPM 的 Node.js 環境。
  • Google 帳戶。

教學課程

教學課程

1. 建立新的 Firebase 專案

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

2. 初始化您的專案

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

  • 選擇您在上一個步驟中建立的專案。
  • 請勿使用 Gemini 建立結構定義 (在本教學課程中，您將使用預先建構的結構定義範例)。
  • 建立新的 Cloud SQL 執行個體。
  • 建立 React 範本。
 
mkdir myproj ; cd myproj
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. 設定網頁應用程式

執行這些指令，將新的網頁應用程式新增至 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 \
            @tanstack/react-query \
            @tanstack-query-firebase/react

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頁面，然後繼續瀏覽後續頁面，瞭解如何編寫作業。