Á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 domain <modul> [--db <név>]
├── add handler <modul> <surface> <művelet> --method GET --path "/x/{id}"
├── add auth [--module auth] [--social discord,facebook,apple,google]
├── 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
└── 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 gyökércsomagjának és a modul-szintű repository/-nak a váza.
• 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 auth egy teljes auth-modult scaffoldol (DB-alapú RBAC-séma, register/verify-email/login/refresh/logout/password-reset végpontok, plusz social login réteg), és automatikusan beköti az autentikációt: minden modul belépési pontjába beszúrja az api.Use(server.IdentityMiddleware(cfg.JWT)) sort a gpsystem:api-middleware anchornál, és a gpsystem.yaml-be írja az auth: <modul> bejegyzést, így a később generált modulok maguktól ezzel a sorral születnek. Régebbi projekten, ahol a main.go-ból hiányzik az anchor, nem hibázik, hanem kiírja a kézzel beillesztendő sort. Lásd Autentikáció.
• 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 domain a modul gyökércsomagjának domain-fájljait (<modul>.go, errors.go) és a modul-szintű repository/ vázat 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 --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

Két további anchor a saját kódod varrata, nem generátor-cél: a gpsystem:middleware (a server.Run opciólistájában, ide kerülnek a WithStack/WithMiddleware opciók; lásd a framework servere) és a gpsystem:surface-middleware (minden surface Route-blokkjának első sora, a route-csoport middleware-ek helye, pl. r.Use(server.RequireRole("admin"))).

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
framework: github.com/gp-system/framework@v0.0.0
db: pgx
auth: auth                     # az add auth által generált modul; amíg nem futott, nincs jelen
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. Az auth az add auth lefutása után jelenik meg, és az általa generált modult nevezi meg: a new module ebből tudja, hogy az új belépési pontokba automatikusan renderelje az identity middleware sorát.