← Tutti i modelli

Handler tipizzati, validazione al confine, log strutturati, mai bloccare l’event loop.

Constitution — Node.js + Express API

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.

  1. Typed handlers. Every route handler declares the types of its params, body, query and response through Request<Params, ResBody, ReqBody, Query> or a typed router helper. any in a handler fails the review and strict is on.

  2. Validation at the edge. Every body, query and params object is parsed with a schema (zod or similar) in a middleware before the handler runs. Handlers receive parsed values only; a request that fails the schema gets a 400 with the failing fields.

  3. Structured logs. Logs are JSON written by pino (or an equivalent) with a request id from pino-http, the route and the status. console.log in application code fails the lint.

  4. Never block the event loop. No synchronous file, crypto or zlib calls (readFileSync, pbkdf2Sync) in request paths, and no CPU work over 10 ms in a handler; heavy work goes to a worker thread or a queue. Event loop delay is measured and alerts above 100 ms at p99.

  5. One error middleware. Async errors reach a single error-handling middleware (Express 5 forwards rejected promises; on Express 4 every async handler is wrapped). It maps typed errors to status codes and never sends a stack trace to the client.

  6. Secure defaults. helmet, a body size limit on express.json(), CORS with an explicit origin list and app.disable("x-powered-by") are set in the app factory. A route that needs a looser rule says why in the plan.

  7. Testable app factory. The app is built by a function that takes its dependencies and does not listen, so supertest runs every route in tests without a port. Each route has tests for its success and its validation failure.