davidyichengwei 架构设计
使用场景：
workflow-system-designskill 在讨论 spec.md 4.1 方案概览 时加载本 skill。
第一性原理
架构设计的本质：在约束条件下，选择最优的 trade-off 来满足业务目标。
设计前：回顾 spec.md 前三节
在提出架构方案前，确保已理解：
| spec.md 章节 | 要回答的问题 |
|---|---|
| 1. 背景 | 要解决什么问题？现状是怎样的？ |
| 2. 目标 & 非目标 | 成功的标准是什么？什么不做？ |
| 3.1 功能性需求 | 系统需要具备哪些能力？ |
| 3.2 非功能性需求 | 性能、兼容性、可维护性约束？ |
如果非功能性需求可以量化，尽量量化（如 p99 延迟 < 100ms），但不强制要求所有场景都能量化。
模块划分
好的划分 = 减少协调成本 + 包含变化。
划分原则
| 原则 | 说明 | 检查点 |
|---|---|---|
| 按功能域划分 | 围绕业务能力而非技术层 | 相关的代码是否在一起？ |
| 高内聚 | 一起变化的代码放一起 | 修改一个功能要改几个模块？ |
| 低耦合 | 模块间依赖最小化 | 模块能否独立理解和测试？ |
| 明确所有权 | 每个模块有明确的数据和不变量 | 谁负责维护这块数据的一致性？ |
边界定义
// ✅ 明确的模块边界
namespace compaction {
// 公开接口
class CompactionScheduler { ... };
// 内部实现（不暴露）
namespace internal {
class CompactionTask { ... };
}
}
依赖管理
依赖方向
层次结构（从高到低）：
- 应用层 - 业务逻辑、用例编排
- 领域层 - 核心抽象、接口定义
- 基础设施层 - 具体实现（RocksDB、网络等）
依赖原则：高层依赖低层，依赖抽象接口而非具体实现
依赖规则
| 规则 | 说明 |
|---|---|
| 单向依赖 | 只能向下依赖，禁止向上依赖 |
| 禁止循环 | A→B→C→A 必须打破 |
| 依赖抽象 | 依赖接口而非具体实现 |
数据架构
数据决策决定正确性和运维复杂度。
| 决策点 | 需要明确 |
|---|---|
| 数据所有权 | 哪个模块是这份数据的 source of truth？ |
| 一致性模型 | 强一致 vs 最终一致？ |
| Schema 演进 | 向前/向后兼容？回滚方案？ |
接口设计
架构层关注接口原则，详细设计参见
bp-component-design的 4.2.2 节。
| 原则 | 说明 |
|---|---|
| 最小化 | 只暴露必要的接口 |
| 不泄露内部 | 使用专用 DTO |
| 版本兼容 | 接口变更需考虑向后兼容 |
与其他 Skill 协同
| 场景 | 加载 Skill |
|---|---|
| 涉及网络通信、多节点、一致性、故障恢复 | bp-distributed-systems |
| 涉及类/接口详细设计 | bp-component-design（4.2 节使用） |
4.1 方案概览 Checklist
在 spec.md 4.1 节，确认以下内容已讨论：
- 整体思路：用 1-2 句话描述方案核心
- 模块划分：涉及哪些模块？边界在哪？
- 依赖方向：模块间的依赖关系
- 数据流：数据如何流转？
- 关键 trade-off：为什么这样设计？牺牲了什么？
反模式
| 反模式 | 改进 |
|---|---|
| 循环依赖 (A→B→C→A) | 引入接口打破循环 |
| 边界模糊（多模块修改同一份数据） | 明确数据所有权 |
| 过度抽象 | 简单优先，按需抽象 |
| Big Ball of Mud | 逐步引入边界 |