洋葱圈模型的工作原理

洋葱圈模型的基本概念

洋葱圈模型是Koa2中间件处理请求和响应的核心机制。想象一个洋葱，请求从外层进入，穿过每一层中间件，到达核心业务逻辑，然后再反向穿过每一层中间件返回。这种双向流动的处理方式让中间件可以在请求处理前后都执行逻辑。

const Koa = require('koa');
const app = new Koa();

// 第一个中间件
app.use(async (ctx, next) => {
  console.log('进入第一个中间件');
  await next();
  console.log('离开第一个中间件');
});

// 第二个中间件
app.use(async (ctx, next) => {
  console.log('进入第二个中间件');
  await next();
  console.log('离开第二个中间件');
});

// 业务逻辑
app.use(async ctx => {
  console.log('处理业务逻辑');
  ctx.body = 'Hello World';
});

app.listen(3000);

执行这段代码时，控制台输出顺序会是：

进入第一个中间件
进入第二个中间件
处理业务逻辑
离开第二个中间件
离开第一个中间件

中间件的执行顺序

Koa2中间件的执行顺序严格遵循先进后出的栈结构。先注册的中间件会先执行上半部分代码，但会后执行下半部分代码。这种特性使得错误处理、日志记录等操作可以完美地包裹住核心业务逻辑。

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

app.use(async (ctx, next) => {
  console.log('认证中间件开始');
  if (!ctx.headers.authorization) {
    ctx.throw(401);
  }
  await next();
  console.log('认证中间件结束');
});

在这个例子中，计时中间件会最先开始执行，但最后结束执行，确保能准确测量整个请求处理的时间。

next()函数的关键作用

next()函数是洋葱圈模型能够双向流动的关键。它实际上是一个Promise，表示"执行下一个中间件"。当调用await next()时，当前中间件的执行会暂停，控制权交给下一个中间件。

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = err.message;
    ctx.app.emit('error', err, ctx);
  }
});

app.use(async ctx => {
  // 模拟错误
  throw new Error('Something broke!');
});

错误处理中间件通过捕获next()抛出的异常，实现了全局错误处理机制。

异步操作的处理

洋葱圈模型天然支持异步操作，这是Koa2相比Express的优势之一。每个中间件都可以安全地进行异步操作而不会阻塞事件循环。

app.use(async (ctx, next) => {
  const user = await User.findById(ctx.session.userId);
  ctx.state.user = user;
  await next();
});

app.use(async (ctx, next) => {
  const posts = await Post.find({ author: ctx.state.user._id });
  ctx.state.posts = posts;
  await next();
});

这种线性的异步代码写法比回调嵌套或Promise链更清晰易读。

中间件的组合使用

多个中间件可以组合起来形成更复杂的处理流程。Koa-compose是Koa内部用来组合中间件的工具。

const compose = require('koa-compose');

const middleware1 = async (ctx, next) => {
  console.log('middleware1 start');
  await next();
  console.log('middleware1 end');
};

const middleware2 = async (ctx, next) => {
  console.log('middleware2 start');
  await next();
  console.log('middleware2 end');
};

const all = compose([middleware1, middleware2]);

app.use(all);

这种组合方式让中间件可以模块化开发和复用。

实际应用场景

洋葱圈模型在实际开发中有多种应用场景：

1. 请求日志记录：

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

2. 响应时间头：

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

3. 数据库事务管理：

app.use(async (ctx, next) => {
  await sequelize.transaction(async t => {
    ctx.state.transaction = t;
    await next();
  });
});

错误处理的最佳实践

洋葱圈模型让错误处理变得直观。错误可以沿着中间件链向上冒泡，直到被捕获。

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {
      error: err.message
    };
    ctx.app.emit('error', err, ctx);
  }
});

app.use(async ctx => {
  // 业务逻辑中可能抛出错误
  if (ctx.query.bad) {
    ctx.throw(400, 'Bad Request');
  }
  ctx.body = { ok: true };
});

性能优化考虑

虽然洋葱圈模型很强大，但也要注意性能问题：

1. 避免不必要的中间件
2. 异步操作要合理使用await
3. 复杂逻辑可以考虑拆分到子中间件

// 不好的做法 - 同步阻塞
app.use((ctx, next) => {
  const result = computeHeavyTask(); // 同步计算
  ctx.state.result = result;
  next();
});

// 好的做法 - 异步非阻塞
app.use(async (ctx, next) => {
  const result = await computeHeavyTaskAsync(); // 异步计算
  ctx.state.result = result;
  await next();
});

与Express中间件的对比

Koa2的洋葱圈模型与Express的线性模型有本质区别：

// Express中间件 - 线性执行
app.use(function(req, res, next) {
  console.log('first');
  next();
  console.log('first after'); // 这部分会在响应发送后执行
});

app.use(function(req, res, next) {
  console.log('second');
  res.send('Hello');
});

// Koa2中间件 - 洋葱圈执行
app.use(async (ctx, next) => {
  console.log('first');
  await next();
  console.log('first after'); // 这部分会在响应发送前执行
});

app.use(async ctx => {
  console.log('second');
  ctx.body = 'Hello';
});

自定义中间件开发

开发自定义中间件时，要遵循洋葱圈模型的约定：

function logger(format) {
  return async (ctx, next) => {
    const start = Date.now();
    try {
      await next();
    } finally {
      const ms = Date.now() - start;
      console.log(format.replace(':method', ctx.method)
        .replace(':url', ctx.url)
        .replace(':time', ms));
    }
  };
}

app.use(logger(':method :url :time'));

中间件的提前返回

有时需要在中间件中提前结束请求处理：

app.use(async (ctx, next) => {
  if (!ctx.headers['x-auth']) {
    ctx.status = 401;
    ctx.body = 'Unauthorized';
    return; // 不调用next()，结束处理
  }
  await next();
});

上下文对象的传递

中间件之间通过ctx对象共享数据：

app.use(async (ctx, next) => {
  ctx.state.user = await getUser(ctx);
  await next();
});

app.use(async ctx => {
  const posts = await getPosts(ctx.state.user.id);
  ctx.body = posts;
});

测试中间件的技巧

测试洋葱圈中间件需要模拟完整的请求响应周期：

const testMiddleware = async (middleware, ctx = {}) => {
  let nextCalled = false;
  const next = jest.fn(() => {
    nextCalled = true;
    return Promise.resolve();
  });
  
  await middleware(ctx, next);
  
  return {
    ctx,
    nextCalled
  };
};

// 测试用例
test('auth middleware sets user', async () => {
  const ctx = { state: {} };
  const { nextCalled } = await testMiddleware(authMiddleware, ctx);
  expect(nextCalled).toBeTruthy();
  expect(ctx.state.user).toBeDefined();
});