Fabric Apps -projektin rakenne

Fabric Apps projektoi erilliset backend-konfiguraatiot, tietomallit ja frontend-koodin. Tarkka asettelu riippuu mallipohjasta. Oletuspohja blankapp ratkeaa Universal Appiksi, npm-työtilaksi, jossa on erilliset frontend-, data- ja jaetut paketit.

Kansion asettelu

Oletus Universal App -tukirakenteella on seuraava rakenne:

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
Sijainti Omistus
rayfin/ Backend-konfiguraatio ja aktiivisen ympäristön arvot.
packages/frontend/ Selaimen käyttöliittymä, asiakasohjelman alustus ja käyttöliittymän rakentaminen.
packages/data/ Koristellut ajonaikaiset entiteettiluokat ja skeemarekisteröinti.
packages/shared/ Isomorfiset tietuesopimukset ja skeematyypit jaetaan frontendin kanssa. Älä laita tänne vain backend-koodia.

Data on poistettu käytöstä perusrakenteessa. Ota se käyttöön, kun sovelluksesi tarvitsee pysyviä tietueita:

npm run pack:add -- data-modeling

Ominaisuus lisää aloitusyksikön ja yhteisen sopimuksen sekä mahdollistaa datapalvelun. Entiteettien luomisesta ja MSSQL-murteen konfiguraatiosta katso Määrittele tietomallit.

Tasapohjainen vaihtoehto

Jotkut mallipohjat ja olemassa olevat sovellukset käyttävät tasaista asettelua, jossa frontend-koodi on juuressasrc/, entiteetit joukossa rayfin/data/, ja skeematyyppinen kartta .rayfin/data/schema.ts Tämä asettelu on edelleen voimassa. Älä siirrä tiedostoja tai luo duplikaattipaketteja vain sopiaksesi toiseen mallipohjaan. Lue rayfin/rayfin.yml palvelupolut löytääksesi ne hakemistot, joita projektisi oikeasti rakentaa.

Avainkonfiguraatiotiedostot

Rayfin/rayfin.yml

rayfin/rayfin.yml-tiedosto on pääasiallinen konfiguraatiotiedosto Fabric sovellusten taustajärjestelmälle. Se ohjaa, mitkä palvelut toimivat paikallisen kehityksen aikana ja tukee ympäristömuuttujien interpolointia dynaamisille konfiguraatioarvoille.

Oletustyötila käyttää eksplisiittisiä palvelupolkuja. Seuraava esimerkki näyttää nämä polut, joissa Data on käytössä sovelluksessa, joka tarvitsee tietokannan:

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

Palveluarvot path ovat suhteessa projektin juureen. Build-komennot suoritetaan ratkaistusta palveluhakemistosta. Funktioiden alustus tallentaa services.functions.path myös, kun se valitsee työtilapaketin, kuten packages/functions. Asuntoprojektit voivat käyttää olemassa rayfin/functions olevaa sijaintia. Katso Käytä funktioita.

Konfiguraatio sisältää seuraavat keskeiset kentät:

Huipputason kentät

kenttä Tyyppi Pakollinen Description
id string Yes Project-slug, jota käytetään Docker Compose -project-nimenä ja Fabric-kohteen tunnisteena.
name string Yes Ihmisen luettava projektin näyttönimi.
version string Yes Project-versio (semver).
services object Yes Palvelun konfiguraatiolohko.

services.data

kenttä Tyyppi Oletus Description
enabled boolean false Ota datapalvelu käyttöön.
dialect string — Käyttö mssql SQL-tietokannalle Fabric-ohjelmassa. Vaaditaan, kun Data on käytössä.
path string — Datapakettihakemistossa suhteessa projektin juureen, kuten packages/data. Litteät mallipohjat voivat käyttää rayfin/data.
buildCommand string — Build-komento konfiguroidulle datapaketille.

services.storage

kenttä Tyyppi Oletus Description
enabled boolean false Ota etätiedostojen tallennus käyttöön. Vaatii :n services.data.enabled: true.
path string . Tallennusprojektin juuri, suhteessa sovelluksen juureen. Esimerkki: packages/storage.

Tallennus toimii Fabric-laitteella, myös kehityksen aikana. Se ei käytä paikallista tallennuspalvelua tai emulaattoria. Ilmoita kansiot ja niiden käyttöoikeudet konfiguroidun tallennusprojektin juuren rayfin/storage/ alla. Asennusohjeet löytyvät kohdasta Tallenna ja hallinnoi tiedostoja.

services.auth

kenttä Tyyppi Oletus Description
enabled boolean false Ota käyttöön todennuspalvelu.
expiryInMinutes number — JWT-tokenin vanheneminen minuuteissa.
customClaims Record<string, string> — Mukautetut vaatimukset lisättiin myönnettyihin JWT-malleihin.
scopes string[] — OAuth-kaukoputket (esimerkiksi, ["read:data", "write:data"]).
refreshToken.lifetimeInDays number — Päivitä tokenin elinikä päivissä.
allowedRedirectUris string[] ["http://localhost:5173"] Sallittu uudelleenohjaus URI:t autentikointikutsuja varten.

services.auth.password

kenttä Tyyppi Oletus Description
enabled boolean true Ota käyttöön sähköposti- ja salasanatunnistus paikallista kehitystä varten

services.auth.fabric

kenttä Tyyppi Oletus Description
enabled boolean false Ota käyttöön Fabric-välittäjän tunnistautuminen (Microsoft Entra ID SSO).
externalEntraExchange boolean — Ota käyttöön suora delegoitu Entra-token-vaihto ja ulkoinen vanhempi-isäntä-autentikointi, kun kohdeympäristö tukee sitä.

services.staticHosting

kenttä Tyyppi Oletus Description
enabled boolean false Ota staattisen sisällön isännöinti käyttöön.
path string — Frontend-pakettihakemisto suhteessa projektin juureen.
root string — Legacy frontend-juuri, jota käytetään tasaisissa kokoonpanoissa.
folder string "dist" Hakemisto, joka sisältää rakennettuja staattisia assetteja suhteessa ratkaistuun frontend-polkuun.
buildCommand string — Shell-komento ajaa ennen pakkausta (esim. npm run build).
indexDocument string — Oletusdokumentti, joka palvellaan juuripolulle (esim. index.html).

Vinkki

Kaikki merkkijonoarvot tukevat ympäristömuuttujien interpolointia ja ${VAR}${VAR:-default} syntaksia. Muuttujat ratkaistaan kuoren rayfin/.env ympäristöstä.

rayfin/.env

Tiedosto rayfin/.env sisältää aktiiviset ajonaika- ja käyttöönottoarvot ja toimittaa arvot interpoloinnin kautta rayfin.yml . Komentorivi kirjoittaa kehysneutraaleja RAYFIN_PUBLIC_* arvoja aktiiviselle taustajärjestelmälle. Vain muuttujat, joilla on kyseinen etuliite, projisoidaan generoituihin frontend-ympäristötiedostoihin. Älä koskaan laita salaisuuksia RAYFIN_PUBLIC_* muuttujiin.

Pysy rayfin/.env poissa lähteenhallinnasta. Käytetään rayfin/.env.example dokumentoimaan odotettuja muuttujia paikkamerkkien avulla.

Rayfin/.deployments.json

Käyttöönoton rekisteri tallentaa backend-URL-osoitteet, isännöintiosoitteet, kohde-ID:t ja työtilan ID:t projektisi käyttöönottoja varten. Se ei ole frontend-ympäristötiedosto. Pidä se poissa lähteenhallinnasta. Käytetään npx rayfin up list tallennettujen käyttöönottojen listaamiseen, npx rayfin up switch <name> aktiivisen käyttöönoton vaihtamiseen ja ympäristöarvojen palauttamiseen.

Rayfin/tsconfig.json

Mallipohjat tarjoavat TypeScript-konfiguroinnin niiden asetteluun. Workspace-paketeilla on omat konfiguraationsa ja projektiviittauksensa; litteät mallipohjat voivat kääntää entiteettejä läpi rayfin/tsconfig.json. Säilytä tukirakenteen viittaukset ja käytä sen build- ja type-check-skriptejä sen sijaan, että olettaisit yhden juurikokouksen.

Tietomallitiedostot

Pidä ajonaikainen rekisteröinti ja asiakaskohtaiset tyypit linjassa valitsemasi asettelun mukaan.

Työtilayksiköt ja jaetut sopimukset

Universal Appissa tiedostot määrittelevät packages/data/src/ koristellut entiteettiluokat. Rekisteröi ajonaikaiset luokat taulukossaschema, joka on vienyt .packages/data/src/index.ts

Pidä yllä tietueliitännät ja tyyppi UniversalAppSchema .packages/shared/src/index.ts Frontend tuo tämän sopimuksen @rayfin-app/shared sisään sen sijaan, että tuo koristeltuja backend-luokkia.

Flat-template-entiteetit

Tasaisessa mallipohjassa määrittelee rayfin/data/*.ts entiteettejä ja rayfin/data/schema.ts yhdistää entiteettien nimet tyyppeihin .client.data.<Entity> Noudata kyseisen mallin tarjoamaa rekisteröintimekanismia.

Tallennustiedostot

Valinnainen rayfin/storage/ kansio tallennusprojektin juuren alla sisältää luokat, jotka on koristeltu ja @blob()schema.ts tiedoston, joka rekisteröi ne. Kun jätät services.storage.path sen pois tai asetat , .lisää nämä tiedostot sovelluksesi rayfin/storage/ kansioon. Esimerkiksi sijoittaa services.storage.path: packages/storage nämä tiedostot .packages/storage/rayfin/storage/ Vie taulukkoschema, joka listaa kansiot, jotka on tarkoitus ottaa käyttöön Fabric:iin. Tyyppi AppStorageSchema määrittää kansioiden nimet luokkiin tyypitettyä asiakaskäyttöä varten. Esimerkiksi katso Tallenna ja hallinnoi tiedostoja.

Luodut artefaktit

rayfin/.temp/

Kansio rayfin/.temp/ sisältää generoituja taustaartefakteja, jotka syntyvät, kun ajat kehityspalvelinta. Jos taustajärjestelmä näyttää käyttävän vanhentunutta skeemaa tai konfiguraatiota, pysäytä ja käynnistä kehittäjäpino uudelleen, jotta nämä tiedostot voidaan generoida uudelleen.

Important

Älä sitoo .temp/ kansiota repositorioosi. Lisää se tiedostoosi .gitignore .

Edustarakenne

Oletusetuosa on .packages/frontend/src/ Litteät mallipohjat voivat käyttää juurta src/. Asetus services.staticHosting.path tunnistaa frontend-paketin.

Aktiivinen ympäristö- ja kehyskartoitus

rayfin devja rayfin up tuottaa kehyskohtaisia .env.local arvoja .rayfin/.env Sisäkkäiselle frontendille tiedosto kirjoitetaan , services.staticHosting.pathesimerkiksi packages/frontend/.env.local; tasaiset projektit käyttävät projektin juurta.

Lähde rayfin/.env Vite-lähtö .env.local Next.js lähtö sisään .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

Muokkaa lähdearvoja , rayfin/.envälä generoitua tiedostoa. Regenerointi ilman käyttöönottoa:

npx rayfin env --framework vite

Käytä --framework nextjs tai --framework plain muita tuettuja kartoituksia. Käytetään --output <dir> valita tuloshakemisto tai --show tarkastella julkista kartoitusta ilman kirjoittamista. Pidä generoidut .env.local tiedostot poissa lähdekoodin hallinnasta.

Siirrä vanhempi ympäristöasettelu

Vanhemmissa projekteissa voi olla .env.fabric tiedostoja .env.fabric-<workspace> . Nämä tiedostot eivät ole aktiivisia ympäristötiedostoja nykyisessä asettelussa. Juokse npx rayfin up käyttääksesi nykyistä ympäristön työnkulkua. Tarkista mahdolliset siirtoviestit ja kopioi niihin mukautetut arvot rayfin/.env tarpeen mukaan. Käyttöönottorekisteri korvaa työtilakohtaiset ympäristötiedostot. Älä määritä uusia sovelluksia riippumaan niistä.

Liittyvä sisältö

  • Viimeksi päivitetty