Áttekintés

A fogyasztó projektek a Go 1.24+ tool directive-vel rögzítik a CLI-t a go.mod-ban (a new project írja be), így a csapat minden tagja ugyanazt a verziót futtatja:

go tool gpsystem <parancs>

gpsystem
├── new project <név> --module-path <path> [--dir] [--db pgx|bun]
├── new module <név> [--surface <név>]
├── new migration <név>
├── add surface <modul> <surface> [--db <név>]
├── add core <modul> [--db <név>]
├── add handler <modul> <surface> <művelet> --method GET --path "/x/{id}"
├── add event <modul> <név>
├── add listener <modul> <event> <név> [--queue <sor>]
├── add job <modul> <név> --cron "0 3 * * *"
├── add mail <modul> <név>
├── add notification <modul> <név>
├── add worker
├── add realtime
├── add db <modul> <név> [--connector pgx|bun]
├── add seeder <név>
├── add compose
├── add docker
├── upgrade templates [--force]
└── version

Gyors, parancsonkénti tájékozódás:

• A new module modult generál: belépési pont, első surface, kontraktus, plusz a modul-szintű core/repository vázak.
• Az add surface újabb surface-t ad egy meglévő modulhoz.
• Az add handler egy műveletet ad egy meglévő surface-hez.
• Az add event létrehoz egy eventet, és bedrótozza a modulba az outbox dispatchert.
• Az add listener feliratkozik egy eventre (a --queue egy nevesített asynq sorra irányítja).
• Az add job ütemez egy ismétlődő handlert.
  Az add event / add listener / add job a cmd/worker binárishoz készít háttérmunkát (lásd a worker koncepciókat); minden projekt tartalmazza a workert, így ezek a parancsok azonnal használhatók.
• Az add mail egy modul-tulajdonú mail-notifiert (payload + sablonok) generál, és a projekt első notifierénél bedrótoz egy közös mail.Mailer-t minden belépési pontba.
• Az add notification egy modul-tulajdonú, többcsatornás notificationt (payload + Via + csatornánkénti tartalom) generál, és a projekt első notificationjénél bedrótoz egy közös notify.Sender-t minden belépési pontba, plusz a notifications tábla migrációt.
• Az add realtime a dedikált, horizontálisan skálázható cmd/realtime gatewayt scaffoldolja, ami élőben kézbesíti a notificationöket a csatlakozott klienseknek.
• Az add worker hozzáadja a worker-réteget (cmd/worker, modulonkénti listeners//jobs/ alcsomagok, az outbox migráció) egy olyan projekthez, amelyben még nincs.
• A new migration számozott goose SQL migrációt hoz létre a migrations/ mappában.
• Az add db egy modulhoz ad hozzá egy másik, önálló adatbázis-kapcsolatot (saját pool, config és Dependencies mezők, pgx vagy bun); az add surface --db a modul közös repository-vázát köti hozzá.
• Az add core a közös core/ és a modul-szintű repository/ vázakat adja hozzá egy olyan modulhoz, amelyben ezek még nincsenek meg (tisztán additív, anchorhoz nem nyúl).
• Az add compose önállóan (újra)generálja a compose.yml-t (alap stack + egy service manifest-modulonként); az add docker a Dockerfile-t/.dockerignore-t generálja újra.

Globális flagek minden parancson: --dry-run (a terv kiírása, írás nélkül) és --force (felülírás engedélyezése). A new project ezeken felül elfogadja a --kit-replace/--replace/--replace-dev flageket is: ez egy contributor/dev-mode funkció, ami a generált go.mod replace-direktíváit lokális modul-checkoutokra irányítja; a hétköznapi fogyasztó-projekteknek sosem kell hozzájuk nyúlniuk, lásd new project: contributor mód.

Biztonsági szabályok

• A teljes fájlterv előre elkészül; ha bármely cél létezik, az egész futás megszakad, mielőtt bármi íródna (kivéve --force). Részleges írás nincs. --force esetén a futás folytatódik, de előbb minden felülírandó létező fájlra kiír egy overwriting <path> sort, így az újragenerálás soha nem írja felül némán a fájlokat.
• A generált .go fájlok goimports-szal formázódnak; az érvénytelen Go-t renderelő template hangosan hibázik.
• Meglévő fájl kizárólag anchor-kommenteknél módosul, sehol máshol.
• A beszúrások idempotensek: egy generátor újrafuttatása sosem duplikál blokkot.

Anchorok

A manifest: gpsystem.yaml

A new project írja a projekt gyökerébe; a CLI felfelé sétálva találja meg a projektet.

version: 1
name: shop
module: github.com/acme/shop
kit: github.com/gp-system/gpsystem@v0.1.0
engine: chi
db: pgx
templatesSHA: 4f2a…            # a telepített oapi template-készlet checksumja
modules:
  news:
    surfaces: [api, admin]
    dbs:
      - name: analytics
        connector: bun
    surfaceDBs:
      admin: analytics

Ez a generátorok igazságforrása arról, mi létezik (az add surface news admin azonnal hibázik, ha a modul hiányzik vagy a surface már megvan), és a module mezőt a go.mod-dal is összeveti. A dbs/surfaceDBs csak akkor jelenik meg, ha a modulnak van nevesített kapcsolata (add db révén); a nélkülük írt manifestek változatlanul betöltődnek.