常用开发工具与调试技巧

Koa2 常用开发工具

Koa2 开发中离不开各种工具的支持。nodemon 是必备的热重载工具，安装后通过 nodemon app.js 启动服务，文件修改时会自动重启。调试推荐使用 VSCode 内置调试器，配置 launch.json 如下：

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

日志管理建议使用 winston 库，多层级日志输出配置示例：

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()
      )
    })
  ]
});

核心中间件调试

bodyParser 中间件常见问题是请求体解析失败。调试时需确认：

1. 中间件注册顺序是否正确
2. 请求头 Content-Type 是否为 application/json
3. 请求体是否为合法 JSON 格式

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

路由调试可使用 koa-router 的 layer 追踪功能：

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

异步错误捕获

Koa2 的异步错误需要特殊处理，未捕获的 Promise rejection 会导致进程退出。推荐以下方案：

// 全局错误处理
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
    };
  }
});

// 异步操作错误示例
app.use(async ctx => {
  const data = await someAsyncOperation().catch(err => {
    // 手动附加状态码
    err.status = 400;
    throw err;
  });
});

性能调优技巧

使用 koa-compress 进行响应压缩时，需注意压缩阈值设置：

const compress = require('koa-compress');
app.use(compress({
  threshold: 2048, // 超过2KB才压缩
  gzip: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  br: false // 禁用Brotli
}));

数据库查询优化示例：

// 错误示范：N+1查询
app.use(async ctx => {
  const users = await User.findAll();
  const results = await Promise.all(
    users.map(user => Post.findAll({ where: { userId: user.id }}))
  );
});

// 优化方案：预加载关联
app.use(async ctx => {
  const usersWithPosts = await User.findAll({
    include: [{ model: Post }]
  });
});

测试相关工具

单元测试推荐使用 Jest + supertest 组合：

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

集成测试时可用内存数据库替代真实数据库：

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();
});

生产环境问题排查

内存泄漏检测可使用 heapdump 模块：

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}`);
});

慢请求监控中间件示例：

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`);
});

自定义调试中间件

开发环境专用调试工具示例：

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();
    }
  };
}

请求/响应日志格式化工具：

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]`);
});