深入浅出：在 Koa 中实现优雅的中间件依赖注入

1. 引言：为什么需要依赖注入？

在现代 [Web 开发]中，随着业务逻辑越来越复杂，代码的可维护性和可测试性变得至关重要。传统的模式中，模块通常直接在内部 require 或 new 它们所依赖的资源（如数据库连接、配置对象、服务层等），这会导致以下几个问题：

紧耦合（Tight Coupling） ：模块与其依赖项紧密绑定，难以单独测试或替换。
难以测试（Hard to Test） ：为了测试一个模块，你必须模拟（mock）其内部所有的依赖，这通常很困难。
代码臃肿：每个模块都需要自己管理依赖的创建和获取逻辑。

依赖注入（Dependency Injection, DI） 是一种设计模式，它通过"控制反转（Inversion of Control, IoC）"来解决这些问题。核心思想是：一个对象或函数不从内部创建其依赖项，而是由外部容器（或调用者）创建并"注入"给它。

在 Koa 中，我们的[业务逻辑]主要写在中间件（Middleware） 和控制器（Controller） 中。本文将探讨几种在 Koa 中间件中实现依赖注入的优雅方案。

2. 方案一：利用 Koa 上下文 (Context) - 最 Koa 的方式

这是最自然、最符合 Koa 哲学的方式。Koa 的上下文对象 ctx 贯穿整个请求生命周期，我们可以利用它作为依赖的载体。

2.1 基础实现：在应用启动时挂载依赖

ini 复制代码

// app.js
const Koa = require('koa');
const app = new Koa();

// 模拟一些依赖项
const databaseService = {
  getUser: async (id) => ({ id, name: `User ${id}` })
};
const logger = {
  info: (msg) => console.log(`[INFO] ${new Date().toISOString()}: ${msg}`)
};
const config = {
  appName: 'My-Koa-App'
};

// ！！！核心步骤：将依赖挂载到 ctx 上！！！
// 使用一个中间件在请求一开始就注入依赖
app.use(async (ctx, next) => {
  // 将依赖注入到 ctx.state 或直接挂载到 ctx 上
  // ctx.state 是 Koa 推荐的命名空间，用于存储请求级别的状态数据
  ctx.state.dependencies = {
    db: databaseService,
    logger: logger,
    config: config
  };
  
  // 或者也可以直接挂载到 ctx 上 (更常见)
  ctx.db = databaseService;
  ctx.logger = logger;
  ctx.config = config;
  
  await next();
});

// 业务中间件：现在可以方便地使用注入的依赖了
app.use(async (ctx) => {
  // 从 ctx 上获取依赖
  const user = await ctx.db.getUser(123);
  ctx.logger.info(`Fetched user: ${user.name}`);
  
  ctx.body = {
    app: ctx.config.appName,
    user: user
  };
});

app.listen(3000);

AI写代码javascript
运行
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647

2.2 进阶：使用工厂函数创建请求级别的依赖

有些依赖（如数据库连接）可能需要为每个请求创建一个新的实例，或者依赖于请求本身（如获取当前用户信息的 Service）。

javascript 复制代码

// dependency-factory.js
class RequestScopedService {
  constructor(requestId) {
    this.requestId = requestId;
  }
  
  doSomething() {
    console.log(`Doing something for request ${this.requestId}`);
  }
}

// 创建依赖的工厂函数
function createDependencies(ctx) {
  // 可以根据 ctx 的信息来创建依赖
  // 例如，从 header 中获取 request-id
  const requestId = ctx.get('X-Request-ID') || Math.random().toString(36).substr(2);
  
  return {
    requestService: new RequestScopedService(requestId),
    // ... 其他依赖
  };
}

// app.js
app.use(async (ctx, next) => {
  // 为每个请求创建新的依赖实例
  const deps = createDependencies(ctx);
  
  // 将工厂函数创建的依赖注入到 ctx 上
  Object.assign(ctx, deps);
  
  await next();
});

app.use(async (ctx) => {
  // 使用请求级别的依赖
  ctx.requestService.doSomething();
  ctx.body = { status: 'ok' };
});

AI写代码javascript
运行
123456789101112131415161718192021222324252627282930313233343536373839

优点：

简单直观：完全遵循 Koa 的设计模式。
易于理解 ：依赖关系清晰可见，在中间件中通过 ctx 直接访问。
请求级别作用域：可以轻松创建请求级别的依赖实例。

缺点：

类型不安全 ：TypeScript 下需要额外声明扩展的 ctx 属性。
依赖解析：依赖较多时，初始化的中间件会变得臃肿。

3. 方案二：使用高阶函数 (Higher-Order Function) 包装中间件

高阶函数是返回函数的函数。我们可以利用它来"预配置"中间件，提前注入它所需要的依赖。

3.1 基础实现

javascript 复制代码

// 定义一个"中间件工厂"，它接收依赖，返回一个真正的 Koa 中间件
function createAuthMiddleware(userService, logger) {
  // 返回一个标准的 Koa 中间件函数
  return async function authMiddleware(ctx, next) {
    const token = ctx.headers.authorization;
    
    if (!token) {
      ctx.throw(401, 'No token provided');
    }
    
    try {
      // 使用注入的 userService
      const user = await userService.validateToken(token);
      // 可以将用户信息挂载到 ctx 上供后续中间件使用
      ctx.state.user = user;
      // 使用注入的 logger
      logger.info(`User ${user.id} authenticated`);
      await next();
    } catch (error) {
      logger.error('Authentication failed', error);
      ctx.throw(401, 'Invalid token');
    }
  };
}

// 模拟依赖
const userService = {
  validateToken: async (token) => ({ id: 123, name: 'John Doe' })
};
const logger = console;

// 应用启动时，创建并使用中间件
app.use(createAuthMiddleware(userService, logger));

// 后续中间件可以安全地使用 ctx.state.user
app.use(ctx => {
  ctx.body = { message: `Hello, ${ctx.state.user.name}` };
});

AI写代码javascript
运行
1234567891011121314151617181920212223242526272829303132333435363738

3.2 更优雅的柯里化 (Currying) 写法

如果依赖项很多，可以分步注入。

javascript 复制代码

// 柯里化风格的中间件工厂
function createMiddleware(dependencies) {
  // 第一步：注入所有通用依赖
  return function(middlewareFunc) {
    // 第二步：传入中间件逻辑函数
    return async function(ctx, next) {
      // 第三步：在执行时，将依赖和 ctx 一起传给业务逻辑
      return middlewareFunc(ctx, next, dependencies);
    };
  };
}

// --- 使用方法 ---
// 1. 初始化注入器
const inject = createMiddleware({
  db: databaseService,
  logger: logger,
  emailService: emailService
});

// 2. 定义业务中间件逻辑，它接收依赖作为参数
async function userController(ctx, next, { db, logger }) {
  const users = await db.getUsers();
  logger.info('Fetched users');
  ctx.body = users;
}

// 3. 使用 inject 包装中间件逻辑，生成标准的 Koa 中间件
app.use(inject(userController));

AI写代码javascript
运行
1234567891011121314151617181920212223242526272829

优点：

显式依赖：中间件需要什么依赖，一目了然。
高可测试性 ：测试 userController 函数时，可以轻松传入模拟的 db 和 logger。
复用性好：同一个中间件逻辑可以用不同的依赖配置。

缺点：

语法稍复杂：需要理解高阶函数和柯里化的概念。
破坏标准签名 ：生成的中间件函数签名不再是标准的 (ctx, next)，可能让不熟悉该模式的人困惑。

4. 方案三：使用 Awilix 等专业的 DI 容器

对于大型项目，手动管理依赖会变得非常繁琐。这时可以使用专业的 DI 容器库，如 Awilix。Awilix 功能强大，支持多种生命周期（单例、瞬态、请求作用域）和解析方式。

4.1 安装 Awilix

复制代码

npm install awilix awilix-koa

AI写代码bash
1

4.2 完整示例

javascript 复制代码

const { createContainer, asClass, asValue, asFunction } = require('awilix');
const { scopePerRequest } = require('awilix-koa');

// 1. 创建容器
const container = createContainer();

// 2. 声明依赖（"注册"）
container.register({
  // 注册一个常量值，例如配置
  config: asValue({ appName: 'My App' }),
  
  // 注册一个 Class，生命周期为 SINGLETON（单例）
  userService: asClass(UserService).singleton(),
  
  // 注册一个 Class，但每次解析都创建一个新实例（瞬态）
  // transientTask: asClass(TransientTask).transient(),
  
  // 注册一个已有的实例
  logger: asValue(console),
  
  // 注册一个工厂函数
  // connection: asFunction(createConnection).singleton()
});

// 假设我们有一个 UserService
class UserService {
  constructor({ logger /* 依赖注入 */ }) {
    this.logger = logger;
  }
  
  async getUser(id) {
    this.logger.info(`Fetching user ${id}`);
    return { id, name: `User ${id}` };
  }
}

// 3. 集成到 Koa
const Koa = require('koa');
const app = new Koa();

// ！！！核心集成：为每个请求创建一个作用域！！！
app.use(scopePerRequest(container));

// 4. 在中间件中使用依赖
app.use(async (ctx) => {
  // 从请求的作用域中解析出依赖
  // 注意：这里解析的是 userService，它在容器中注册的名字
  const userService = ctx.request.container.resolve('userService');
  const config = ctx.request.container.resolve('config');
  
  const user = await userService.getUser(123);
  
  ctx.body = {
    app: config.appName,
    user: user
  };
});

app.listen(3000);

AI写代码javascript
运行
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859

Awilix 工作流程详解：

创建容器：一个全局的、根级别的容器。
注册依赖 ：告诉容器如何创建每个依赖（asValue, asClass, asFunction）以及它们的生命周期（singleton, scoped, transient）。
请求作用域 ：scopePerRequest 中间件为每个到来的请求基于根容器创建一个新的子容器（作用域） ，并将其挂载到 ctx.request.container。
解析依赖 ：在中间件中，通过 ctx.request.container.resolve('name') 来获取依赖。容器会自动处理依赖树（如果 UserService 又依赖 logger，容器会自动注入）。

优点：

强大的管理能力：自动处理复杂的依赖关系图。
灵活的生命周期：完美支持单例、请求作用域、瞬态等模式。
极高的可测试性：整个应用的依赖都由容器管理，测试时可以整体替换实现。
面向接口编程：鼓励基于接口而非实现编程，进一步解耦。

缺点：

学习曲线：需要理解 DI 容器的概念和 Awilix 的 API。
复杂度：对于小型项目来说可能是过度设计。

5. 总结与对比

方案	适用场景	优点	缺点
利用 Koa 上下文 (`ctx`)	中小型项目，快速开发	简单直观，符合 Koa 哲学，无需额外库	类型不安全，依赖多时初始化代码臃肿
高阶函数包装	非常注重可测试性的项目	依赖显式声明，测试极其方便，复用性好	语法稍复杂，破坏了中间件标准签名
Awilix DI 容器	大型复杂企业级应用	功能强大，自动化程度高，生命周期管理完善	学习曲线较陡，对于小项目是过度设计

如何选择？

如果你是初学者或项目很简单，从方案一开始。
如果你非常看重测试和代码的纯粹性，方案二是你的最佳选择。
如果你的项目正在变得庞大且复杂，需要良好的架构来维护，那么投资时间学习并使用方案三是值得的。