Fabric Apps 專案結構

Fabric Apps 專案採用一致的資料夾配置，方便快速找到資料模型、後端設定和前端程式碼。 本文說明了你在建立專案後最有可能使用的檔案和資料夾。

資料夾配置

當你建立新的 Fabric Apps 專案時，範本會產生以下結構：

your-project/
├── rayfin/
│   ├── data/
│   │   ├── schema.ts
│   │   └── *.ts
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── src/
├── package.json
├── tsconfig.json
└── README.md

關鍵設定檔

rayfin/rayfin.yml

rayfin/rayfin.yml 檔案是你 Fabric Apps 後端的主要設定檔。 它控制在本地開發期間執行哪些服務，並支援環境變數插值以取得動態配置值。

完整範例：

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    expiryInMinutes: 60
    refreshToken:
      lifetimeInDays: 30
    customClaims:
      tenant: "default"
    scopes:
      - read:data
      - write:data
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    password:
      enabled: true
    fabric:
      enabled: false
    passwordless:
      magicLink:
        enabled: false
        expiryMinutes: 15
      smsOtp:
        enabled: false
    email:
      enabled: false
      provider: smtp
      senderName: Rayfin Platform
      verificationTokenExpirationHours: 24
      passwordResetTokenExpirationMinutes: 30
      smtp:
        host: maildev
        port: 1025
        senderEmail: noreply@rayfin.local
        username: ""
        password: ""
        useSsl: false
        useStartTls: false
        webPort: 1080
  data:
    enabled: true
    dialect: mssql
  storage:
    enabled: false
  staticHosting:
    enabled: true
    root: .
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

配置包含以下關鍵欄位：

最上層欄位

Field 類型 Required Description
id string 是的 Project slug 被用作 Docker Compose project 名稱和 Fabric 項目識別碼。
name string 是的 便於人閱讀的專案顯示名稱。
version string 是的 專案版本（semver）。
services object 是的 服務配置區塊。

services.data

Field 類型 預設值 Description
enabled boolean false 啟用資料服務。

services.auth

Field 類型 預設值 Description
enabled boolean false 啟用驗證服務。
expiryInMinutes number — JWT 代幣幾分鐘後到期。
customClaims Record<string, string> — 在已核發的JWT上新增的海關理賠。
scopes string[] — OAuth 範圍（例如， ["read:data", "write:data"]）。
refreshToken.lifetimeInDays number — 代幣壽命以天數刷新。
allowedRedirectUris string[] ["http://localhost:5173"] 允許重新導向 URI 進行認證回撥。

services.auth.password

Field 類型 預設值 Description
enabled boolean true 啟用電子郵件與密碼驗證以進行本地開發

services.auth.fabric

Field 類型 預設值 Description
enabled boolean false 啟用 Fabric 經紀式認證（Microsoft Entra ID SSO）。

services.staticHosting

Field 類型 預設值 Description
enabled boolean false 啟用靜態內容託管。
root string — 前端專案的根目錄（相對於專案根目錄）。
folder string "dist" 包含建置後靜態資產的目錄（相對於 root）。
buildCommand string — 在打包前執行 Shell 指令（例如， npm run build）。
indexDocument string — 為根路徑提供的預設文件（例如 index.html）。

小提示

所有字串值都支援使用 ${VAR} 和 ${VAR:-default} 語法進行環境變數插值。 變數會從 rayfin/.env 和 shell 環境中解析。

Rayfin/.env

rayfin/.env 檔案是選用的環境檔案，用來透過插值為 rayfin.yml 提供值。 不要把秘密提交到你的儲存庫。 請改為建立一個供文件使用的 rayfin/.env.example 檔案，然後將 .env 加入你的 .gitignore 檔案中。

rayfin/tsconfig.json

rayfin/tsconfig.json 檔案是供 Fabric Apps CLI 用來編譯您的實體定義的專案參考 TypeScript 組態檔。 它會擴展你的根tsconfig.json，並覆蓋Fabric 應用程式所需的設定，例如 composite: true 和 Node.js 模組解析度。 你不需要直接編輯這個檔案。

資料模型檔案

Rayfin/Data/*.ts

資料夾裡 rayfin/data/ 的檔案定義了你的實體。 實體是使用 @entity() 修飾的 TypeScript 類別，以及像 @uuid() 和 @text() 這樣的欄位修飾器。 每個實體檔案都會匯出一個類別，代表你應用程式中的資料模型。

Rayfin/Data/schema.ts

該 rayfin/data/schema.ts 檔案會將實體名稱映射到它們的類別。 Rayfin SDK 用戶端使用此對應表，透過 client.data.<Entity> 以型別安全的方式存取實體。 當你新增實體時，必須在這個結構檔案中註冊它。

產生的產物

rayfin/.temp/

這個 rayfin/.temp/ 資料夾包含在你執行開發伺服器時產生的後端產物。 如果後端看起來使用過時的架構或設定，請停止並重新啟動開發堆疊以重新產生這些檔案。

Important

不要把資料夾 .temp/ 提交到你的儲存庫。 將其新增至您的 .gitignore 檔案。

前端結構

資料夾裡 src/ 有你的前端應用程式代碼。 具體結構取決於你創建專案時選擇的範本，例如 React 或 Vue。

Fabric Apps 範本使用以下 Vite 環境變數進行前端設定：

  • VITE_RAYFIN_API_URL – 將前端指向 Fabric Apps 後端的基礎 URL。 在執行 npm run dev 前設定這個環境變數以覆蓋預設值。
  • VITE_RAYFIN_PUBLISHABLE_KEY – 可用於用戶端驗證的可發佈金鑰。
  • VITE_FABRIC_ITEM_ID – 由 rayfin up 設定的 Fabric 項目 ID。 在部署期間寫入至 .env.fabric-<workspacename>（以及 .env.fabric）。 用於 Fabric 代理驗證。
  • VITE_FABRIC_WORKSPACE_ID – 由 rayfin up 設定的 Fabric 工作區識別碼。 在部署期間與 VITE_FABRIC_ITEM_ID 一同寫入。

相關內容

  • Last updated on