hm-nodejs-api-design

Split each module into three files: module.ts as the composition root wiring dependencies, controller.ts with thin HTTP handlers, and route.ts defining only paths, methods, and hooks. Register the module in app.ts with a prefix like /api/orders.

Create a validateBody preHandler hook that calls schema.parse on request.body and passes a ValidationError to done() on failure. Attach it in the route's preHandler array after authentication so downstream code receives typed, coerced data.

Return 201 Created when a POST successfully creates a resource and 204 No Content for a successful DELETE with no response body. Use 200 OK for GET and updates, 400 for validation failures, 404 for missing resources, and 409 for conflicts.

No. Fastify natively catches errors thrown in async handlers and routes them to the function registered via setErrorHandler. Controllers should throw typed errors like NotFoundError instead of wrapping logic in try/catch blocks.

Plugins wrapped with fp() inherit the error handler from the parent scope at registration time. Setting handlers after plugin registration causes handler scope isolation bugs in Fastify 5, so error and not-found handlers must be set first in buildApp().

For modules with only one or two routes and no complex hooks, route definitions may stay in module.ts. Extract them to a separate route.ts file as soon as routes grow or hooks become non-trivial.