技术决策记录(ADR)
状态:持续更新 —— 本页汇总 ng-mfe v0.2.0 已确认的 11 项核心技术决策,每项独立成篇,记录问题、候选方案、决策与后果。
这是什么
本目录是 ng-mfe 的架构决策记录(Architecture Decision Records)。每个决策回答一个问题:在当时的约束下,为什么这样选、放弃了什么、接受了哪些已知限制。决策不是永恒真理——约束变化时会被重新评估,演进方向见路线图。
阅读一篇 ADR 的正确姿势:先看「问题」与「候选方案」,理解当时的取舍空间;再看「代价与权衡」与「后果」,其中包含如实记录的已知限制与待改进项。
决策总览
| 编号 | 决策 | 一句话理由 | 状态 |
|---|---|---|---|
| 01 | 门户采用 Angular 21 + Zoneless | 正式 API 的 Zoneless 变更检测与 Signal 模型契合微前端的可预测卸载 | 已实施(v0.2.0) |
| 02 | Signal 与 MFE 服务桥接,core 零框架依赖 | 框架状态原语与运行时服务解耦,三框架同构订阅 | 已实施(v0.2.0) |
| 03 | 原生 ES Module 加载子应用 | <script type="module"> 即标准契约,子应用保持普通 Vite 应用 | 已实施(v0.2.0) |
| 04 | 不采用 Module Federation | 子应用自主性与构建器中立优先于构建期依赖共享 | 已实施(v0.2.0) |
| 05 | 沙箱双模式:Proxy 优先、Snapshot 降级 | 运行环境探测决定,兼容不支持 Proxy 的环境 | 已实施(v0.2.0) |
| 06 | 通信三件套:EventBus + RPC + SharedState | 广播、请求响应、共享数据三种语义各自独立 | 已实施(v0.2.0) |
| 07 | 三级缓存 + Read/Write-Through + 单飞 | 内存/会话/持久三级各司其职,并发去重防击穿 | 已实施(v0.2.0) |
| 08 | 统一 HTTP 中间件管道 | 六步回路 + 优先级排序,认证/缓存/重试可组合 | 已实施(v0.2.0) |
| 09 | 刷新令牌单飞 + 登出级联 | 并发刷新共享同一 Promise,登出一次性清理全局态 | 部分实施(刷新重放规划中) |
| 10 | 地图工厂 + 图层注册表 | MapLibre 动态加载为可选依赖,图层懒加载带 ACL | 已实施(v0.2.0) |
| 11 | 跨应用组件注册表 | 生产者注册、消费者加载,避免框架间直接依赖 | 已实施(v0.2.0) |
阅读指引
- 想理解整体设计思想:从设计原则入手,再按编号顺序阅读 01 → 04(框架与加载四篇互相关联)。
- 关心隔离与通信:05 → 06 两篇覆盖沙箱与三通道通信,配合沙箱架构与通信架构。
- 关心数据链路:07 → 08 → 09 三篇覆盖缓存、HTTP 管道与认证,配合缓存与缓冲。
- 做 GIS 或跨应用复用:10、11 两篇,配合地图架构与注册表架构。
- 评估是否采用本框架:先读什么是微前端与总体架构,再对照本目录的「代价与权衡」判断约束是否匹配。
决策状态说明
| 状态 | 含义 |
|---|---|
| 已实施(v0.2.0) | 决策已在 v0.2.0 全部落地,行为与文档一致 |
| 部分实施 | 主体已落地,存在明确记录的待改进项(如 09 的刷新重放) |
每篇 ADR 的「后果」一节如实列出已知限制;限制被修复或决策被修订时,对应页面随之更新,不静默改写历史结论。若某项决策被整体取代,会在原页面顶部标注替代篇目。
横切约束
所有决策共享以下硬约束,单篇不再重复论证:
- 体积预算(来自
.size-limit.json,CI 强制):core ≤15KB、sandbox ≤12KB、event-bus ≤5KB、shared-state ≤8KB、util ≤6KB、adapters/angular ≤10KB、vue ≤8KB、react ≤8KB、devtools ≤5KB; - 构建底座:bun + Nx + Vite 8 工作区,5 个发布包(core/services/adapters/ui/testing);
- Zoneless 守卫:CI 独立 zoneless-guard job,详见01;
- 子应用形态:普通 Vite 应用,无共享运行时契约,详见03。