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

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

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

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

先決條件

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

• 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"
}
</random-id>

好的，我們已經創建了 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

在設定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"
}
</random-id>

這裡我們使用 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

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

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

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

好了，這就是本機開發儀表板的全部內容。您可以探索其他選項，例如服務目錄、流程等。在下一節中，我們將產生具有 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"
}
</random-id>

接下來，執行腳本在 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"
}
</random-id>

接下來，讓我們設定 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>> = new Map();

interface HandshakeRequest {
  id: string;
}

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

interface ListResponse {
  sales: Sale[];
}

</string>

• 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);
    }
  }
);
</handshakerequest>

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

</void>

在這裡，我們匯入 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"
}
</random-id>

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

# 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，您將看到以下畫面。

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

• 觀眾

• 經理

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

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

概括

在本教學中，我們使用 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中文網其他相關文章！