add handler

Az add handler egyetlen endpointot ad hozzá egy meglévő surface-hez: egy TypeSpec műveletet plusz egy handler-metódus vázat, beillesztve a surface kategória-fájljaiba és anchoraiba. Ezt használd minden alkalommal, amikor egy már add surface-szal scaffoldolt surface-hez adsz műveletet.

go tool gpsystem add handler <modul> <surface> <művelet> \
  --method GET --path "/items/{id}"

Mit csinál

1. TypeSpec művelet-vázat szúr be a gpsystem:operations anchorhoz a <surface>.tsp-ben: a path-paraméterek deklarálva, POST/PUT/PATCH esetén @body paraméterrel, a visszatérési típus stubbal.
2. --permission / --policy esetén a megfelelő decoratorok is felkerülnek, és a válasz-unió kibővül Unauthorized | Forbidden-nel; az érvényesítést a generált middleware végzi (lásd auth, rbac & policy).
3. Kiválasztja a kategória-fájlt, amibe a handler-metódus kerül, az internal/modules/<modul>/surfaces/<surface>/http/ alatt: <modul>_handler.go az alap csoportnak, <modul>_<csoport>_handler.go egyébként.
4. A csoportot alapértelmezetten a --path első nem-paraméter szegmenséből származtatja (/notifications/{id}/read -> notifications); --group-pal felülírható.
5. Az adott kategória első művelete létrehozza a fájlt, a többi a fájl végi // gpsystem:handlers anchornál új metódusként kerül be.
6. A stub törzsét úgy generálja, hogy 501 Not Implemented problem dokumentumot adjon vissza, így az endpoint azonnal látható és tesztelhető.

A handler.go mindvégig a Handler struct, a New és a //go:generate helye marad: saját handler-metódust nem tartalmaz.

A munkafolyamat

go tool gpsystem add handler news api getNews --method GET --path "/items/{id}"
mise run generate     # létrejön a gen.GetNewsRequest / gen.GetNewsResponse

A getNews az /items/{id} útvonal miatt az items csoportba kerül: internal/modules/news/surfaces/api/http/news_items_handler.go. Egy ugyanazon csoportba tartozó további művelet (pl. deleteNews --path "/items/{id}") ugyanabba a fájlba kerül, a meglévő metódus mellé.

Aztán cseréld le a stub törzsét: hívd a service-t, és a hibát a határon csomagold be, ugyanazzal a mintával, amit az add surface váz generál:

// internal/modules/news/surfaces/api/http/news_items_handler.go
func (h *Handler) GetNews(ctx context.Context, req gen.GetNewsRequest) (gen.GetNewsResponse, error) {
    item, err := h.svc.GetByID(ctx, req.Id)   // add hozzá a service metódust
    if err != nil {
        return nil, errs.Wrap(err, "api: get news")  // stacket hordoz; a httperr rendereli
    }
    return mapper.ToGetNewsResponse(item), nil // add hozzá a mappert
}

Finomítsd a műveletet a .tsp fájlban (modellek, hiba-uniók, lapozás), és futtasd újra a mise run generate-et: a szigorú interfész fordítási időben tartja becsületben a handleredet.