Sử dụng SDK web đã tạo

SDK ứng dụng Firebase Data Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ trực tiếp từ một ứng dụng Firebase. Bạn tạo một SDK ứng dụng tuỳ chỉnh song song khi thiết kế các lược đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ Data Connect. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic ứng dụng.

Như chúng tôi đã đề cập ở nơi khác, điều quan trọng cần lưu ý là Data Connect các truy vấn và đột biến không được mã ứng dụng gửi và thực thi trên máy chủ. Thay vào đó, khi được triển khai, các hoạt động Data Connect sẽ được lưu trữ trên máy chủ như Cloud Functions. Điều này có nghĩa là bạn cần triển khai các thay đổi tương ứng ở phía máy khách để tránh làm gián đoạn người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ hơn).

Đó là lý do Data Connect cung cấp cho bạn một môi trường và công cụ dành cho nhà phát triển, cho phép bạn tạo mẫu các lược đồ, truy vấn và đột biến được triển khai trên máy chủ. Công cụ này cũng tự động tạo SDK phía máy khách trong khi bạn tạo mẫu.

Khi bạn lặp lại các bản cập nhật cho dịch vụ và ứng dụng, cả bản cập nhật phía máy chủ và phía ứng dụng đều sẵn sàng triển khai.

Quy trình phát triển ứng dụng là gì?

Nếu bạn đã làm theo phần Bắt đầu, thì bạn đã được giới thiệu về quy trình phát triển tổng thể cho Data Connect. Trong hướng dẫn này, bạn sẽ tìm thấy thông tin chi tiết hơn về việc tạo SDK web từ giản đồ và làm việc với các truy vấn và đột biến của ứng dụng.

Bạn có thể tìm hiểu về cách phát triển ứng dụng bằng kho lưu trữ ứng dụng khởi động nhanh và tạo một ứng dụng có đầy đủ tính năng bằng cách làm theo Data Connect lớp học lập trình của chúng tôi dành cho web.

Tóm lại, để sử dụng SDK web đã tạo trong ứng dụng, bạn sẽ làm theo các bước điều kiện tiên quyết sau:

1. Thêm Firebase vào ứng dụng web.

Sau đó:

1. Phát triển lược đồ ứng dụng.
2. Khởi động mã ứng dụng bằng SDK JavaScript hoặc React hoặc Angular libraries.
3. Đối với React và Angular, hãy cài đặt các gói Tanstack Query

4. Thiết lập quá trình tạo SDK:

   • Bằng nút Add SDK to app (Thêm SDK vào ứng dụng) trong tiện ích Data Connect VS Code
   • Bằng cách cập nhật connector.yaml cho SDK JavaScript hoặc React hoặc Angular.

5. Nhập thư viện và mã đã tạo bằng SDK JavaScript hoặc React hoặc Angular.

6. Triển khai các lệnh gọi đến truy vấn và đột biến bằng SDK JavaScript, hoặc React hoặc Angular.

7. Kiểm thử bằng cách thiết lập trình mô phỏng Data Connect bằng SDK JavaScript hoặc React hoặc Angular.

Triển khai mã ứng dụng bằng Firebase JavaScript SDK

Phần này trình bày cách bạn có thể triển khai ứng dụng bằng Firebase JavaScript SDK.

Nếu bạn đang sử dụng React hoặc Angular, hãy xem hướng dẫn thiết lập thay thế và các đường liên kết đến tài liệu bổ sung về cách tạo Data Connect SDK cho các khung.

Khởi động ứng dụng

Trước tiên, hãy khởi động ứng dụng bằng trình tự Firebase tiêu chuẩn .

initializeApp({...});

Cài đặt SDK JavaScript đã tạo

Sử dụng Firebase CLI để thiết lập các SDK đã tạo của Data Connect trong ứng dụng. Lệnh init sẽ phát hiện tất cả ứng dụng trong thư mục hiện tại và tự động cài đặt các SDK đã tạo.

firebase init dataconnect:sdk

Kết nối ứng dụng của bạn với dịch vụ 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);

Cập nhật SDK trong khi tạo mẫu

Nếu bạn đã cài đặt tiện ích Data Connect VS Code, thì tiện ích này sẽ luôn cập nhật các SDK đã tạo.

Nếu không sử dụng tiện ích Data Connect VS Code, bạn có thể sử dụng Firebase CLI để luôn cập nhật các SDK đã tạo.

firebase dataconnect:sdk:generate --watch

Tạo SDK trong quy trình xây dựng

Bạn có thể sử dụng Firebase CLI để tạo Data Connect SDK trong các quy trình xây dựng CI/CD.

firebase dataconnect:sdk:generate

Nhập thư viện

Bạn cần có 2 bộ dữ liệu nhập để khởi động mã ứng dụng: dữ liệu nhập chung Data Connect và dữ liệu nhập SDK cụ thể đã tạo.

Lưu ý đối tượng ConnectorConfig có trong dữ liệu nhập chung.

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

Lưu ý: SDK ứng dụng JavaScript đã tạo sử dụng cùng tên cho các giao diện và hoạt động như SDK quản trị Node.js đã tạo. Hãy nhớ nhập đúng thư viện cho nền tảng của bạn. Nếu cần sử dụng cả hai thư viện trong cùng một tệp, hãy sử dụng bí danh nhập hoặc nhập theo không gian tên cho một hoặc cả hai thư viện.

import { listMovies as adminListMovies } from '@dataconnect/admin-generated';
Or:
import * as Admin from '@dataconnect/admin-generated';

Sử dụng các truy vấn từ SDK JavaScript

Mã đã tạo sẽ đi kèm với các Tham chiếu truy vấn được xác định trước. Bạn chỉ cần nhập và gọi thực thi trên các tham chiếu đó.

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

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

Gọi phương thức truy vấn SDK

Dưới đây là ví dụ về cách sử dụng các hàm lối tắt hành động này:

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

Đăng ký nhận thông báo khi có thay đổi

Bạn có thể đăng ký nhận thông báo khi có thay đổi (thông báo này sẽ cập nhật bất cứ lúc nào bạn thực thi một truy vấn).

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`

Xử lý các thay đổi đối với trường liệt kê

Lược đồ của ứng dụng có thể chứa các giá trị liệt kê, mà truy vấn GraphQL có thể truy cập.

Khi thiết kế ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ cho enum mới. Ví dụ: giả sử sau này trong vòng đời của ứng dụng, bạn quyết định thêm giá trị FULLSCREEN vào enum AspectRatio.

Trong quy trình Data Connect, bạn có thể sử dụng công cụ phát triển cục bộ để cập nhật các truy vấn và SDK.

Tuy nhiên, trước khi bạn phát hành phiên bản cập nhật của ứng dụng, các ứng dụng cũ đã triển khai có thể bị gián đoạn.

Ví dụ về cách triển khai linh hoạt

Luôn thêm nhánh default vào câu lệnh switch trên các giá trị enum hoặc nhánh else vào khối if/else if so sánh với các giá trị enum. Ngôn ngữ JavaScript/TypeScript không bắt buộc điều này, nhưng đây là cách để tạo mã ứng dụng mạnh mẽ trong trường hợp thêm các giá trị enum mới.

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

Sử dụng các đột biến từ SDK JavaScript

Bạn có thể truy cập vào các đột biến theo cùng một cách như truy vấn.

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

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

Kết nối với trình mô phỏng Data Connect

Bạn có thể kết nối với trình mô phỏng bằng cách gọi connectDataConnectEmulator rồi truyền thực thể Data Connect vào, như sau:

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

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Để chuyển sang tài nguyên sản xuất, hãy nhận xét các dòng để kết nối với trình mô phỏng.

Lưu ý: Bạn chỉ cần gọi getDataConnect nếu muốn kết nối với trình mô phỏng Data Connect. Nếu không, SDK đã tạo sẽ tự động tạo một thực thể của đối tượng DataConnect cho bạn.

Triển khai mã ứng dụng cho React và Angular

Firebase Data Connect cung cấp một SDK đã tạo với các hook cho React và Angular bằng cách sử dụng các thư viện có sẵn từ các đối tác của chúng tôi tại Invertase, TanStack Query Firebase.

Thư viện này cung cấp một tập hợp các hook giúp bạn dễ dàng xử lý các tác vụ không đồng bộ với Firebase trong ứng dụng.

Khởi động ứng dụng

Trước tiên, giống như bất kỳ ứng dụng web Firebase nào, hãy khởi động ứng dụng bằng trình tự Firebase tiêu chuẩn.

initializeApp({...});

Cài đặt các gói TanStack Query Firebase

cài đặt các gói cho TanStack Query trong dự án của bạn.

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

Tạo SDK React hoặc Angular

Giống như SDK web tiêu chuẩn (như mô tả ở trên), công cụ Firebase xử lý việc tự động tạo SDK dựa trên giản đồ và hoạt động của bạn.

Nếu bạn vừa thêm React hoặc Angular vào dự án, hãy chạy lại firebase init dataconnect:sdk để định cấu hình lại các SDK đã tạo nhằm đưa các liên kết khung bổ sung vào.

Nhập thư viện

Bạn cần có 4 bộ dữ liệu nhập để khởi động mã ứng dụng React hoặc Angular client code: dữ liệu nhập Data Connect chung, dữ liệu nhập TanStack chung, và dữ liệu nhập cụ thể cho các SDK đã tạo của JS và React.

Lưu ý loại ConnectorConfig có trong dữ liệu nhập chung.

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

Sử dụng các truy vấn và đột biến trong ứng dụng React hoặc Angular

Sau khi thiết lập xong, bạn có thể kết hợp các phương thức từ SDK đã tạo.

Trong đoạn mã sau, hãy lưu ý phương thức có tiền tố use-useListAllMovies cho React và phương thức có tiền tố inject-injectListAllMovies cho Angular, cả hai đều từ SDK đã tạo.

React

Tất cả các hoạt động như vậy trong SDK đã tạo (cả truy vấn và đột biến) đều gọi các liên kết TanStackQuery:

• Truy vấn gọi và trả về hook useDataConnectQueryTanStack
• Đột biến gọi và trả về hook useDataConnectMutationTanStack

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

Lưu ý: ng add @angular/fire sẽ tự động thực hiện việc này cho bạn, nhưng nếu bạn chọn thiết lập thủ công, bạn có thể thực hiện bằng đoạn mã sau:

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

Sử dụng các truy vấn tải lại tự động với React và Angular

Bạn có thể định cấu hình các truy vấn để tự động tải lại khi dữ liệu thay đổi.

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

Kết nối với trình mô phỏng Data Connect

Bạn có thể kết nối với trình mô phỏng bằng cách gọi connectDataConnectEmulator rồi truyền thực thể Data Connect vào hook đã tạo, như sau:

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

Để chuyển sang tài nguyên sản xuất, hãy nhận xét các dòng để kết nối với trình mô phỏng.

Lưu ý: Bạn chỉ cần gọi getDataConnect nếu muốn kết nối với trình mô phỏng Data Connect. Nếu không, SDK đã tạo sẽ tự động tạo một thực thể của đối tượng DataConnect cho bạn.

Bật tính năng lưu vào bộ nhớ đệm phía máy khách

Data Connect có một tính năng lưu vào bộ nhớ đệm phía máy khách không bắt buộc. Bạn có thể bật tính năng này bằng cách chỉnh sửa tệp connector.yaml. Khi tính năng này được bật, các SDK ứng dụng đã tạo sẽ lưu vào bộ nhớ đệm cục bộ các phản hồi truy vấn. Điều này có thể làm giảm số lượng yêu cầu cơ sở dữ liệu mà ứng dụng của bạn thực hiện và cho phép các phần phụ thuộc vào cơ sở dữ liệu của ứng dụng hoạt động khi kết nối mạng bị gián đoạn.

Nhà phát triển React, Next.js và Angular: SDK React và Angular của Data Connect xử lý việc lưu vào bộ nhớ đệm bằng các thư viện TanStack. Các thư viện này không tương thích với tính năng lưu vào bộ nhớ đệm gốc của Data Connect. Nếu sử dụng React hoặc Angular, bạn nên không bật tính năng lưu vào bộ nhớ đệm như mô tả trong phần này mà thay vào đó, hãy tiếp tục sử dụng tính năng do TanStack cung cấp.

Để bật tính năng lưu vào bộ nhớ đệm phía máy khách, hãy thêm cấu hình lưu vào bộ nhớ đệm của ứng dụng vào cấu hình trình kết nối:

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

Cấu hình này có 2 tham số, cả hai đều không bắt buộc:

• maxAge: Tuổi tối đa mà phản hồi được lưu vào bộ nhớ đệm có thể có trước khi SDK ứng dụng tìm nạp các giá trị mới. Ví dụ: "0", "30s", "1h30m".

  Giá trị mặc định cho maxAge là 0, có nghĩa là các phản hồi được lưu vào bộ nhớ đệm, nhưng SDK ứng dụng sẽ luôn tìm nạp các giá trị mới. Các giá trị được lưu vào bộ nhớ đệm sẽ chỉ được sử dụng khi CACHE_ONLY được chỉ định cho executeQuery() và kết quả ban đầu được trả về từ subscribe().

• storage: Bạn có thể định cấu hình SDK ứng dụng để lưu vào bộ nhớ đệm các phản hồi trong bộ nhớ persistent hoặc trong memory. Kết quả được lưu vào bộ nhớ đệm trong bộ nhớ persistent sẽ tồn tại trong các lần khởi động lại ứng dụng. Trong SDK web, chỉ hỗ trợ bộ nhớ memory.

Sau khi cập nhật cấu hình lưu vào bộ nhớ đệm của trình kết nối, hãy tạo lại các SDK ứng dụng và xây dựng lại ứng dụng. Sau khi bạn thực hiện xong, executeQuery() và subscribe() sẽ lưu vào bộ nhớ đệm các phản hồi và sử dụng các giá trị được lưu vào bộ nhớ đệm theo chính sách mà bạn đã định cấu hình. Điều này thường xảy ra tự động mà bạn không cần thực hiện thêm bước nào; tuy nhiên, hãy lưu ý những điều sau:

• Hành vi mặc định của executeQuery() như mô tả ở trên: nếu một kết quả được lưu vào bộ nhớ đệm cho một truy vấn và giá trị được lưu vào bộ nhớ đệm không cũ hơn maxAge, thì hãy sử dụng giá trị được lưu vào bộ nhớ đệm. Hành vi mặc định này được gọi là chính sách PREFER_CACHE.

  Bạn cũng có thể chỉ định cho các lệnh gọi riêng lẻ của executeQuery() để chỉ phân phát các giá trị được lưu vào bộ nhớ đệm (CACHE_ONLY) hoặc để tìm nạp vô điều kiện các giá trị mới từ máy chủ (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Khi bạn gọi subscribe(), hàm này sẽ luôn trả về ngay nội dung được lưu vào bộ nhớ đệm nếu có, bất kể chế độ cài đặt maxAge. Các lệnh gọi tiếp theo đến executeQuery() sẽ thông báo cho người nghe theo maxAge đã định cấu hình.

Kiểu dữ liệu trong SDK

Máy chủ Data Connect đại diện cho các kiểu dữ liệu GraphQL phổ biến. Các kiểu dữ liệu này được biểu thị trong SDK như sau.

Data Connect Kiểu	TypeScript
Dấu thời gian	chuỗi
Ngày	chuỗi
mã nhận dạng duy nhất (UUID)	chuỗi
Int64	chuỗi
Giường đôi	Số tàu
Nổi	Số tàu

Cập nhật SDK trong khi tạo mẫu

Nếu bạn đã cài đặt tiện ích Data Connect VS Code, thì tiện ích này sẽ luôn cập nhật các SDK đã tạo.

Nếu không sử dụng tiện ích Data Connect VS Code, bạn có thể sử dụng Firebase CLI để luôn cập nhật các SDK đã tạo.

firebase dataconnect:sdk:generate --watch

Tạo SDK trong quy trình xây dựng

Bạn có thể sử dụng Firebase CLI để tạo Data Connect SDK trong các quy trình xây dựng CI/CD.

firebase dataconnect:sdk:generate