Common development tools and debugging techniques

Commonly Used Development Tools for Koa2

Koa2 development relies on various tools for support. Nodemon is an essential hot-reloading tool. After installation, start the service with nodemon app.js, and it will automatically restart when files are modified. For debugging, the built-in debugger in VSCode is recommended. Configure launch.json as follows:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Koa Debug",
      "program": "${workspaceFolder}/app.js",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

For log management, the Winston library is recommended. Here’s an example of multi-level log output configuration:

const winston = require('winston');
const logger = winston.createLogger({
  levels: winston.config.syslog.levels,
  transports: [
    new winston.transports.File({ 
      filename: 'error.log',
      level: 'error'
    }),
    new winston.transports.Console({
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      )
    })
  ]
});

Debugging Core Middleware

A common issue with the bodyParser middleware is request body parsing failure. When debugging, ensure:

1. The middleware registration order is correct.
2. The request header Content-Type is set to application/json.
3. The request body contains valid JSON.

app.use(async (ctx, next) => {
  console.log('Raw request body:', ctx.request.rawBody);
  await next();
});

For route debugging, use the layer tracing feature of koa-router:

router.get('/users/:id', (ctx) => {
  console.log('Matched path:', ctx._matchedRoute);
  console.log('Path params:', ctx.params);
});

Asynchronous Error Handling

Asynchronous errors in Koa2 require special handling. Uncaught Promise rejections can cause the process to exit. Recommended solutions:

// Global error handling
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = { 
      message: err.message,
      stack: process.env.NODE_ENV === 'development' ? err.stack : undefined
    };
  }
});

// Example of asynchronous operation error
app.use(async ctx => {
  const data = await someAsyncOperation().catch(err => {
    // Manually attach status code
    err.status = 400;
    throw err;
  });
});

Performance Optimization Tips

When using koa-compress for response compression, pay attention to the compression threshold setting:

const compress = require('koa-compress');
app.use(compress({
  threshold: 2048, // Compress only if over 2KB
  gzip: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  br: false // Disable Brotli
}));

Example of database query optimization:

// Bad practice: N+1 queries
app.use(async ctx => {
  const users = await User.findAll();
  const results = await Promise.all(
    users.map(user => Post.findAll({ where: { userId: user.id }}))
  );
});

// Optimized solution: Preload associations
app.use(async ctx => {
  const usersWithPosts = await User.findAll({
    include: [{ model: Post }]
  });
});

Testing Tools

For unit testing, Jest + Supertest is recommended:

const request = require('supertest');
const app = require('../app');

describe('GET /users', () => {
  it('should return 200', async () => {
    const res = await request(app.callback())
      .get('/users')
      .expect('Content-Type', /json/)
      .expect(200);
    
    expect(res.body).toHaveProperty('data');
  });
});

For integration testing, use an in-memory database instead of a real one:

const { MongoMemoryServer } = require('mongodb-memory-server');

beforeAll(async () => {
  const mongoServer = await MongoMemoryServer.create();
  process.env.MONGO_URI = mongoServer.getUri();
});

afterAll(async () => {
  await mongoose.disconnect();
  await mongoServer.stop();
});

Production Environment Troubleshooting

For memory leak detection, use the heapdump module:

const heapdump = require('heapdump');
process.on('SIGUSR2', () => {
  const filename = `/tmp/heapdump-${process.pid}-${Date.now()}.heapsnapshot`;
  heapdump.writeSnapshot(filename);
  console.log(`Heap dump written to ${filename}`);
});

Example of a slow request monitoring middleware:

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const duration = Date.now() - start;
  
  if (duration > 500) {
    console.warn(`Slow request: ${ctx.method} ${ctx.url} - ${duration}ms`);
  }
  
  ctx.set('X-Response-Time', `${duration}ms`);
});

Custom Debugging Middleware

Example of a debugging tool for development environments only:

function devMiddleware() {
  return async (ctx, next) => {
    if (process.env.NODE_ENV !== 'production') {
      console.log('Request headers:', ctx.headers);
      console.log('Current state:', ctx.state);
      const start = process.hrtime();
      await next();
      const diff = process.hrtime(start);
      console.log(`Execution time: ${diff[0] * 1e3 + diff[1] / 1e6}ms`);
    } else {
      await next();
    }
  };
}

Request/response log formatting tool:

app.use(async (ctx, next) => {
  console.log(`<-- ${ctx.method} ${ctx.url}`);
  await next();
  console.log(`--> ${ctx.method} ${ctx.url} ${ctx.status} [${ctx.length || 0}b]`);
});