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

SDK ứng dụng Firebase SQL Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ ngay 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ế giản đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ SQL Connect của mình. 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 ở phần khác, điều quan trọng cần lưu ý là SQL Connect mã ứng dụng khách không gửi truy vấn và đột biến, đồng thời không thực thi trên máy chủ. Thay vào đó, khi được triển khai, các thao tác SQL 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ũ).

Đó là lý do SQL Connect cung cấp cho bạn một môi trường phát triển và công cụ, giúp bạn tạo nguyên mẫu cho 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 nguyên 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 khách, cả bản cập nhật phía máy chủ và phía máy khách đều sẵn sàng để triển khai.

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

Nếu đã làm theo hướng dẫn Bắt đầu, bạn đã được giới thiệu về quy trình phát triển tổng thể cho SQL Connect. Trong hướng dẫn này, bạn sẽ tìm thấy thông tin chi tiết hơn về cách 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.

Tóm lại, để sử dụng SDK web được tạo trong ứng dụng khách, bạn cần làm theo các bước tiên quyết sau:

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

Sau đó:

  1. Phát triển giản đồ ứng dụng.
  2. Khởi chạy mã ứng dụng bằng SDK JavaScript.
  3. Thiết lập tính năng tạo SDK:
    • Bằng nút Add SDK to app (Thêm SDK vào ứng dụng) trong tiện ích SQL Connect VS Code.
    • Bằng cách cập nhật connector.yaml cho SDK JavaScript.
  4. Nhập thư viện và mã được tạo bằng SDK JavaScript.
  5. Triển khai lệnh gọi đến truy vấn và đột biến bằng SDK JavaScript.
  6. Kiểm thử bằng cách thiết lập trình mô phỏng SQL Connect bằng SDK JavaScript.

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

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

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à đường liên kết đến tài liệu bổ sung về tạo SDK SQL Connect cho khung.

Khởi chạy ứng dụng

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

initializeApp({...});

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

Sử dụng CLI Firebase để thiết lập SDK do SQL Connect tạo trong ứng dụng của bạn. 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 SDK đã tạo.

firebase init dataconnect:sdk

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

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

Nếu bạn đã cài đặt tiện ích SQL Connect VS Code, 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 SQL Connect cho VS Code, bạn có thể dùng Giao diện dòng lệnh (CLI) của Firebase để luôn cập nhật các SDK được 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 Giao diện dòng lệnh (CLI) của Firebase để tạo SDK SQL Connect trong quy trình xây dựng CI/CD.

firebase dataconnect:sdk:generate

Nhập thư viện

Có hai nhóm lệnh nhập cần thiết để khởi chạy mã ứng dụng: lệnh nhập chung SQL Connect và lệnh nhập SDK cụ thể, được tạo.

Lưu ý đối tượng ConnectorConfig có trong các lệnh 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';

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

Mã được 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 lệnh thực thi trên các lớp đó.

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 phím tắt thao tác 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 về các thay đổi

Xem bài viết Nhận thông tin cập nhật theo thời gian thực từ SQL Connect.

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

Giản đồ của ứng dụng có thể chứa các kiểu liệt kê mà truy vấn GraphQL của bạn có thể truy cập.

Khi thiết kế của ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ mới cho enum. 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 làm việc SQL Connect, bạn có thể sử dụng công cụ cho nhà 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ị hỏng.

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. Điều này không được thực thi bằng ngôn ngữ JavaScript/TypeScript, nhưng là cách để làm cho mã ứng dụng khách trở nên mạnh mẽ trong trường hợp các giá trị enum mới được thêm vào.

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ách tương tự 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 SQL Connect

Nếu muốn, 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 vào thực thể SQL Connect, 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 phát hành công khai, hãy đánh dấu là nội dung nhận xét cho các dòng kết nối với trình mô phỏng.

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

SQL Connect có tính năng lưu vào bộ nhớ đệm phía máy khách (không bắt buộc) mà bạn có thể bật bằng cách chỉnh sửa tệp connector.yaml. Khi bạn bật tính năng này, SDK ứng dụng được tạo sẽ lưu các phản hồi truy vấn vào bộ nhớ đệm cục bộ. Việc 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 đưa ra, đồng thời 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 mạng bị gián đoạn.

Để 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 phía máy khách 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: Thời gian tối đa mà một phản hồi được lưu vào bộ nhớ đệm có thể tồn tại 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, 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 thành 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 phản hồi vào bộ nhớ đệm trong bộ nhớ persistent hoặc trong memory. Kết quả được lưu vào bộ nhớ đệm trong bộ nhớ persistent sẽ được giữ lại trong các lần khởi động lại ứng dụng. Trong SDK web, chỉ bộ nhớ memory được hỗ trợ.

Sau khi bạn 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 SDK ứng dụng và tạo lại ứng dụng. Sau khi bạn thực hiện xong, executeQuery() và subscribe() sẽ lưu phản hồi vào bộ nhớ đệm 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. Quá trình này thường diễn ra tự động mà không cần bạ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 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 từng lệnh gọi 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 các giá trị mới từ máy chủ (SERVER_ONLY) mà không cần điều kiện.

    await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
    
    await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
    
  • Khi bạn gọi subscribe(), phương thức này sẽ luôn trả về ngay nội dung đã 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 trình nghe theo maxAge đã định cấu hình.

Các loại dữ liệu trong SDK

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

Loại SQL Connect 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

Tạo SDK React và Angular bằng TanStack

Firebase SQL Connect cung cấp một SDK được tạo sẵn có các hook cho React và Angular bằng cách sử dụng các thư viện có sẵn từ đố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ộ bằng Firebase trong ứng dụng của mình.

TanStack đi kèm với cách triển khai riêng cho tính năng lưu vào bộ nhớ đệm phía máy khách và gói thuê bao theo thời gian thực. Cách triển khai này có thể hoạt động cùng với tính năng hỗ trợ theo thời gian thực tích hợp sẵn của SQL Connect, nhưng sẽ gặp một số khó khăn. Bạn nên sử dụng các liên kết dựa trên TanStack hoặc hỗ trợ theo thời gian thực tích hợp sẵn của SQL Connect, nhưng không phải cả hai.

Xin lưu ý rằng việc triển khai theo thời gian thực của SQL Connect có một số ưu điểm so với các liên kết TanStack:

  • Lưu vào bộ nhớ đệm chuẩn hoá: SQL Connect triển khai tính năng lưu vào bộ nhớ đệm chuẩn hoá, giúp cải thiện tính nhất quán của dữ liệu cũng như hiệu quả của bộ nhớ và mạng so với việc lưu vào bộ nhớ đệm ở cấp truy vấn. Với tính năng lưu vào bộ nhớ đệm chuẩn hoá, nếu một thực thể cập nhật trong một khu vực của ứng dụng, thì thực thể đó cũng sẽ cập nhật ở các khu vực khác sử dụng thực thể đó.
  • Vô hiệu hoá từ xa: SQL Connect có thể vô hiệu hoá từ xa các thực thể được lưu vào bộ nhớ đệm trên tất cả thiết bị đã đăng ký.

Khởi chạy ứng dụng

Trước tiên, giống như mọi ứng dụng web Firebase, hãy khởi chạy ứng dụng của bạn bằng trình tự Firebase tiêu chuẩn.

initializeApp({...});

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

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

Thể hiện cảm xúc

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 sẽ 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 thêm các liên kết khung bổ sung.

Nhập thư viện

Có 4 nhóm lệnh nhập cần thiết để khởi chạy mã ứng dụng React hoặc Angular: lệnh nhập SQL Connect chung, lệnh nhập TanStack chung và lệnh nhập cụ thể cho SDK được tạo bằng JS và React.

Lưu ý loại ConnectorConfig có trong các lệnh nhập chung.

Thể hiện cảm xúc

// 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 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 useListAllMovies có tiền tố use cho React và phương thức injectListAllMovies có tiền tố inject cho Angular, cả hai đều từ SDK được tạo.

Thể hiện cảm xúc

Tất cả các thao tác như vậy trong SDK được tạo (cả truy vấn và đột biến) đều gọi các liên kết 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;
  })
]

Sử dụng truy vấn tự động tải lại bằng 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.

Thể hiện cảm xúc

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 SQL Connect

Nếu muốn, 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ể SQL Connect vào hook đã tạo, như sau:

Thể hiện cảm xúc

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 phát hành công khai, hãy đánh dấu là nội dung nhận xét cho các dòng kết nối với trình mô phỏng.

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

Nếu bạn đã cài đặt tiện ích SQL Connect VS Code, 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 SQL Connect cho VS Code, bạn có thể dùng Giao diện dòng lệnh (CLI) của Firebase để luôn cập nhật các SDK được 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 Giao diện dòng lệnh (CLI) của Firebase để tạo SDK SQL Connect trong quy trình xây dựng CI/CD.

firebase dataconnect:sdk:generate