跳至主要內容

koa 洋葱模型的理解

pax大约 5 分钟

Koa 的洋葱模型是其最核心的设计理念之一，它提供了一种优雅的方式来组织和执行中间件。让我详细解释这个概念：

1. 洋葱模型的基本概念

洋葱模型将中间件的执行过程比作剥洋葱，请求从外层向内层传递，响应从内层向外层返回，形成一个完整的处理流程。

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

// 最外层中间件
app.use(async (ctx, next) => {
  console.log('1. 开始处理请求');
  await next();
  console.log('6. 响应返回给客户端');
});

// 中间层中间件
app.use(async (ctx, next) => {
  console.log('2. 验证用户权限');
  await next();
  console.log('5. 记录响应日志');
});

// 最内层中间件
app.use(async (ctx, next) => {
  console.log('3. 处理业务逻辑');
  ctx.body = 'Hello World';
  console.log('4. 业务逻辑处理完成');
});

app.listen(3000);

执行顺序：

1. 开始处理请求
2. 验证用户权限
3. 处理业务逻辑
4. 业务逻辑处理完成
5. 记录响应日志
6. 响应返回给客户端

2. 洋葱模型的执行机制

核心实现原理

// 简化的洋葱模型实现
function compose(middlewares) {
  return function (context, next) {
    // last called middleware #
    let index = -1;
    return dispatch(0);
    
    function dispatch(i) {
      if (i <= index) return Promise.reject(new Error('next() called multiple times'));
      index = i;
      
      let fn = middlewares[i];
      if (i === middlewares.length) fn = next;
      
      if (!fn) return Promise.resolve();
      
      try {
        // 关键：将 next 传递给当前中间件，实现洋葱模型
        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
      } catch (err) {
        return Promise.reject(err);
      }
    }
  };
}

中间件执行流程图解

        ┌─────────────────────────────────────────────────────────┐
        │                Middleware 1 (外层)                      │
        │  ┌──────────────────────────────────────────────────┐   │
        │  │            Middleware 2 (中层)                   │   │
        │  │  ┌───────────────────────────────────────────┐   │   │
        │  │  │        Middleware 3 (内层)                │   │   │
        │  │  │                                           │   │   │
        ▼  ▼  ▼                                           ▲   ▲   ▲
请求 ──→ 1 ──→ 2 ──→ 3 ────────── 处理业务 ──────────→ 3 ──→ 2 ──→ 1 ──→ 响应

3. 实际应用场景

请求处理和响应处理分离

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

// 计时中间件
app.use(async (ctx, next) => {
  const start = Date.now();
  console.log(`${ctx.method} ${ctx.url} - 开始处理`);
  
  await next(); // 执行后续中间件
  
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

// 错误处理中间件
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = { error: err.message };
    console.error('错误:', err);
  }
});

// 认证中间件
app.use(async (ctx, next) => {
  console.log('验证用户身份');
  
  const token = ctx.headers.authorization;
  if (!token) {
    ctx.status = 401;
    ctx.body = { error: '未授权访问' };
    return; // 不调用 next()，中断执行
  }
  
  // 模拟验证通过
  ctx.user = { id: 1, name: 'Alice' };
  await next();
  
  console.log('清理认证信息');
});

// 业务逻辑中间件
app.use(async (ctx, next) => {
  console.log('执行业务逻辑');
  ctx.body = { message: 'Hello ' + ctx.user.name };
  await next();
  console.log('业务逻辑执行完成');
});

app.listen(3000);

4. 洋葱模型的优势

1. 清晰的职责分离

// 每个中间件负责特定功能
app.use(logger());        // 日志记录
app.use(errorHandler());  // 错误处理
app.use(auth());          // 身份验证
app.use(validation());    // 参数验证
app.use(cache());         // 缓存处理
app.use(router());        // 路由处理

2. 灵活的控制流

// 条件性执行后续中间件
app.use(async (ctx, next) => {
  // 只有满足条件时才执行后续中间件
  if (ctx.path.startsWith('/api')) {
    await next();
  } else {
    ctx.status = 404;
    ctx.body = { error: 'API not found' };
  }
});

// 缓存命中时跳过后续处理
app.use(async (ctx, next) => {
  const cached = getCache(ctx.url);
  if (cached) {
    ctx.body = cached;
    // 不调用 next()，直接返回缓存结果
  } else {
    await next();
    // 将结果存入缓存
    setCache(ctx.url, ctx.body);
  }
});

5. 与传统 Express 中间件的对比

Express 中间件（线性模型）

// Express - 线性执行
app.use((req, res, next) => {
  console.log('中间件1开始');
  next();
  console.log('中间件1结束'); // 这里在响应发送后执行
});

app.use((req, res, next) => {
  console.log('中间件2');
  res.send('Hello');
  next(); // 即使调用 next 也无意义，因为响应已发送
});

Koa 中间件（洋葱模型）

// Koa - 洋葱模型
app.use(async (ctx, next) => {
  console.log('中间件1开始');
  await next();
  console.log('中间件1结束'); // 这里在响应发送前执行
});

app.use(async (ctx, next) => {
  console.log('中间件2');
  ctx.body = 'Hello';
  await next(); // 可以继续执行后续逻辑
  console.log('中间件2清理工作');
});

6. 自定义洋葱模型实现

// 完整的洋葱模型实现示例
class OnionMiddleware {
  constructor() {
    this.middlewares = [];
  }
  
  use(middleware) {
    this.middlewares.push(middleware);
    return this;
  }
  
  compose() {
    return (context) => {
      let index = -1;
      
      const dispatch = (i) => {
        if (i <= index) {
          return Promise.reject(new Error('next() called multiple times'));
        }
        
        index = i;
        
        if (i === this.middlewares.length) {
          return Promise.resolve();
        }
        
        try {
          return Promise.resolve(
            this.middlewares[i](context, () => dispatch(i + 1))
          );
        } catch (err) {
          return Promise.reject(err);
        }
      };
      
      return dispatch(0);
    };
  }
}

// 使用示例
const onion = new OnionMiddleware();

onion.use(async (ctx, next) => {
  console.log('第一层开始');
  await next();
  console.log('第一层结束');
});

onion.use(async (ctx, next) => {
  console.log('第二层开始');
  await next();
  console.log('第二层结束');
});

onion.use(async (ctx, next) => {
  console.log('核心处理');
  ctx.result = '处理完成';
  await next();
});

// 执行
const context = {};
onion.compose()(context).then(() => {
  console.log('最终结果:', context.result);
});

7. 洋葱模型的最佳实践

合理组织中间件顺序

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

// 1. 错误处理（最外层）
app.use(errorHandler());

// 2. 基础设置
app.use(setup());

// 3. 日志记录
app.use(logger());

// 4. 安全相关
app.use(securityHeaders());
app.use(cors());

// 5. 身份验证
app.use(auth());

// 6. 业务逻辑
app.use(router());

// 7. 404 处理（最内层）
app.use(notFound());

总结

Koa 洋葱模型的核心特点：

  1. 双向执行：每个中间件都有"前"和"后"两个执行阶段
  2. 控制权传递：通过 await next() 传递控制权给下一个中间件
  3. 灵活控制：可以选择是否继续执行后续中间件
  4. 优雅的错误处理：可以在外层中间件统一处理内部错误
  5. 清晰的职责分离：每个中间件负责特定功能

洋葱模型使得 Koa 的中间件系统非常灵活和强大，开发者可以轻松地组合各种功能模块，构建出结构清晰、易于维护的应用程序。

默认页脚
Copyright © 2026 pax