首頁 >web前端 >js教程 >如何使用 Encore.ts 和 React 建立即時儀表板

如何使用 Encore.ts 和 React 建立即時儀表板

Linda Hamilton
Linda Hamilton原創
2025-01-08 07:40:411035瀏覽

即時儀表板在各種應用程式中都非常有用,從追蹤網站分析到監控即時財務數據,甚至密切關注物聯網設備。

?在本教程中,我們將向您展示如何使用 ReactEncore.ts 建立一個。您將學習建立一個可即時傳輸更新的動態儀表板,使您能夠做出快速、明智的決策。

要了解我們將要建立的內容,請在此處查看成品的 GIF 和原始程式碼。讓我們深入了解一下!

How to Build a Real-Time Dashboard with Encore.ts and React

先決條件

在我們開始之前,請確保您的電腦上安裝了這些東西

  • Node.js(v18 或更高版本)
  • Npm(v10 或更高版本)

什麼以及為什麼安可

Encore.ts 是一個開源框架,可協助您使用 TypeScript 建立後端,確保類型安全。它輕量且快速,因為它沒有任何 NPM 依賴項。

在開發分散式後端系統時,往往很難在本地複製生產環境,導致開發者體驗不佳。您最終可能會處理很多複雜性,只是為了讓事情以合理的方式在本地運行,這需要時間來專注於建立實際的應用程式。 Encore.ts 透過提供建構分散式系統的完整工具集來解決這個問題,包括:

  • 本地環境與雲端匹配
  • 跨服務類型安全
  • 型別感知基礎設施
  • 自動 API 文件與客戶端
  • 本地測試追蹤
  • 還有更多

好的,我們討論了 Encore 是什麼以及它如何幫助我們建立後端服務。在下一節中,我們將在本機安裝 Encore 並開始建置。

安裝安可

要使用 Encore,我們需要安裝 CLI,這使得建立和管理本機環境變得非常容易。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

創建 Encore 應用程式

建立 Encore 應用程式非常簡單,只需執行命令即可。

encore app create

您將被問到以下問題,因此請相應地選擇您的答案。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

應用程式建立後,您可以在 encore.app 中驗證應用程式設定

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

好的,我們已經創建了 Encore 應用程式。我們下一節將討論 Encore 中的 Streaming API。

什麼是Encore 中的串流 API

在討論串流 API 之前,我們先討論一下 Encore 中的 API。在 Encore 中建立 API 端點非常容易,因為它提供了 encore.dev/api 模組中的 api 函數來定義類型安全的 API 端點。 Encore 也內建了傳入請求的驗證。 API 的核心是具有請求和回應架構結構的簡單非同步函數。 Encore 會在編譯時解析程式碼並產生樣板,因此您只需專注於定義 API。

流 API 是允許您向應用程式發送資料和從應用程式接收資料的 API,從而允許雙向通訊。

Encore 提供三種類型的流,每種流用於不同的資料流方向:

  • StreamIn:使用它將資料串流傳輸到您的服務中。
  • StreamOut:使用它從您的服務中串流資料。
  • StreamInOut:使用它可以將資料流入和流出您的服務。

當您連線到串流 API 端點時,用戶端和伺服器使用 HTTP 請求執行握手。如果伺服器接受此請求,則會為用戶端和 API 處理程序建立一個串流。這個流實際上是一個允許發送和接收訊息的 WebSocket。

好吧,現在我們知道了 Encore 中的 API 和 Streaming API,讓我們在下一節中使用 Streaming API 端點建立儀表板服務來即時儲存和檢索資料。

建立儀表板服務

讓我們建立一個儀表板服務,我們將在其中定義銷售 API 以將資料傳入和傳出我們的銷售儀表板。

在根層級建立一個名為dashboard的資料夾,然後新增一個 encore.service.ts 檔。此文件將告訴 Encore 將儀表板資料夾及其子資料夾視為服務的一部分。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

然後將以下程式碼加入 encore.service.ts 檔案。我們從 encore.dev/service 導入 Service 類,並使用“dashboard”作為服務名稱建立它的實例。

encore app create

現在讓我們建立一個儀表板.ts 檔案並設定銷售 API。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

How to Build a Real-Time Dashboard with Encore.ts and React

在設定API之前,我們先設定資料庫來儲存銷售資料。我們將使用 encore.dev/storage/sqldb 模組中的 SQLDatabase 來建立 Encore 支援的 PostgreSQL 資料庫。

我們需要將 SQL 定義為遷移,當我們執行指令 encore run 時,Encore 將會拾取該遷移。

在儀表板資料夾中建立一個名為migrations的資料夾,然後建立一個名為1_first_migration.up.sql的檔案。確保遵循命名約定,以 number_ 開頭並以 up.sql 結尾。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

在這裡,我們建立一個名為 sales 的表,包含四個欄位:

  • id:自增,為主鍵
  • 促銷:促銷標題
  • 總計:銷售總額
  • 日期:銷售日期

接下來,將以下程式碼加入dashboard.ts 檔案中。

encore app create

在這裡,我們建立一個 SQLDatabase 實例,將其命名為儀表板並指定遷移資料夾的路徑。

我們正在使用 postgres 套件來監聽並通知資料庫中的變更。

接下來,新增這些類型和記憶體中的映射來保存連接的流(websocket 連線)。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

接下來,讓我們設定一個銷售流端點,以便在發生新銷售時發送更新。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

這裡我們使用 api.streamOut 函數來定義 API,它接受兩個參數:

  • 流選項:
    • expose:設定為 true 以便端點公開,否則為 false
    • auth:設定為 true 以通過驗證保護端點,否則為 false
    • 路徑:/sale
  • 函數:需要兩個參數
    • 握手:用於建立流連接
    • stream:流物件

我們在connectedStreams映射中保持連接,並使用Postgres客戶端監聽new_sale通道。當新的銷售發生時,我們會將更新傳送到所有連線的流。

接下來,我們將定義新增銷售 API 端點,我們從請求正文中取得銷售數據,並使用資料庫實例插入新的銷售記錄。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

在這裡,將新的銷售記錄新增至資料庫後,我們使用 Postgres 用戶端向 new_sale 通道發送包含銷售資料的通知。這樣,new_sale 頻道偵聽器就會收到通知並且可以採取行動。

最後,讓我們設定 API 端點以傳回銷售記錄清單。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

這裡,我們使用db實例方法查詢來取得數據,然後處理它以列表的形式傳回。

太好了,我們現在已經定義了所有 API 端點。讓我們在下一節中探索 Encore 開發儀表板。

探索開發儀表板

我們有一個帶有資料庫設定的 API 端點,但是我們如何測試和偵錯服務呢?別擔心,因為 Encore 提供了本地開發儀表板,可以讓開發人員的生活更輕鬆並提高生產力。

它包含多種功能來幫助您設計、開發和調試應用程式:

  • Service Catalog 和 API Explorer,可輕鬆對本機後端進行 API 呼叫
  • 分散式跟踪,實現簡單而強大的調試
  • 用於分享知識和回答問題的自動 API 文件
  • Encore Flow 用於視覺化您的微服務架構

當您更改應用程式時,所有這些功能都會即時更新。

要存取儀表板,請使用 encore run 啟動 Encore 應用程序,它會自動開啟。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

這就是儀表板的外觀,您可以在投入生產之前在本地測試所有內容。這使得測試微服務架構變得更加容易,而無需外部工具。

How to Build a Real-Time Dashboard with Encore.ts and React

以下是使用 API 瀏覽器新增銷售的範例。當您按一下「呼叫 API」按鈕時,您將收到回應和日誌。右側可以看到請求的痕跡。

How to Build a Real-Time Dashboard with Encore.ts and React

點擊追蹤連結時,您將獲得資料庫查詢、回應和日誌等詳細資訊。

How to Build a Real-Time Dashboard with Encore.ts and React

好了,這就是本機開發儀表板的全部內容。您可以探索其他選項,例如服務目錄、流程等。在下一節中,我們將產生具有 TypeScript 類型安全性的客戶端,以在前端服務(React 應用程式)中使用,以與儀表板服務 API 進行通訊。

產生客戶端

Encore 可以使用 TypeScript 或 JavaScript 產生前端請求客戶端,保持請求/回應類型同步並幫助您無需手動操作即可呼叫 API。

在根目錄下建立一個名為 frontend 的資料夾,然後執行以下指令使用 Vite 設定 React 專案。

encore app create

接下來,在 src 目錄中建立一個 lib 資料夾,新增一個名為 client.ts 的新文件,並將其留空。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

然後,在 package.json 檔案中新增一個名為 gen-client 的新腳本。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

接下來,執行腳本在 src/lib/client.ts 中建立客戶端。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

src/lib/client.ts 檔案應包含產生的程式碼。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

接下來,在lib目錄中建立一個名為getRequestClient.ts的檔案並新增以下程式碼。這將根據環境傳回 Client 實例。

# make sure you are in dashboard folder
touch dashboard.ts

好了,現在我們有了可以在 React 應用程式中使用的客戶端來呼叫儀表板 API。在下一節中,我們將建立前端服務並為即時銷售儀表板建立 UI。

創建前端服務

在上一節中,我們使用 React 應用程式設定了一個前端資料夾,現在我們希望將其設為服務。讓我們建立一個 encore.service.ts 檔案並添加以下程式碼來告訴 Encore 將前端資料夾視為「前端」服務。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

我們有兩個選擇:

  • 分別提供儀表板和前端服務
  • 將所有內容作為一個捆綁包提供(我們將在本教程中使用這種方法)

為了服務 React 應用程序,我們需要在 Encore 中將其建置並作為靜態資產提供。讓我們在前端資料夾中設定 static.ts 檔案。

在 Encore.ts 中提供靜態檔案與常規 API 端點類似,但我們使用 api.static 函數取代。

encore app create

這裡有兩件重要的事情要注意:我們正在傳遞路徑和目錄選項。

  • path: /!path 確保它充當後備路由並且不會與其他端點衝突。
  • dir:./dist 是 React 應用程式的建置版本的目錄。

太好了,靜態端點已設定。現在,讓我們為 React 應用程式安裝一些依賴項

  • 反應路由器-dom
  • uuid
  • 順風CSS
Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

然後使用以下程式碼更新 main.tsx。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

接下來,讓我們設定 Tailwind CSS 並更新一些檔案。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

更改 tailwind.config.js 中的內容部分

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

和帶有以下程式碼的index.css。

# make sure you are in dashboard folder
touch dashboard.ts

現在讓我們為銷售儀表板建立一些元件。

  • SalesTable:以表格顯示銷售資料。
# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

這裡,我們從產生的客戶端匯入類型,以匹配儀表板服務類型並確保類型安全。

  • SalesMetrics:顯示一些銷售數字,例如總銷售額、最低銷售額和平均銷售額。
# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);
  • RoleSelector:為了讓使用者為儀表板選擇角色,我們將顯示兩個選項:
    • 查看者:可以查看銷售儀表板
    • 經理:可以查看並建立新的銷售
# dashboard.ts

...

// Map to hold all connected streams
const connectedStreams: Map<string, StreamOut<Sale>> = new Map();

interface HandshakeRequest {
  id: string;
}

interface Sale {
  sale: string;
  total: number;
  date: string;
}

interface ListResponse {
  sales: Sale[];
}

  • GenerateSales:顯示產生銷售按鈕並包含產生銷售的邏輯。

為了產生銷售額,我們需要一些模擬數據,所以讓我們建立一個 src/constant.ts 檔案並添加模擬數據

# dashboard.ts
...

import { api, StreamOut } from 'encore.dev/api';
import log from 'encore.dev/log';

...

export const sale = api.streamOut<HandshakeRequest, Sale>(
  { expose: true, auth: false, path: '/sale' },
  async (handshake, stream) => {
    connectedStreams.set(handshake.id, stream);

    try {
      await client.listen('new_sale', async function (data) {
        const payload: Sale = JSON.parse(data ?? '');

        for (const [key, val] of connectedStreams) {
          try {
            // Send the users message to all connected clients.
            await val.send({ ...payload });
          } catch (err) {
            // If there is an error sending the message, remove the client from the map.
            connectedStreams.delete(key);
            log.error('error sending', err);
          }
        }
      });
    } catch (err) {
      // If there is an error reading from the stream, remove the client from the map.
      connectedStreams.delete(handshake.id);
      log.error('stream error', err);
    }
  }
);
# dashboard.ts
...
...

export const addSale = api(
  { expose: true, method: 'POST', path: '/sale/add' },
  async (body: Sale & { id: string }): Promise<void> => {
    await db.exec`
      INSERT INTO sales (sale, total, date)
      VALUES (${body.sale}, ${body.total}, ${body.date})`;

    await client.notify(
      'new_sale',
      JSON.stringify({ sale: body.sale, total: body.total, date: body.date })
    );
  }
);

在這裡,我們匯入 getRequestClient,然後從儀表板服務呼叫 addSale 端點。它非常簡單,而且 addSale 是類型安全的,因此如果您嘗試傳遞任何不允許的屬性,您將收到錯誤。

接下來,讓我們建立一個 SalesDashboard 元件來顯示包含銷售指標、近期銷售和歷史銷售的儀表板視圖。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

SalesDashboard 採用一個名為 role 的道具,它決定是否要顯示GenerateSales 元件。

saleStream 將保存活動流引用並且是強類型的。

encore app create

安裝元件時,我們使用儀表板服務的銷售端點建立流連接。然後,我們監聽套接字開啟和關閉事件,並根據這些事件運行適當的邏輯。

我們從 saleStream.current 讀取銷售資料並將其儲存在centreSalesData 狀態中。

當元件卸載時,我們清理並關閉目前流。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

此程式碼使用儀表板服務中的 listSales 端點取得儲存的銷售額,並將其保存在 salesData 狀態中。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

此程式碼計算近期銷售量和歷史銷售數據。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

最後,使用此程式碼更新 App.tsx 檔案。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

這裡,我們根據角色查詢參數是否可用來顯示 SalesDashboard 和 RoleSelector 元件。

現在,讓我們透過在前端根目錄中執行以下命令來建立 React 應用程式。

# make sure you are in dashboard folder
touch dashboard.ts

成功運行指令後,將在前端目錄中建立 dist 資料夾。

太好了,現在在下一部分中,讓我們運行應用程式並從頭到尾對其進行測試。

運行應用程式

運行 encore 應用程式很簡單;只需使用下面的命令即可。

# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

成功執行指令後,您將在終端機中看到以下日誌:

# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);

在瀏覽器中造訪http://127.0.0.1:4000,您將看到以下畫面。

How to Build a Real-Time Dashboard with Encore.ts and React

接下來,在一個選項卡中選擇“檢視器”,在另一個標籤中選擇“管理員”。

  • 觀眾

How to Build a Real-Time Dashboard with Encore.ts and React

  • 經理

How to Build a Real-Time Dashboard with Encore.ts and React

在檢查開發儀表板時,我們建立了一筆銷售記錄,並將其保存在資料庫中,因此在 UI 中也可見。

現在,從經理視圖中,點擊「產生銷售」按鈕,並觀看儀表板上的兩個選項卡即時更新。

How to Build a Real-Time Dashboard with Encore.ts and React

概括

在本教學中,我們使用 React 和 Encore.ts 建立了一個即時銷售儀表板。該應用程式會立即更新新的銷售和庫存商品,有助於快速決策。我們使用開源框架 Encore.ts 來使用 TypeScript 建立後端,以實現安全、流暢的編碼。 Encore 的主要特點是:

  1. 類型安全性:確保所有 API 端點和資料結構都是安全的,減少錯誤並使程式碼更可靠。
  2. Streaming API:允許透過 StreamIn、StreamOut 和 StreamInOut 進行即時資料流,從而實現客戶端和伺服器之間的雙向通訊。
  3. 本地開發儀表板:提供用於測試和偵錯的工具,例如服務目錄、API Explorer 和分散式跟踪,從而提高生產力。
  4. 自動客戶端產生:使用 TypeScript 或 JavaScript 建立前端請求客戶端,保持請求/回應類型一致。
  5. 簡化的微服務:讓您可以建立具有多個服務的應用程序,而無需通常的複雜性,從而提供更簡單的方法來處理微服務。

這些功能結合在一起,可以更輕鬆地建立和管理複雜的應用程序,從而提供出色的開發人員體驗。

相關連結

  • GitHub 上的 Star Encore
  • 尋找此範例的原始程式碼
  • 加入我們的 Discord 社群

以上是如何使用 Encore.ts 和 React 建立即時儀表板的詳細內容。更多資訊請關注PHP中文網其他相關文章!

陳述:
本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn