1. 先搞清楚dunx解决的是什么问题如果你在用 Bun 做后端开发尤其是从 NestJS 这类框架转过来或者想在一个新项目里引入依赖注入DI来提升代码的可测试性和模块化程度那你可能已经踩过坑了。最大的坑就是“反射元数据”reflect-metadata。在 Node.js 环境下很多 DI 库包括 NestJS 早期版本都依赖这个 polyfill 来读取 TypeScript 装饰器注入的类型信息。但 Bun 作为一个追求性能和现代性的运行时对这套机制的支持并不完美甚至可以说有点“水土不服”。直接引入reflect-metadata可能会遇到各种兼容性问题比如装饰器不生效、注入的依赖为undefined或者构建、打包时出现奇怪的错误。dunx这个库瞄准的就是这个痛点。它的核心价值非常明确在 Bun 运行时中提供一套类似 NestJS 风格的依赖注入机制但完全不需要reflect-metadata。它通过自己的方式解析依赖关系让你能在 Bun 项目里用上熟悉的Injectable()、Inject()这些装饰器语法写出结构清晰、易于测试的代码同时避开 Bun 环境下那些恼人的兼容性雷区。所以这篇文章适合两类人看一是正在评估 Bun 作为后端运行时但担心生态和开发体验的开发者二是已经在用 Bun但受够了手动管理依赖或者想引入更工程化架构的实践者。最值得关注的不是它实现了 DI这本身不稀奇而是它如何绕开reflect-metadata这个“历史包袱”在 Bun 里干净利落地跑起来。2. 环境准备与项目初始化别急着写代码在动手引入dunx之前先把环境理清楚。很多问题不是出在库本身而是前置条件没满足。2.1 确认你的 Bun 版本和项目配置首先确保你用的是相对较新的 Bun 版本。虽然dunx可能对版本要求不高但为了避免一些底层 API 的差异建议使用 Bun 1.0 以上的稳定版本。打开终端检查bun --version其次你的项目需要是一个 TypeScript 项目或者至少是使用了 TypeScript 的 JSDoc 类型。因为dunx的装饰器语法和类型推断严重依赖 TypeScript 的编译时类型系统。检查你的tsconfig.json关键配置项需要开启{ compilerOptions: { experimentalDecorators: true, // 必须开启 emitDecoratorMetadata: false, // 关键必须为 false我们不需要它 // ... 其他配置 } }这里有个非常重要的细节把emitDecoratorMetadata设为false。这是和传统需要reflect-metadata的 DI 方案最大的不同。传统方案需要这个选项为true让 TypeScript 编译器在生成的 JavaScript 代码中嵌入类型元数据然后reflect-metadata在运行时读取。dunx不走这条路所以完全不需要生成这些元数据设为false反而更干净编译速度也更快。2.2 安装dunx并理解它的依赖接下来安装dunxbun add dunx安装完成后看一下package.json。你会发现dunx的依赖非常轻量它没有引入reflect-metadata也没有依赖一堆复杂的反射工具。它的核心可能就是利用 Bun 的运行时特性和 TypeScript 的编译器 API通过ts-morph或类似工具在编译时分析在构建阶段就完成依赖关系的解析而不是在运行时去反射。这就是它聪明的地方把类型解析从运行时挪到了编译时。对于 Bun 这种自带快速打包和运行能力的工具链来说这种思路非常匹配。3. 核心概念与基本用法从定义一个服务开始理解了原理我们来看怎么用。我会用一个从简单到复杂的例子把dunx的核心装饰器和容器用法过一遍。3.1 定义可注入的服务Injectable假设我们有一个用户服务负责处理用户相关的逻辑。在 NestJS 里你会用Injectable()。在dunx里一模一样。首先创建一个user.service.ts// src/services/user.service.ts import { Injectable } from dunx; Injectable() export class UserService { private users new Mapnumber, string(); constructor() { // 模拟一些初始数据 this.users.set(1, Alice); this.users.set(2, Bob); } getUserName(id: number): string | undefined { return this.users.get(id); } addUser(id: number, name: string) { this.users.set(id, name); } }看到Injectable()了吗它告诉dunx的容器“这个类可以被实例化并且它的依赖可以被自动注入。” 目前它没有依赖其他类所以构造函数是空的。3.2 创建模块并注册服务Module在 NestJS 里服务需要属于某个模块。dunx也采用了类似的概念来组织依赖关系。创建一个用户模块// src/modules/user.module.ts import { Module } from dunx; import { UserService } from ../services/user.service; Module({ providers: [UserService], // 在这里声明本模块提供的服务 exports: [UserService], // 导出后其他模块才能注入它 }) export class UserModule {}Module装饰器接受一个配置对象providers: 声明本模块内部可以创建和注入的类。exports: 声明哪些providers是对外公开的允许被其他模块导入使用。3.3 在控制器或其他服务中注入依赖Inject现在假设我们有一个认证服务它需要用到UserService来验证用户。我们来演示如何注入。创建auth.service.ts// src/services/auth.service.ts import { Injectable, Inject } from dunx; import { UserService } from ./user.service; Injectable() export class AuthService { constructor( Inject(UserService) private readonly userService: UserService ) {} validateUser(id: number): boolean { const name this.userService.getUserName(id); return name ! undefined; } }关键点在于constructor里的Inject(UserService)。这明确告诉dunx容器“我需要一个UserService的实例请把它注入到这个位置。” 由于UserService已经在UserModule中声明并导出只要AuthService所在的模块导入了UserModule这个注入就能成功。Inject()装饰器是必须的吗对于基于类型的注入在大多数情况下dunx可能也能像 NestJS 一样通过 TypeScript 的类型信息自动推断省略Inject()。但我的建议是在初期或者任何你觉得不放心的时候显式地写上Inject()。这能让依赖关系一目了然也避免了因类型系统复杂推导可能带来的意外。3.4 创建应用根模块并启动容器最后我们需要一个根模块来组装一切并引导容器。创建app.module.ts// src/app.module.ts import { Module } from dunx; import { UserModule } from ./modules/user.module; import { AuthService } from ./services/auth.service; Module({ imports: [UserModule], // 导入其他模块 providers: [AuthService], // 声明根模块自己的服务 }) export class AppModule {}现在如何获取一个已经解析好所有依赖的AuthService实例呢我们需要使用dunx的容器。在一个入口文件例如index.ts或server.ts中// src/index.ts import { createContainer } from dunx; import { AppModule } from ./app.module; async function bootstrap() { // 1. 根据根模块创建容器 const container await createContainer(AppModule); // 2. 从容器中解析出你需要的服务实例 const authService await container.resolve(AuthService); // 3. 使用它 const isValid authService.validateUser(1); console.log(User 1 is valid: ${isValid}); // 应该输出 true // 4. 记得对于长期运行的应用如HTTP服务器容器需要被持有和管理 // 对于一次性脚本用完即可。对于服务器容器通常伴随应用生命周期。 } bootstrap().catch(console.error);createContainer是一个异步函数它会分析AppModule及其导入的所有子模块构建出完整的依赖关系图。container.resolve()则是根据这个关系图创建出你请求的类的实例并递归地创建和注入它所有依赖的实例。4. 进阶用法与生产实践考量基本流程跑通了但真实项目会更复杂。下面这些是决定你是否能把它用在生产环境的关键。4.1 处理循环依赖循环依赖是 DI 系统中的经典难题。A 依赖 BB 又依赖 A。dunx作为 NestJS 风格的库很可能提供了类似的解决方案前向引用Forward Reference。假设UserService和AuthService互相依赖虽然设计上应避免但有时难以绕开// user.service.ts import { Injectable, Inject, forwardRef } from dunx; import { AuthService } from ./auth.service; Injectable() export class UserService { constructor( Inject(forwardRef(() AuthService)) private authService: AuthService ) {} } // auth.service.ts import { Injectable, Inject } from dunx; import { UserService } from ./user.service; Injectable() export class AuthService { constructor( Inject(UserService) private userService: UserService ) {} }forwardRef(() AuthService)的作用是打破解析死循环。它告诉容器“先给我一个AuthService的引用占位符等所有依赖都创建得差不多了再把这个占位符替换成真正的实例。” 这是一种妥协方案能解决问题但会让依赖关系变得隐晦。最好的实践依然是审视架构尽量避免循环依赖。4.2 自定义 Provider 与值注入不是所有依赖都是一个类。有时你想注入一个配置对象、一个字符串常量或者一个外部库的实例。dunx应该支持自定义 Provider。在模块的providers数组里你可以提供一个更复杂的对象// config.module.ts import { Module, ValueProvider } from dunx; const databaseConfig: ValueProvider { provide: DATABASE_CONFIG, // 使用一个字符串或 Symbol 作为令牌token useValue: { host: localhost, port: 5432, username: myuser, // ... 其他配置 }, }; Module({ providers: [databaseConfig], exports: [DATABASE_CONFIG], // 同样需要导出 }) export class ConfigModule {}然后在服务中通过Inject配合这个令牌来注入// database.service.ts import { Injectable, Inject } from dunx; Injectable() export class DatabaseService { constructor( Inject(DATABASE_CONFIG) private config: any ) { console.log(Connecting to ${config.host}:${config.port}); } }provide字段就是依赖标识符token。useValue表示直接使用这个固定值。除了useValue常见的还有useClass: 指定一个类来创建实例默认行为。useFactory: 用一个工厂函数动态创建实例工厂函数本身可以注入其他依赖。useExisting: 给一个已有的 provider 起个别名。这些高级用法让你能灵活地管理各种依赖。4.3 作用域Scope管理单例 vs 请求级在 Web 服务器中有些服务应该是全局单例的如数据库连接池、配置服务有些则应该为每个 HTTP 请求创建一个新实例如请求上下文、用户会话。NestJS 提供了SINGLETON和REQUEST等作用域。dunx作为轻量级方案可能默认所有都是单例SINGLETON或者提供了简单的作用域控制。你需要查看dunx的文档或源码确认它是否支持以及如何设置作用域。例如可能通过Injectable({ scope: Scope.REQUEST })来声明。如果它不支持请求作用域而你的项目需要那你可能需要自己结合 Bun 的上下文或中间件在每个请求中手动从容器创建子容器或解析特定服务这会增加复杂性。我的建议是如果dunx没有明确支持请求作用域那么在 Bun 的 HTTP 框架如 Elysia、Hono的中间件里谨慎使用依赖注入来管理请求级状态或者考虑将请求相关的数据通过参数传递而不是注入。4.4 与 Bun 的 HTTP 框架集成dunx本身只是一个 DI 容器它不处理 HTTP。你需要把它和你选择的 Bun Web 框架结合起来。以目前 Bun 生态里比较流行的 Elysia 为例思路是在启动 Elysia 应用之前先创建好dunx容器。然后将容器实例或者从容器中解析出的核心服务如业务逻辑层服务通过上下文Context传递给每个请求处理器。// src/index.ts import { Elysia } from elysia; import { createContainer } from dunx; import { AppModule } from ./app.module; import { UserService } from ./services/user.service; async function bootstrap() { const container await createContainer(AppModule); const userService await container.resolve(UserService); const app new Elysia() // 将容器或服务注入到 Elysia 的上下文状态中 .state(container, container) .state(userService, userService) .get(/user/:id, ({ params: { id }, store }) { // 从 store 中获取服务 const service store.userService; const name service.getUserName(parseInt(id)); return { id, name }; }) .listen(3000); console.log(Server is running at ${app.server?.url}); } bootstrap();这是一种简单直接的集成方式。更复杂的集成可能需要为每个请求创建子容器如果 DI 库支持以实现请求级别的隔离和更干净的依赖管理。5. 常见问题排查与调试指南用上新东西难免会遇到问题。下面是我在测试类似 DI 方案时通常会按顺序排查的几个点。5.1 服务实例为undefined或null这是最常见的问题。注入失败了。检查模块导入导出链这是最可能的原因。确保你要注入的服务如UserService在其所属模块UserModule的exports数组中。然后确保使用该服务的模块如AppModule在其imports数组中导入了UserModule。少一步都不行。检查Injectable()装饰器确认服务类本身确实用Injectable()装饰了。有时候复制粘贴会漏掉。检查Inject()装饰器如果使用了Inject()确认传入的令牌Token是正确的。如果是类直接传类引用UserService如果是字符串或 Symbol确保两边完全一致包括大小写。检查循环依赖如果存在循环依赖且没有正确处理使用forwardRef容器可能在解析过程中陷入死循环或提前返回一个未完成的实例。查看容器解析日志如果dunx提供了调试模式或日志选项打开它。查看容器在解析AuthService时是如何查找UserService的这能最直接地发现问题。5.2 运行时错误Cannot resolve dependency...容器明确告诉你某个依赖无法解析。确认依赖是否已注册这个依赖比如一个LoggerService是否在任何一个已导入模块的providers列表里它可能根本没被任何模块提供。检查作用域冲突如果你尝试在一个非请求作用域的服务中注入一个请求作用域的服务假设dunx支持作用域就会出错。单例服务不能依赖生命周期更短的服务。检查自定义 Provider 的令牌如果你使用了useValue、useFactory确保provide的令牌和Inject()里用的令牌是同一个对象严格相等。5.3 构建或启动时报类型错误这通常和 TypeScript 配置或 Bun 的运行时有关。复查tsconfig.json确保experimentalDecorators: true且emitDecoratorMetadata: false。这是dunx无反射模式的关键。清理并重启有时 Bun 的缓存或 TypeScript 的编译缓存会导致奇怪的问题。尝试运行bun run --bun来强制使用 Bun 的运行时或者删除node_modules/.cache和可能的输出目录如dist然后重新安装依赖并启动。检查dunx版本兼容性查看dunx的官方文档或 GitHub Issues确认你使用的版本与你的 Bun 版本、TypeScript 版本是否兼容。5.4 性能与内存考虑对于中小型项目dunx这种编译时分析的 DI 方案通常性能很好因为依赖图在启动时就已经构建完成运行时只是简单的对象查找和实例化。但需要注意启动时间如果项目有几百上千个服务容器创建阶段createContainer的分析和构建可能会比运行时反射的方案稍慢因为它在编译/启动时做了更多工作。但这通常是一次性成本。内存占用所有标记为单例的服务会在容器生命周期内一直存在。确保单例服务没有意外地持有大量临时数据或请求级别的引用以免内存泄漏。Tree-shaking由于依赖关系是在编译时通过装饰器声明的这可能会对 Bun或任何打包工具的 Tree-shaking 优化产生影响。未被任何模块providers引用的服务类理论上可以被摇掉但最好在最终打包后检查一下产物体积。6. 总结什么时候该用dunx什么时候再想想经过上面这一轮拆解你应该对dunx有了比较全面的认识。最后我分享一下我的判断标准帮你决定是否要在项目里引入它。适合使用dunx的场景你的项目基于 Bun且确定要采用依赖注入架构。你欣赏 NestJS 的清晰分层但不想或不能在 Bun 里引入reflect-metadata。项目规模中等模块边界清晰。DI 在管理跨模块的复杂依赖时优势明显。你追求更好的可测试性。通过 DI你可以轻松地用 Mock 服务替换真实实现进行单元测试。你愿意接受一定的“框架约定”。你需要遵循它的模块、装饰器规则来组织代码。可能需要再考虑一下的场景超小型项目或原型如果只有几个简单的路由和函数手动实例化或者用更轻量的方案如手动工厂函数可能更直接避免过度设计。深度依赖某个特定 Bun Web 框架的高级特性如果你用的框架如 Elysia有自己成熟的插件和状态管理生态并且与dunx的集成需要大量胶水代码那就要评估收益是否大于成本。团队对装饰器和 DI 模式不熟悉引入新概念有学习成本如果团队更习惯函数式或更直接的编程风格强推 DI 可能会降低开发效率。你需要极其精细的作用域控制如瞬态、请求级如果dunx的文档显示其作用域模型比较简单而你的业务对此有强需求就需要仔细测试或寻找替代方案。我的个人建议是先在一个独立的子模块或新项目中尝试dunx。从定义一个服务、一个模块到成功注入并使用开始。重点验证它在你的开发环境包括热重载、调试和生产构建流程中是否顺畅。把单例模式下的基本流程跑通、跑稳再逐步应用到更复杂的循环依赖、动态提供者等场景。这样能最大程度地控制风险并让你真正体会到它在 Bun 环境下带来的开发体验提升。