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' }) ).