A shop mintaalkalmazás

A dokumentáció példái egyetlen összefüggő projektből jönnek: a shop egy webshop-backend, két surface-szel, worker binárissal, eseményekkel és ütemezett jobbal. Nem kell megépítened ahhoz, hogy a dokumentációt olvasd, de minden oldal ennek a projektnek a fájljaira hivatkozik, így a részletek egy koherens egésszé állnak össze.

Mit modellez

• api surface (publikus): terméklistázás cursor-lapozással, rendelésfeladás (PlaceOrder), validációval, policy-ellenőrzéssel és tranzakcióval.
• admin surface: termék CRUD és képfeltöltés object storage-ba, RequireRole("admin") mögött.
• orderPlaced event: a rendelésfeladás tranzakciójából, outboxon keresztül kerül a queue-ba.
• sendOrderConfirmation listener: a workerben fut, MJML e-mailt küld.
• nightlySalesReport job: minden hajnalban fut, replika-biztosan.

Hogyan generálódik

A teljes vázat a CLI adja: pontosan ezekkel a parancsokkal:

go tool gpsystem new project shop --module-path github.com/acme/shop \
  --dir ./shop                    # --db bun is választható
cd shop

go tool gpsystem new module shop                 # api surface, alapértelmezésben
go tool gpsystem add surface shop admin
go tool gpsystem add event shop orderPlaced
go tool gpsystem add listener shop orderPlaced sendOrderConfirmation --queue mail
go tool gpsystem add job shop nightlySalesReport --cron "0 3 * * *"
go tool gpsystem new migration create_products_and_orders

mise run generate                                # tsp → OpenAPI → szerverkód → build

A projekt alakja

Az alábbi fa minden fájlja pontosan az, amit a generátor + a saját üzleti logikád előállít, kattints végig rajta. Az api surface a modul gyökerére mountolódik (/api/v1/shop/...), az admin a saját prefixe alá (/api/v1/admin/shop/...), lásd add surface. A közös rendelési szabály a modul core/ csomagjában él, a perzisztencia a modul-szintű repository/-ban; az api surface service/-e vékony varrat ezek fölött. A generált // gpsystem:* anchor-kommenteket az olvashatóság kedvéért többnyire elhagytuk; a saját projektedben hagyd őket a helyükön: a későbbi add surface / add event / add listener hívások ezekhez a pontokhoz illesztenek.

package main

import (
    "context"
    "log"

    "github.com/go-chi/chi/v5"

    "github.com/gp-system/dbx/pg"
    "github.com/gp-system/envconf"
    "github.com/gp-system/events/outbox"
    "github.com/gp-system/gpsystem/server"

    "github.com/acme/shop/internal/modules/shop"
    "github.com/acme/shop/internal/platform/config"
)

func main() {
    cfg := envconf.MustLoad[config.Config]()
    ctx := context.Background()
    pool := pg.MustNewPool(ctx, cfg.DB)

    err := server.Run(ctx, cfg.Server, func(r chi.Router) error {
        api := chi.NewRouter()
        deps := shop.Dependencies{
            DB:         pg.NewDB(pool),
            Transactor: pg.NewTransactor(pool),
            Dispatcher: outbox.NewDispatcher(outbox.NewStore(pg.NewDB(pool))),
        }
        shop.RegisterApi(api, deps)
        shop.RegisterAdmin(api, deps)
        r.Mount("/api/v1", api)
        return nil
    }, server.WithCloser("pgxpool", func(context.Context) error {
        pool.Close()
        return nil
    }))
    if err != nil {
        log.Fatal(err)
    }
}

A register.go RegisterApi/RegisterAdmin függvényei ugyanazt a generált mintát követik, amit A szerver mag oldal sorról sorra dokumentál: explicit service → handler → policy-registry felépítés, surface-enként egy router.Route, server.StrictValidator és kitpolicy.Enforcer strict middleware-ként, httperr-en át renderelt hibákkal.

Kövesd a rendelést

Egy POST /api/v1/shop/orders kérés útja a rendszeren át, lépésenként azzal az oldallal, ami az adott ugrást dokumentálja:

Következő lépés: az első modulod, ugyanez az út, a saját geped előtt ülve.