为什么这样设计 Tegg

下面是我对 tegg 为什么设计成现在这种架构的系统性分析，结合 tegg 仓库的结构来回答“动机-分层-机制-取舍”四个维度，帮助你从“为什么这样设计”的角度理解它。

为什么这样设计

一、目标与约束（Why）

• 核心目标
  • 面向复杂业务的“可组合能力”：将控制器、AOP、DAL、事件总线、调度等能力模块化、按需装配，避免“一个包做所有事”的内聚膨胀。
  • 与 Egg.js 生态的“解耦集成”：核心能力要独立于 Web/框架，但又能通过插件自然接入 Egg 的生命周期、配置和中间件体系。
  • 强类型与装饰器的开发体验：以 TypeScript + 装饰器为入口，提升领域建模的表达力，把设计“显式化”“可扫描化”。
  • 生命周期与上下文的正确性：异步调用链下的上下文传递与隔离，用于解决“异步堆栈里传参散落”的顽疾。
  • 单测与演化友好：以 monorepo 管理多包，使能力可以独立演进、单独发布与回滚，降低全局耦合风险。
• 外部约束
  • Node.js 平台语义（模块系统、异步模型）与 Egg 插件机制。
  • 工程化约束（多包发布、类型共享、构建一致性）。
  • 对既有项目渐进迁移的现实需求（CJS 到 ESM、全局上下文到 ALS）。

二、分层与包的职责（How it’s structured）

• 核心（Core）层：抽象出“运行时/元数据/装载器”三件套
  • 元数据：装饰器标注 → 可被扫描/序列化的元数据
  • 装载器：扫描工程、解析元数据、构建原型/装配单元（LoadUnit/Prototype）
  • 运行时容器：依赖注入、实例生命周期、上下文、作用域等
  • 类型与跨包契约：抽离公共类型，降低编译耦合
  • 能力入口/外观（Facade）：聚合核心能力（为上层提供简化入口）
• 能力（Decorator/Runtime）层：将横切/领域能力按“装饰器 + 运行时”解耦
  • 例如 AOP、DAL、ORM、事件总线、调度等均以“装饰器声明 + 对应运行时”组合出现
• 集成（Plugin）层：把核心能力与 Egg 的应用框架做“边界清晰”的桥接
  • HTTP/Controller 插件：把控制器声明/路由/参数校验等与核心容器打通
  • 与 Egg 的集成外壳（入口/初始化/配置），将 tegg 功能以插件方式启用
  • 其它插件（orm/schedule/ajv 等）将具体能力接入 Egg
• 运行形态（Standalone）层：除了在 Egg 中运行，也支持独立运行模式

这套分层遵循“能力内聚、耦合外移”的原则：核心保持与框架无关，插件负责落地集成，增强了运行时形态的可移植性与渐进引入能力。

三、关键机制与设计取舍（How it works）

• Decorator → Metadata → Loader → Runtime 的流水线
  • 为什么要“先装饰器再元数据”：装饰器让“意图”显式化、可静态扫描；元数据是稳定的中间层，屏蔽语言/框架差异。
  • 为什么要“装载器”：将分散在项目各处的声明统一装配为“原型/LoadUnit”，把“扫描/解析/组装”的复杂度从业务代码挪走。
  • 为什么要“容器/运行时”：解决依赖注入、生命周期、作用域、实例化策略、上下文传播等通用问题。
• 上下文管理采用 AsyncLocalStorage（演进点）
  • 解决异步调用链中的上下文丢失问题，替代手写传参或全局变量，提升一致性与可靠性。
  • 与 Egg 的请求生命周期天然契合，插件层可以围绕请求/任务创建异步上下文作用域。
• ESM only 与类型抽离（工程化演进）
  • ESM only：与现代 Node/工具链对齐，简化双模块形态带来的复杂性与坑点。
  • 类型抽离到 types：将跨包契约集中管理，降低“隐式类型耦合”，便于重构与发布。
• 与 Egg 的解耦集成
  • 为什么把“HTTP 控制器能力”做成插件而不是放在核心：保持核心对框架无感，支持多运行形态；同时让“控制器如何映射到 Egg 的路由/中间件”由插件层决定，避免强耦合。
• Monorepo 的组织理由
  • 每个能力独立发版、独立回滚；变更影响范围可控；同时共享构建/规范工具链，降低总体维护成本。

四、相对其它方案的取舍（Why not X）

• 不做“单一大包（one big package）”
  • 优点：降低初期心智负担；缺点：后期耦合过高，发布与回滚风险极大，难以扩展新能力或裁剪。
  • tegg 选择“多包/可插拔”，以长期演进/大型团队协同为优先。
• 不把 HTTP/框架语义塞进核心
  • 核心一旦耦合框架语义，将限制运行形态与扩展；插件可以自由演化适配不同的框架/协议（HTTP、RPC、消息）。
• 不继续使用全局变量/手写传参做上下文
  • 在 Node 异步场景下不可靠、不可维护；AsyncLocalStorage 是更符合异步模型的“正交能力”。
• 不维持双模块（CJS+ESM）长期并存
  • 工程复杂度高、边界 case 多；ESM only 让生态与工具链更清晰一致。

五、这个架构带来的收益与成本

• 收益
  • 解耦：核心可独立复用，插件可平行演进。
  • 可测试：每个能力包可单测/集成测隔离执行。
  • 可演化：装饰器/元数据/容器作为“稳定三件套”，外部能力以“模块化”扩展。
  • 类型安全：跨包契约集中在 types，重构风险更可控。
• 成本
  • 学习曲线：理解装饰器→元数据→装载器→运行时流水线需要一定门槛。
  • 工程复杂度：多包构建/发布/版本管理需要规范与工具链保障。
  • 性能权衡：启动期的扫描/装载有开销，需要通过缓存/按需加载来权衡。

架构总览

装饰器→元数据→装载器→运行时→插件

下图展示 tegg 的关键流转与边界：装饰器将“意图”转化为元数据；装载器扫描并构建 LoadUnit/Prototype；运行时负责 DI/生命周期/上下文（基于 AsyncLocalStorage）；插件层与 Egg 集成。

关键数据结构（示例清单）：

• Metadata：ClassMetadata、PropertyMetadata、ParamMetadata
• Loader：LoadUnit、EggPrototype/EggObject、Qualifier/Scope
• Runtime：Context（ALS）、Container、LifecycleHook
• Plugin：HTTPController、路由注册/参数解析

数据结构索引

以下索引帮助你从“架构图/生命周期图”跳到具体源码

• Controller 元数据：plugin/controller/lib/ControllerMetadata.ts

• 方法元数据接口：core/types/MethodMeta.ts

• 原型接口：core/types/EggPrototype.ts

• 加载单元：core/types/LoadUnit.ts

• 对象包装：core/types/EggObject.ts

• 请求上下文：core/types/EggContext.ts

• 生命周期钩子：core/types/LifecycleHook.ts

• 控制器注册工厂：plugin/controller/lib/ControllerRegisterFactory.ts

• HTTP 方法注册器：plugin/controller/lib/HTTPMethodRegister.ts

• 容器对象工厂：core/lib/EggContainerFactory.ts（或所在实现位置）