Getting Started
Conventions
Naming, versioning, auth strategies e formati comuni dei microservizi.
Conventions
Stack di riferimento
- Runtime: Node.js 22.17 LTS
- Framework: Fastify v5 +
@pzeta/fastify-utils(security, error handler, auth, OpenAPI) - Lingua: TypeScript strict
- Database: PostgreSQL via driver
pgdiretto (no ORM) - Validation: Zod (request/response, schema-first)
- DI: Inversify
Naming dei servizi
- Pattern repo Gitea:
PZeta_Touch/node-{name}(kebab-case). - Pattern image:
gitea.pzetatouch.it/pzeta_touch/node-{name}:{semver}. - Pattern deployment K8s:
node-{name}-{tenant}(es.node-storage-ditta). - Pattern DNS interno:
node-{name}-{tenant}.{tenant}.svc.cluster.local.
Auth strategies supportate
Multi-strategia via authPlugin di @pzeta/fastify-utils:
| Strategy | Quando | Header / segnale |
|---|---|---|
nginx | Traffico utente da browser (default) | X-User-Id, X-User-Tenant, … iniettati dall'ingress |
apiKey | Sviluppo e test | x-api-key |
oauth | Comunicazione M2M con introspection | Bearer token |
jwt | Casi particolari self-contained | Bearer JWT firmato |
Forbidden: storing password (identità gestita da Identity Provider esterno).
Versioning
- Tag Git semver:
vX.Y.Z(es.v1.0.22). - L'OpenAPI servito dal microservizio espone
info.versionallineato al tag. - La pagina del servizio nel sito riporta la versione del container in produzione (campo
versiondel frontmatter).
Endpoint convenzionali
Esposti standard da ogni node-*:
/health— liveness probe/ready— readiness probe/openapi.json(o/api-docs.json) — schema OpenAPI 3.1
Formato errore
Tutte le response di errore seguono il formato di errorHandlerPlugin di @pzeta/fastify-utils (vedi pagine /services/* per dettagli per servizio).
Stato: stub iniziale. Contenuto da completare con esempi reali e codici errore documentati.