Excalidraw依赖注入模式：提升代码可测试性

Excalidraw 中的依赖注入：让代码更易测试、更灵活扩展

在现代前端开发中，我们常常面临一个看似简单却影响深远的问题：如何写出既能快速迭代，又方便测试、易于维护的代码？尤其是在构建像 Excalidraw 这类功能丰富、集成了 AI 生成、实时协作和多种存储机制的复杂应用时，模块之间的耦合很容易成为技术债的源头。

Excalidraw 作为一款开源的手绘风格白板工具，不仅以“拟物感”界面赢得开发者喜爱，其背后的设计哲学同样值得深挖。它没有依赖重型框架来管理依赖关系，而是通过轻量级但极具实效的依赖注入模式，实现了核心逻辑与外部服务的彻底解耦。这种设计不是为了炫技，而是为了解决真实世界中的工程难题——比如“怎么在不调用 OpenAI 的情况下测试 AI 生成功能？”或者“如何让团队成员轻松替换协作后端进行调试？”

答案就藏在它的架构选择里：把“谁来做这件事”交给运行时决定，而不是写死在代码中。

从一个问题开始：为什么不能直接 new？

设想你在实现一个自然语言转图表的功能。最直观的做法可能是这样的：

class DiagramCommandHandler { async handleNaturalLanguageInput(text: string) { const generator = new OpenAIGenerator(import.meta.env.VITE_OPENAI_KEY); return await generator.generateDiagram(text); } }

初看没问题，但一旦要写单元测试，麻烦就来了。你得联网、得有 API Key、还得处理异步请求——这已经不是在测你的命令处理器，而是在测网络稳定性了。更糟的是，如果未来想换成 Anthropic 或本地模型，你就得改每一处new的地方。

这就是典型的紧耦合：业务逻辑和具体实现绑在一起，无法独立演进。

而依赖注入的核心思想很简单：不要自己创建依赖，让别人把需要的服务“送过来”。就像餐厅厨师不需要自己种菜，只需要拿到清洗切好的食材即可开工。

在 Excalidraw 的实践中，这个“送食材”的过程是通过构造函数参数完成的：

class DiagramCommandHandler { constructor(private aiGenerator: AIGenerator) {} // 注入点 async handleNaturalLanguageInput(text: string) { return await this.aiGenerator.generateDiagram(text); // 只关心接口，不关心是谁 } }

这样一来，无论是真实的 OpenAI 实现，还是返回固定数据的 Mock 对象，都可以无缝接入。测试时传入模拟器，生产环境传入真实客户端，完全不影响逻辑本身。

轻量级 DI 如何运作？没有框架也能行

很多人一听到“依赖注入”，立刻想到 Angular 那样复杂的 IoC 容器。但在 Excalidraw 这样的项目中，根本不需要引入重量级解决方案。它的做法更接近“手动装配”——干净、可控、无额外依赖。

整个流程可以拆解为四个步骤：

1. 定义契约（接口）
2. 提供实现（类）
3. 按需选择（配置）
4. 组装注入（初始化）

1. 接口先行：明确“能做什么”，而非“怎么做”

interface AIGenerator { generateDiagram(prompt: string): Promise<ExcalidrawElement[]>; }

这个接口就是所有 AI 图形生成服务必须遵守的协议。只要符合这个签名，不管是调用云端大模型，还是本地规则引擎，都能被系统接纳。

2. 多种实现并存：真实 vs 模拟

class OpenAIGenerator implements AIGenerator { /* 真实调用 */ } class MockAIGenerator implements AIGenerator { /* 固定返回矩形 */ }

两种实现共用同一接口，意味着它们在类型层面完全兼容。你可以随时切换，而不必修改使用方代码。

3. 启动时决策：根据环境决定用哪个

function createAppEnvironment(useMock = false) { const aiGenerator: AIGenerator = useMock ? new MockAIGenerator() : new OpenAIGenerator(apiKey); return new DiagramCommandHandler(aiGenerator); }

这里的关键在于——依赖的绑定发生在应用启动阶段，而不是在业务逻辑执行过程中。这种“延迟绑定”赋予了系统极大的灵活性。

4. 使用时不感知：只依赖抽象，不依赖具体

最终，DiagramCommandHandler根本不知道自己用的是哪个生成器。它只做一件事：调用generateDiagram并处理结果。这种“无知”恰恰是高内聚低耦合的体现。

架构图里的秘密：分层清晰，职责分明

Excalidraw 的整体结构可以用一张简图来概括：

+------------------+ | UI 层 | | (React 组件) | +--------+---------+ | v +--------+---------+ | 命令处理器 | | (业务逻辑) | +--------+---------+ | v +--------+---------+ | 依赖注入容器 | | (服务注册与分发) | +--------+---------+ | v +--------+---------+ | 服务实现层 | | - AI 生成 | | - 存储适配 | | - 协作同步 | +------------------+

每一层都有明确边界：

• UI 层专注交互；
• 命令处理器封装行为逻辑；
• 服务层提供跨平台能力；
• 容器层负责连接一切。

这种分层方式避免了“上帝组件”的出现。每个部分都可以单独测试、独立替换，甚至由不同团队维护。

实战价值：不只是理论，更是生产力提升

让我们看看这种设计在实际开发中带来了哪些改变。

✅ 测试变得轻快可靠

以前测一个带网络请求的功能，可能要等几秒，还容易因网络波动失败。现在呢？

test("should return mock elements when using mock generator", async () => { const handler = new DiagramCommandHandler(new MockAIGenerator()); const result = await handler.handleNaturalLanguageInput("随便画点啥"); expect(result).toHaveLength(1); expect(result[0].type).toBe("rectangle"); });

零依赖、毫秒级执行、结果可预测——这才是理想的单元测试体验。

更重要的是，你可以轻松覆盖各种边界情况：空响应、错误输入、超长文本……这些在真实 API 上很难稳定复现的场景，在 Mock 中只需几行代码就能搞定。

🔁 支持多后端自由切换

假设团队想尝试使用 Claude 替代 GPT，怎么办？

只需新增一个实现类：

class ClaudeGenerator implements AIGenerator { async generateDiagram(prompt: string): Promise<ExcalidrawElement[]> { // 调用 Anthropic API } }

然后在初始化时换一下：

const aiGenerator = new ClaudeGenerator();

其余代码全部不动。这就是开闭原则的实际落地：对扩展开放，对修改关闭。

🧩 环境隔离不再是负担

开发、测试、生产环境往往需要不同的配置组合。传统做法是到处加if (process.env.NODE_ENV)，既难读又易出错。

而采用依赖注入后，配置集中在一个入口点：

切换环境只需调整初始化逻辑，无需改动任何业务代码。部署脚本也可以更简洁，比如：

vite build --mode production # vs vite build --mode development

对应的构建配置会自动加载不同的服务实现。

工程实践建议：别让好模式变成过度设计

虽然依赖注入好处多多，但也并非银弹。在 Excalidraw 的实践中，有几个关键经验值得借鉴：

1. 接口粒度要合理

太细碎的接口会导致大量冗余抽象，增加维护成本；太粗放又失去灵活性。建议按功能域划分接口，例如：

• AIGenerator：专用于图形生成
• FileExporter：导出为 PNG/SVG/JSON
• CollaborationAdapter：处理消息收发

每个接口职责单一，便于替换和测试。

2. 生命周期管理不可忽视

大多数服务应作为单例存在，尤其是涉及网络连接或昂贵初始化操作的（如 WebSocket、AI 客户端）。重复创建不仅浪费资源，还可能导致状态混乱。

可以在容器中统一管理实例生命周期：

// services.ts let _aiGenerator: AIGenerator | null = null; export function getAIGenerator(): AIGenerator { if (!_aiGenerator) { _aiGenerator = new OpenAIGenerator(apiKey); } return _aiGenerator; }

这样确保全局唯一，也便于在测试中重置状态。

3. 类型安全是底线

TypeScript 是这类模式的最佳搭档。接口声明 + 显式类型标注，能在编译期捕获绝大多数错误。

避免使用any或模糊的联合类型。宁可在初期多花几分钟定义清晰结构，也不要留下隐患。

4. 配置集中化，别散落各处

所有依赖注册逻辑应集中在少数几个文件中，比如container.ts或services/index.ts。这样新人接手时一眼就能看出“系统有哪些可插拔部件”。

// container.ts export function initServices(env: 'dev' | 'test' | 'prod') { return { aiGenerator: env === 'prod' ? new OpenAIGenerator() : new MockAIGenerator(), storage: env === 'prod' ? new LocalStorageAdapter() : new MemoryStorage(), sync: createSyncAdapter(env), }; }

清晰、可读、易维护。

5. 不为小项目“加戏”

如果你只是做个静态页面或小型工具，完全没有必要搞一套完整的 DI 机制。手动传递依赖足够了。只有当模块增多、环境变复杂时，才考虑系统性地引入这种模式。

记住：工具服务于需求，而不是反过来。

结语：可测试性不是附加项，而是设计结果

Excalidraw 的案例告诉我们，良好的可测试性从来不是靠后期补测试用例堆出来的，而是从架构设计之初就埋下的种子。

通过简单的依赖注入模式，它做到了：

• 核心逻辑与外部服务彻底分离；
• 单元测试高效且全覆盖；
• 多后端支持无需重构；
• 新人贡献门槛显著降低。

更重要的是，这种设计让代码变得更“诚实”：每一个依赖都被显式声明，每一个行为都可被验证。没有隐藏的副作用，也没有神秘的全局变量。

对于正在构建 AI 增强型、协作式前端应用的团队来说，不妨从一个小模块开始尝试这种模式。你会发现，一旦习惯了“把依赖交出去”，反而获得了更大的控制力。

毕竟，真正的灵活性，来自于松耦合；而松耦合的背后，是对边界的尊重与清晰的认知。