Koa.js Professional Standards
Middleware Architecture
-
The Async Promise Chain: ALWAYS declare middleware as async (ctx, next) => { ... } .
-
Await Next: You MUST await next() exactly once in every middleware.
-
Execution Order: Code before await next() handles the Request; code after handles the Response.
Reliability & Ops
-
Graceful Shutdown: Do not kill the server instantly. Listen for system signals (SIGTERM , SIGINT ).
-
Pattern: Stop accepting new requests -> Close database connections -> Exit process.
-
Example: server.close(() => db.disconnect()) .
-
Health Checks: Always implement a /health endpoint for load balancers (return 200 OK if DB is connected).
Context (ctx) Mastery
-
State Management: Use ctx.state to pass data between middleware (e.g., ctx.state.user ). NEVER pollute the global namespace.
-
Request Data: Access via ctx.request.body , ctx.query , or ctx.params .
-
Response Construction: Explicitly set ctx.status before setting ctx.body .
Security Best Practices
-
Error Handling: Implement a top-level app.on('error', ...) listener and a generic try/catch middleware. Never crash the process on a request error.
-
Headers: Use koa-helmet for standard security headers.
-
Cookies: Always sign cookies using ctx.cookies.set(name, val, { signed: true }) and a secure app.keys .
Routing
-
Router Organization: Use koa-router (or @koa/router ).
-
Prefixing: Group routes by domain (e.g., const usersRouter = new Router({ prefix: '/users' }) ).