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 中。 部署登錄取代了每個工作空間的環境檔案。 不要設定新應用程式依賴它們。