architecture-paradigm-functional-core

函数式核心、命令式外壳范式

适用场景

• 将纯业务逻辑与副作用分离
• 通过不可变领域模型提高可测试性

不适用场景

• 不可变性开销会造成影响的性能关键热路径
• 没有采用函数式模式计划的纯命令式代码库

何时采用此范式

• 当业务逻辑与 I/O 操作（例如数据库调用、HTTP 请求）纠缠在一起，导致测试脆弱且缓慢时。
• 当大量开发时间花在重写适配器或应对框架频繁变动上时。
• 当你需要一套快速、确定性的单元测试来处理纯数据，并辅以精简的集成测试层时。

采用步骤

1. 盘点副作用：绘制系统中所有副作用的图谱，例如数据库写入、外部 API 调用、UI 事件和文件系统访问。明确将这些职责分配给“外壳”。
2. 为核心逻辑建模：将业务规则和策略表示为纯函数。这些函数应以领域数据为输入，并返回决策或命令作为输出，避免共享可变状态。
3. 设计命令模式：定义一组少量且明确的命令对象，供核心返回并由外壳解释（例如 PersistOrder、PublishEvent、NotifyUser）。
4. 渐进式重构：从变动频繁或关键的模块入手。通过适配器封装旧版命令式代码，同时逐步将纯计算提取到函数式核心中。
5. 强化边界：通过代码审查和自动化架构测试，确保严格分离。外壳只应负责编排、排序和重试，而核心绝不能直接调用框架或 I/O 库。

关键交付物

• 一份架构决策记录（ADR），说明选择此模式的原因、受影响的模块以及迁移范围。
• 一套针对核心的单元测试，覆盖率高于 90% 且具有确定性。在适用情况下，使用基于属性或基于测试固件的测试来覆盖多种输入。
• 一套针对外壳的契约测试和集成测试，用于验证命令解释、重试逻辑和遥测是否正确。
• 一组用于展示架构变更价值的发布指标（例如部署前置时间、外壳层的事件发生率）。

风险与缓解措施

• 核心与外壳之间的逻辑漂移：
  • 缓解措施：业务逻辑意外重复或放置在外壳中很常见。在代码审查期间执行“核心负责所有决策”检查清单，避免此问题。
• 与框架不匹配：
  • 缓解措施：命令式外壳可能仍需与框架特定的生命周期钩子交互。在着手大规模重写前，先构建小型概念验证适配器，以验证集成策略。
• 团队不熟悉此模式：
  • 缓解措施：通过结对编程和内部“午餐学习”分享会引入此模式。在试点阶段记录发现的常见反模式，为后续开发提供指导。

具体组件

此范式的实现通常包含的工具和抽象的术语表。 它们不是依赖项，也不是 tools: frontmatter。

• boundary-validator：守护传入纯函数核心的输入，让核心保持全定义
• core-test-generator：针对确定性核心生成基于属性的测试
• shell-adapter-generator：搭建命令式外壳的脚手架，将核心连接到 I/O

退出标准

• 在开始任何重构之前，已有一份明确的副作用清单，将每项 I/O 操作映射到 Shell 层。
• 核心单元测试无需 I/O 模拟（不调用数据库、HTTP 或文件系统），且确定性覆盖率达到

  90%。

• 自动化架构测试（例如导入分析或命名空间规则）确认核心不包含任何来自 I/O 或框架库的导入。
• 在迁移之前，已对推出指标（部署提前期、Shell 层的事件发生率）建立基线，并在迁移后进行对比，以证明该模式的价值。