Fabric应用项目结构

Fabric应用项目使用一致的文件夹布局，以便快速查找数据模型、后端配置和前端代码。 本文介绍创建项目后最有可能使用的文件和文件夹。

文件夹布局

创建新的Fabric应用项目时，模板将生成以下结构：

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应用后端的主配置文件。 它控制哪些服务在本地开发期间运行，并支持动态配置值的环境变量内插。

完整示例：

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

配置包括以下关键字段：

顶级字段

领域 类型 必需 说明
id string 是的 用作 Docker Compose 项目名称和 Fabric 项目标识符的 slug（短标识）。
name string 是的 便于阅读的项目显示名称。
version string 是的 Project版本（semver）。
services object 是的 服务配置块。

services.data

领域 类型 默认 说明
enabled boolean false 启用数据服务。

services.auth

领域 类型 默认 说明
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

领域 类型 默认 说明
enabled boolean true 为本地开发启用电子邮件和密码身份验证

services.auth.fabric

领域 类型 默认 说明
enabled boolean false 启用Fabric中转身份验证（Microsoft Entra ID SSO）。

services.staticHosting

领域 类型 默认 说明
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 文件是一个用于项目引用的 TypeScript 配置文件，由 Fabric Apps CLI 用于编译你的实体定义。 它扩展你的根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应用模板使用以下 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 工作区 ID。 在部署期间与 VITE_FABRIC_ITEM_ID 一同编写。

相关内容

  • Last updated on