这次我们来看一个专为 Bun 运行时设计的依赖注入DI库dunx。它的核心卖点很直接让你能在 Bun 项目中享受到类似 NestJS 那样优雅、基于装饰器的依赖注入体验但无需引入reflect-metadata这个额外的 polyfill从而保持 Bun 环境的高性能和简洁性。对于正在使用或考虑使用 Bun 构建后端服务的开发者来说dunx提供了一个关键的中间件能力。它解决了在 Bun 这个新兴、高性能的 JavaScript/TypeScript 运行时中如何结构化地管理服务、控制器、模块等组件及其依赖关系的问题。本文将带你快速了解dunx的核心能力、部署门槛、使用方法并通过一个完整的示例项目演示如何从零搭建一个具备 DI 能力的 Bun 服务。1. 核心能力速览能力项说明项目类型Bun 运行时专用的依赖注入DI容器库核心特点提供类似 NestJS 的装饰器语法Injectable,Controller,Module但无需reflect-metadata。运行时要求Bun(v1.0 或更高版本推荐)。不依赖 Node.js 原生模块。启动方式通过 Bun 命令行工具 (bun run) 启动你的应用入口文件。主要功能1. 基于装饰器的依赖声明与注入。2. 模块化组织Modules。3. 控制器Controllers自动实例化与路由绑定需结合 Web 框架如 Elysia。4. 作用域管理Singleton, Transient 等。5. 自定义 Provider值、类、工厂。是否支持 API本身是库提供编程接口API供应用代码调用用于注册和解析依赖。是否支持批量任务不直接涉及但 DI 容器管理的服务可用于处理后台任务。适合场景在 Bun 中构建需要良好架构的中大型应用、微服务、API 服务器希望代码组织清晰、易于测试和维护。不适合场景简单的脚本、无需 IoC/DI 的小型项目、必须运行在 Node.js 环境下的项目。2. 适用场景与使用边界dunx的目标用户非常明确使用 Bun 作为运行时并希望采用依赖注入模式来提升代码可维护性和可测试性的开发者。它能解决什么问题解耦与可测试性通过依赖注入业务逻辑如 Service不直接实例化其依赖如 Repository、第三方客户端而是由容器注入。这使得单元测试时可以轻松注入 Mock 对象。代码组织借鉴 NestJS 的模块化思想将相关的控制器、服务、提供者组织在同一个模块内通过模块导入导出管理依赖图结构清晰。生命周期管理容器可以管理对象的生命周期如单例模式避免重复创建优化资源使用。框架集成虽然dunx本身不提供 HTTP 服务器但它可以无缝集成到 Elysia、Hono 等 Bun 生态的 Web 框架中为控制器自动注入所需服务。使用边界与注意事项Bun 专属dunx深度依赖 Bun 的运行时特性来实现无reflect-metadata的装饰器元数据收集。无法在 Node.js 或 Deno 环境中运行。非全栈框架dunx是一个 DI 容器库不是像 NestJS 那样的全栈框架。它不内置 HTTP 服务器、模板引擎、ORM 或数据库连接器。你需要自行选择并集成这些组件。装饰器语法需要项目配置支持 TypeScript 的装饰器语法experimentalDecorators和emitDecoratorMetadata尽管后者在 Bun 中可能不是必须的但保持配置兼容性好。学习成本如果你不熟悉依赖注入或 NestJS 的设计模式需要先理解相关概念。3. 环境准备与前置条件在开始使用dunx前请确保你的开发环境满足以下要求操作系统支持 macOS, Linux, Windows (WSL 2 推荐)。Bun 运行时这是硬性要求。请确保已安装 Bun。可以通过以下命令检查和安装# 检查 Bun 版本 bun --version # 如果未安装使用官方安装脚本macOS/Linux curl -fsSL https://bun.sh/install | bash # 对于 Windows建议通过 WSL2 安装 Linux 版本或使用 Windows 安装包。建议使用 Bun v1.0 或更高版本。项目初始化创建一个新的 Bun 项目目录并初始化。mkdir my-dunx-app cd my-dunx-app bun init按照提示完成初始化会生成package.json和tsconfig.json等文件。TypeScript 配置确保tsconfig.json中启用了装饰器支持。{ compilerOptions: { // ... 其他配置 experimentalDecorators: true, emitDecoratorMetadata: true, // 虽然 dunx 不依赖它但保持开启无害 target: ES2022, module: ESNext, moduleResolution: bundler, // Bun 推荐配置 types: [bun-types] }, include: [src/**/*], exclude: [node_modules] }安装dunx在项目根目录下运行。bun add dunx安装类型定义可选但推荐为了获得更好的 TypeScript 支持安装 Bun 的类型定义。bun add -D bun-types4. 安装部署与启动方式dunx作为库被安装后其“启动”意味着你的应用启动并初始化 DI 容器。下面我们创建一个完整的迷你应用来演示。项目结构规划my-dunx-app/ ├── package.json ├── tsconfig.json ├── src/ │ ├── app.module.ts │ ├── main.ts │ ├── users/ │ │ ├── users.module.ts │ │ ├── users.controller.ts │ │ ├── users.service.ts │ │ └── dto/ │ └── shared/ │ └── logger.service.ts └── README.md步骤 1创建基础服务首先创建一个简单的日志服务它将被注入到其他类中。src/shared/logger.service.ts:import { Injectable } from dunx; Injectable() export class LoggerService { log(message: string, context?: string) { const prefix context ? [${context}] : [App]; console.log(${prefix} ${message} - ${new Date().toISOString()}); } error(message: string, context?: string) { const prefix context ? [${context}] : [App]; console.error(${prefix} ERROR: ${message}); } }步骤 2创建业务模块Users实现一个经典的 Users 模块包含 Service 和 Controller。src/users/users.service.ts:import { Injectable } from dunx; import { LoggerService } from ../shared/logger.service; // User 类型定义 export interface User { id: number; name: string; email: string; } Injectable() export class UsersService { // 依赖注入LoggerService 将被容器自动注入 constructor(private readonly logger: LoggerService) { this.logger.log(UsersService initialized, UsersService); } private users: User[] [ { id: 1, name: Alice, email: aliceexample.com }, { id: 2, name: Bob, email: bobexample.com }, ]; findAll(): User[] { this.logger.log(Fetching all users, UsersService); return this.users; } findOne(id: number): User | undefined { this.logger.log(Fetching user with id ${id}, UsersService); return this.users.find(user user.id id); } create(userData: OmitUser, id): User { const newUser { id: this.users.length 1, ...userData }; this.users.push(newUser); this.logger.log(Created new user: ${newUser.name}, UsersService); return newUser; } }src/users/users.controller.ts:import { Controller, Get, Post, Body, Param } from dunx; // 假设 dunx 提供了基础 HTTP 装饰器或者我们自定义 import { UsersService, User } from ./users.service; // 注意dunx 核心库可能不包含 Get, Post 等装饰器。 // 这些通常由集成的 Web 框架如 Elysia提供。 // 此处为演示 DI我们先使用假定的装饰器实际集成时需替换。 Controller(users) export class UsersController { constructor(private readonly usersService: UsersService) {} Get() getAllUsers() { return this.usersService.findAll(); } Get(:id) getUserById(Param(id) id: string) { const userId parseInt(id, 10); const user this.usersService.findOne(userId); if (!user) { throw new Error(User not found); } return user; } Post() createUser(Body() createUserDto: OmitUser, id) { return this.usersService.create(createUserDto); } }步骤 3定义模块将控制器和服务组织到一个模块中。src/users/users.module.ts:import { Module } from dunx; import { UsersController } from ./users.controller; import { UsersService } from ./users.service; import { LoggerService } from ../shared/logger.service; Module({ // 本模块提供的“提供者”可被注入的类 providers: [LoggerService, UsersService], // 本模块注册的控制器 controllers: [UsersController], // 导出本模块的提供者以便其他模块导入后使用 exports: [UsersService], }) export class UsersModule {}步骤 4创建应用根模块src/app.module.ts:import { Module } from dunx; import { UsersModule } from ./users/users.module; Module({ imports: [UsersModule], }) export class AppModule {}步骤 5应用入口与容器初始化这是关键步骤我们需要创建容器实例注册根模块并启动应用这里以启动一个简单的 HTTP 服务器为例使用 Bun 内置的Bun.serve。src/main.ts:import { DunFactory } from dunx; // 假设入口类是 DunFactory import { AppModule } from ./app.module; // 假设我们使用一个适配器来将 dunx 控制器与 HTTP 服务器绑定 import { createElysiaApp } from ./adapters/elysia.adapter; // 示例适配器 async function bootstrap() { // 1. 使用工厂函数创建应用实例传入根模块 const app await DunFactory.create(AppModule); // 2. 初始化与 Web 框架的集成这里以 Elysia 为例 // 注意dunx 本身可能不包含此部分需要自行实现或使用社区适配器。 // 以下代码为概念演示。 const elysiaApp createElysiaApp(app); // 这个函数会扫描所有控制器将其路由绑定到 Elysia // 3. 启动 HTTP 服务器 const server Bun.serve({ port: 3000, fetch: elysiaApp.fetch, // 使用 Elysia 的 fetch handler }); console.log( Server running at http://localhost:${server.port}); } bootstrap().catch((err) { console.error(Failed to start application:, err); process.exit(1); });步骤 6实现一个简单的适配器概念示例由于dunx核心是 DI 容器与 Web 框架的集成需要额外工作。下面是一个极其简化的概念性适配器展示如何将dunx管理的控制器与 Elysia 绑定。src/adapters/elysia.adapter.ts:import { Elysia } from elysia; import type { INestApplication } from dunx; // 假设有类似接口 // 这是一个高度简化的示例真实实现需要利用 dunx 的容器来获取控制器实例和元数据。 export function createElysiaApp(app: INestApplication): Elysia { const elysia new Elysia(); // 假设 app 有一个方法能获取所有控制器实例及其元数据路由信息 const controllers app.getControllers(); // 伪方法 for (const controller of controllers) { const { path: basePath, routes } controller.metadata; // 伪元数据 for (const route of routes) { const { method, path: routePath, handler } route; const fullPath ${basePath}${routePath}; // 将路由注册到 Elysia switch (method.toLowerCase()) { case get: elysia.get(fullPath, (context) handler.call(controller.instance, context)); break; case post: elysia.post(fullPath, (context) handler.call(controller.instance, context)); break; // ... 其他 HTTP 方法 } } } return elysia; }启动应用在package.json中配置脚本{ scripts: { dev: bun run --watch src/main.ts, start: bun run src/main.ts } }然后运行bun run dev如果一切正常控制台将输出服务器启动日志并监听在http://localhost:3000。5. 功能测试与效果验证由于dunx是一个底层库其功能测试主要围绕依赖注入的正确性、模块隔离性和生命周期管理。我们可以通过编写简单的测试脚本或直接运行应用来验证。测试 1验证基础依赖注入创建一个测试脚本不启动 HTTP 服务器直接测试服务层的依赖注入。src/test-di.ts:import { DunFactory } from dunx; import { AppModule } from ./app.module; import { UsersService } from ./users/users.service; async function testDependencyInjection() { const app await DunFactory.create(AppModule); // 从容器中解析 UsersService // 注意具体获取服务的方法取决于 dunx 的 API 设计这里使用假设的方法 get const usersService app.getUsersService(UsersService); // 伪代码可能是 app.get(UsersService) 或 container.resolve(UsersService) console.log(Testing UsersService...); const allUsers usersService.findAll(); console.log(All users:, allUsers); const user usersService.findOne(1); console.log(User with id 1:, user); const newUser usersService.create({ name: Charlie, email: charlieexample.com }); console.log(Created new user:, newUser); const updatedUsers usersService.findAll(); console.log(All users after creation:, updatedUsers); // 验证 LoggerService 是否被成功注入并使用了 // 观察控制台输出应该能看到来自 UsersService 构造器和方法的日志。 } testDependencyInjection().catch(console.error);运行此脚本bun run src/test-di.ts预期结果脚本应成功运行无报错并在控制台打印用户列表和日志信息。这证明UsersService被正确实例化且其构造函数中依赖的LoggerService也被成功注入。测试 2验证模块作用域与单例修改测试脚本尝试从容器中获取两次LoggerService检查它们是否是同一个实例假设Injectable()默认是单例。src/test-singleton.ts:import { DunFactory } from dunx; import { AppModule } from ./app.module; import { LoggerService } from ./shared/logger.service; async function testSingleton() { const app await DunFactory.create(AppModule); const logger1 app.getLoggerService(LoggerService); const logger2 app.getLoggerService(LoggerService); console.log(Are logger1 and logger2 the same instance?, logger1 logger2); // 应该输出 true // 给实例添加一个临时属性来验证 (logger1 as any).testMark marked; console.log(Does logger2 have the testMark?, (logger2 as any).testMark); // 应该输出 marked } testSingleton().catch(console.error);预期结果两个变量引用的是同一个对象证明LoggerService是以单例模式管理的。测试 3HTTP 端点测试如果集成了 Web 框架如果已经成功集成了 Elysia 并启动了服务器可以使用curl或浏览器进行测试。# 获取所有用户 curl http://localhost:3000/users # 预期返回 JSON 数组: [{id:1,name:Alice,email:aliceexample.com}, ...] # 获取特定用户 curl http://localhost:3000/users/1 # 预期返回 JSON 对象: {id:1,name:Alice,email:aliceexample.com} # 创建新用户 (POST 请求示例使用 JSON 数据) curl -X POST http://localhost:3000/users \ -H Content-Type: application/json \ -d {name:David,email:davidexample.com} # 预期返回新创建的 user 对象成功标准服务器响应正确的 HTTP 状态码如 200 OK和预期的 JSON 数据。同时观察服务器控制台应该能看到LoggerService打印的日志。6. 接口 API 与批量任务dunx本身不提供 HTTP API但它管理的服务可以被暴露为 API。如上节所示通过与 Elysia、Hono 等框架集成可以轻松构建 RESTful 或 GraphQL API。关于批量任务dunx容器管理的服务非常适合执行后台任务。你可以创建一个TaskService在其中注入LoggerService、DatabaseService等然后通过一个简单的脚本或定时任务触发器来运行。src/tasks/email.task.ts:import { Injectable } from dunx; import { LoggerService } from ../shared/logger.service; import { UsersService } from ../users/users.service; Injectable() export class EmailTaskService { constructor( private readonly logger: LoggerService, private readonly usersService: UsersService, ) {} async sendWeeklyNewsletter() { this.logger.log(Starting weekly newsletter task, EmailTask); const users this.usersService.findAll(); // 模拟发送邮件 for (const user of users) { this.logger.log(Sending newsletter to ${user.email}, EmailTask); // 实际调用邮件发送 API await new Promise(resolve setTimeout(resolve, 100)); // 模拟延迟 } this.logger.log(Weekly newsletter task completed, EmailTask); } }然后你可以创建一个独立的脚本src/run-task.ts来运行这个任务import { DunFactory } from dunx; import { AppModule } from ./app.module; import { EmailTaskService } from ./tasks/email.task; async function runTask() { const app await DunFactory.create(AppModule); const taskService app.getEmailTaskService(EmailTaskService); await taskService.sendWeeklyNewsletter(); console.log(Task finished.); process.exit(0); } runTask().catch(err { console.error(Task failed:, err); process.exit(1); });使用 Bun 的 cron 功能或系统级的 cron job 来定期执行此脚本# 手动运行一次 bun run src/run-task.ts7. 资源占用与性能观察dunx作为一个轻量级的 DI 容器库其本身的内存和 CPU 开销极低主要开销在于应用启动时容器需要扫描模块、解析提供者的依赖关系、创建实例。对于大型应用数百个提供者初始化可能会有可感知的时间通常在几百毫秒到几秒内。可以通过 Bun 的--smol模式或生产环境构建来优化启动速度。运行时依赖注入是发生在应用启动时的。运行时从容器获取实例如控制器处理请求时获取服务是直接从已创建好的实例映射中获取速度极快开销可忽略不计。内存占用容器会持有所有单例提供者的实例引用。确保将非全局状态的服务设置为Transient或Request作用域如果dunx支持可以避免内存无限制增长。性能观察建议使用bun --profile运行你的应用分析启动阶段的性能瓶颈。对于 Web 应用关注的是集成后的 Web 框架如 Elysia以及你的业务逻辑的性能dunx本身几乎不构成瓶颈。在开发环境下可以利用 Bun 的超快热重载 (--watch) 来获得流畅的体验。8. 常见问题与排查方法问题现象可能原因排查方式解决方案装饰器未生效类未被注册到容器1.tsconfig.json中未启用experimentalDecorators。2. 类文件未被模块导入链引用。1. 检查tsconfig.json配置。2. 确保使用了Injectable(),Controller(),Module()等装饰器。3. 检查包含该类的模块是否被根模块或父模块导入。1. 确认tsconfig.json设置正确。2. 确保装饰器从dunx正确导入。3. 检查模块的imports数组。依赖解析失败报错 “X is not a provider”1. 依赖的类未使用Injectable()装饰。2. 提供者未在所属模块的providers数组中声明。3. 尝试注入一个私有提供者未在模块中导出。1. 检查错误信息中提到的类。2. 确认该类是否在正确模块的providers中声明。3. 如果跨模块注入确认提供者类是否在导出模块的exports数组中。1. 为依赖类添加Injectable()。2. 在模块中声明提供者。3. 将需要跨模块使用的提供者添加到exports。启动时报 Bun 运行时错误1. Bun 版本过低。2. 使用了 Node.js 特有的 API 或模块。1. 运行bun --version检查。2. 查看错误堆栈确认是否调用了require或 Node.js 内置模块如fs,path在 Bun 中可用但行为可能略有不同。1. 升级 Bun 到最新稳定版。2. 确保所有依赖都兼容 Bun。使用bun install重新安装。与 Web 框架集成后路由不工作1. 适配器实现有误未能正确扫描和绑定控制器路由。2. 控制器或路由装饰器未被正确识别。1. 检查适配器代码确认它成功从dunx容器获取到了控制器实例和元数据。2. 在适配器中添加日志打印扫描到的控制器和路由信息。3. 直接测试控制器实例的方法是否可用。1. 参考dunx官方文档或示例查看正确的集成方式。2. 考虑使用社区维护的、成熟的适配器包如果存在。3. 暂时简化先验证纯 DI 功能再逐步集成 HTTP 层。循环依赖错误Service A 依赖 Service B同时 Service B 又依赖 Service A。查看错误堆栈定位发生循环依赖的两个类。1.重构设计提取公共逻辑到第三个 Service C。2. 使用前向引用Forward Reference如果dunx支持使用forwardRef()包装其中一个提供者。3. 改为属性注入如果支持而非构造函数注入。热重载时状态异常Bun 的--watch模式重新加载了模块但 DI 容器可能持有旧实例。观察应用行为在代码更改后是否出现旧数据或旧逻辑。1. 对于开发可以配置 Bun 在特定文件变化时完全重启应用而非热重载。2. 确保服务是无状态的或者状态易于重置。9. 最佳实践与使用建议从简单开始初次使用时先在一个小模块如一个UserModule内实现完整的 CRUD 流程验证 DI 和路由集成成功后再扩展到其他模块。保持模块高内聚将紧密相关的控制器、服务、实体等放在同一个模块内。模块应具有明确的职责边界。善用exports只有需要被其他模块使用的提供者才放入exports数组。这有助于保持模块的封装性。依赖抽象而非实现尽可能依赖接口Interface而非具体类。这能极大提升代码的可测试性和灵活性。dunx应支持基于 Token 的注入。// 定义接口 export interface ILogger { log(message: string): void; } // 实现 Injectable() export class LoggerService implements ILogger { ... } // 在模块中注册 Module({ providers: [ { provide: ILoggerToken, useClass: LoggerService } // 使用 Token ] }) // 注入时使用 Token constructor(Inject(ILoggerToken) private logger: ILogger) {}注意作用域理解 Singleton单例整个应用生命周期一个实例、Transient瞬态每次注入创建新实例、Request请求作用域每个 HTTP 请求一个实例的区别。根据业务需求选择合适的作用域避免内存泄漏或状态污染。编写单元测试依赖注入的最大优势之一就是便于测试。使用 Jest 或 Bun 的内置测试运行器可以轻松地为注入的服务编写单元测试通过 Mock 来隔离依赖。生产环境构建使用bun build将你的 TypeScript 应用打包成单个可执行文件或优化后的 JavaScript 文件可以提升启动速度和运行性能。关注社区生态dunx是一个较新的库积极关注其 GitHub 仓库的 Issues、Discussions 和 Releases以获取最新的功能、修复和最佳实践。dunx为 Bun 生态带来了一个熟悉且强大的依赖注入解决方案它降低了在 Bun 中构建结构化应用程序的架构复杂度。虽然目前可能需要自己处理与 Web 框架的集成部分但其核心的 DI 功能稳定且直观。对于已经熟悉 NestJS 并希望迁移到或尝试 Bun 的团队dunx是一个值得投入时间评估的桥梁。建议从本文的示例项目出发亲手搭建一遍你会对如何在 Bun 中利用依赖注入组织代码有更深刻的理解。