Fabric Apps 專案結構

Fabric Apps 專案將後端設定、資料模型與前端程式碼分開。 具體的版面配置取決於範本。 預設 blankapp 範本會解析為 Universal App,一個包含獨立前端、資料與共享套件的 npm 工作區。

資料夾配置

預設的通用應用程式架構如下:

your-project/
├── rayfin/
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── packages/
│   ├── frontend/
│   │   ├── src/
│   │   └── package.json
│   ├── data/
│   │   └── src/index.ts
│   └── shared/
│       └── src/index.ts
├── package.json
├── tsconfig.json
└── README.md
Location 擁有權
rayfin/ 後端設定與作用中環境值。
packages/frontend/ 瀏覽器介面、客戶端初始化和前端建置。
packages/data/ 裝飾過的執行時實體類別和結構描述註冊。
packages/shared/ 與前端共享的同構記錄合約與結構型態。 不要放後端專用程式碼。

基底鷹架中的資料已停用。 當你的應用程式需要持久化記錄時啟用它:

npm run pack:add -- data-modeling

此功能新增起始實體與共享合約,並啟用資料服務。 關於實體編寫與 MSSQL 方言設定,請參見 定義資料模型。

扁平模板替代方案

有些範本和現有應用程式使用平面版面配置,前端程式碼在根目錄 src/,實體在 rayfin/data/,結構型態映射在 rayfin/data/schema.ts。 此版面配置仍有效。 不要為了匹配另一個範本而移動檔案或建立重複套件。 閱讀 rayfin/rayfin.yml 中的服務路徑設定,找出你的專案實際建立的目錄。

關鍵設定檔

rayfin/rayfin.yml

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

預設工作區使用明確的服務路徑。 以下範例展示了已啟用 Data、且需要資料庫的應用程式路徑:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: false
  data:
    enabled: true
    dialect: mssql
    path: packages/data
    buildCommand: npm run build
  staticHosting:
    enabled: true
    path: packages/frontend
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected

服務 path 值是相對於專案根目錄的。 建置指令會在已解析的服務目錄中執行。 函式初始化也會在其選取工作區套件(如 packages/functions)時記錄 services.functions.path。 扁平專案可以使用現有的 rayfin/functions 位置。 請參見 使用函數。

配置包含以下關鍵欄位:

最上層欄位

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 啟用資料服務。
dialect string — 在 Fabric 中使用 mssql 作為 SQL 資料庫。 啟用資料時為必填。
path string — 資料包目錄相對於專案根目錄,例如 packages/data。 平面範本可以使用 rayfin/data。
buildCommand string — 建置已設定資料套件的命令。

services.storage

Field 類型 預設值 Description
enabled boolean false 啟用遠端檔案儲存。 需要 services.data.enabled: true。
path string . 儲存專案的根目錄,相對於應用程式的根目錄。 例如: packages/storage 。

Storage 在 Fabric 上執行,包括在開發期間。 它沒有使用本地儲存服務或模擬器。 在設定的儲存專案根目錄中於 rayfin/storage/ 下方宣告資料夾及其存取政策。 關於設定說明,請參見 儲存與管理檔案。

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)。
externalEntraExchange boolean — 當目標環境支援時,啟用直接委派的 Entra 令牌交換及外部父主機認證。

services.staticHosting

Field 類型 預設值 Description
enabled boolean false 啟用靜態內容託管。
path string — 相對於專案根目錄的前端套件目錄。
root string — 舊有的前端根,用於扁平設定。
folder string "dist" 包含建構後靜態資產的目錄,且相對於已解析的前端路徑。
buildCommand string — 在打包前執行 Shell 指令(例如, npm run build)。
indexDocument string — 為根路徑提供的預設文件(例如 index.html)。

小提示

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

Rayfin/.env

該rayfin/.env檔案包含目前使用中的執行階段與部署值,並透過插值將值提供給 rayfin.yml。 CLI 為目前使用中的後端寫入框架中立的 RAYFIN_PUBLIC_* 值。 只有帶有該前綴的變數會寫入到產生的前端環境檔案中。 千萬不要把秘密放進 RAYFIN_PUBLIC_* 變數裡。

不要將 rayfin/.env 納入版本控制。 用 rayfin/.env.example 來記錄帶有佔位符的預期變數。

rayfin/.deployments.json

部署登錄檔會記錄專案部署的後端 URL、主機 URL、項目 ID 及工作區 ID。 它不是一個前端環境檔案。 不要讓它進入源控系統。 用 npx rayfin up list 來列出已錄製的部署,並 npx rayfin up switch <name> 切換主動部署並重新產生其環境值。

rayfin/tsconfig.json

範本提供其版面配置的 TypeScript 組態。 Workspace 套件有自己的設定與專案參考;平面範本可透過 rayfin/tsconfig.json. 編譯實體。 保留腳手架的參照,並使用其建置與型別檢查腳本,而非假設採用單一根層級的編譯。

資料模型檔案

請依照你所選的版面配置,讓執行時註冊與面向客戶的類型保持一致。

工作空間實體與共享合約

在 Universal App 中,packages/data/src/ 下的檔案定義裝飾的實體類別。 在由 schema 匯出的 packages/data/src/index.ts 陣列中註冊執行時類別。

保持相符的記錄介面及 UniversalAppSchema 中的 packages/shared/src/index.ts 型別。 前端是從此契約 @rayfin-app/shared 匯入,而不是匯入裝飾過的後端類別。

扁平範本實體

在平面模板中,rayfin/data/*.ts 定義實體,而 rayfin/data/schema.ts 將實體名稱對應到 client.data.<Entity> 的類型。 請依照該範本提供的註冊機制操作。

儲存體檔案

儲存專案根目錄下的可選 rayfin/storage/ 資料夾包含裝飾過的 @blob() 類別及 schema.ts 一個註冊它們的檔案。 當你省略 services.storage.path 或將其設為 . 時,請將這些檔案加入應用程式的 rayfin/storage/ 資料夾下。 例如,services.storage.path: packages/storage 會將這些檔案放在 packages/storage/rayfin/storage/ 下方。 匯出一個schema陣列,列出要部署到 Fabric 的資料夾。 AppStorageSchema 類型會將資料夾名稱對應至類別,以供具型別的用戶端存取。 舉例來說,請參見 儲存與管理檔案。

產生的產物

rayfin/.temp/

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

Important

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

前端結構

預設前端介面位於 packages/frontend/src/。 扁平模板可以使用根節點 src/。 services.staticHosting.path 設定可識別前端套件。

啟用的環境與框架映射

rayfin dev 和 rayfin up 會從 .env.local 產生框架特定的 rayfin/.env 值。 對於巢狀前端,檔案會寫在 services.staticHosting.path 之下,例如 packages/frontend/.env.local;平面專案則使用專案根目錄。

資料來源 rayfin/.env Vite 輸出於 .env.local Next.js 中的輸出 .env.local
RAYFIN_PUBLIC_API_URL VITE_RAYFIN_API_URL NEXT_PUBLIC_RAYFIN_API_URL
RAYFIN_PUBLIC_PUBLISHABLE_KEY VITE_RAYFIN_PUBLISHABLE_KEY NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY
RAYFIN_PUBLIC_ITEM_ID VITE_FABRIC_ITEM_ID NEXT_PUBLIC_FABRIC_ITEM_ID
RAYFIN_PUBLIC_WORKSPACE_ID VITE_FABRIC_WORKSPACE_ID NEXT_PUBLIC_FABRIC_WORKSPACE_ID
RAYFIN_PUBLIC_PORTAL_URL VITE_FABRIC_PORTAL_URL NEXT_PUBLIC_FABRIC_PORTAL_URL

在 rayfin/.env 中編輯來源值,而不是編輯產生的檔案。 要在不部署的情況下重新產生:

npx rayfin env --framework vite

可使用 --framework nextjs 或 --framework plain 來處理其他支援的映射。 用 --output <dir> 來選擇輸出目錄或 --show 檢查公開映射而不進行任何寫入。 請將產生的 .env.local 檔案排除在原始碼控制之外。

遷移舊的環境版面配置

較舊的專案可能會包含 .env.fabric 或 .env.fabric-<workspace> 檔案。 這些檔案不是目前配置中的使用中環境檔案。 執行 npx rayfin up 以使用目前環境的工作流程。 檢查任何遷移訊息,並視需要將自訂值複製到 rayfin/.env 中。 部署登錄取代了每個工作空間的環境檔案。 不要設定新應用程式依賴它們。