bp-component-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 组件设计

> **使用场景**：`workflow-system-design` skill 在讨论 spec.md **4.2 组件设计** 时加载本 skill。

## 第一性原理

> **组件设计的本质**：把架构方案转化为可实现的代码结构，定义清晰的职责边界和交互契约。

---

## 4.2.1 核心类/模块设计

### SOLID 原则

| 原则 | 含义 | 检查点 |
|------|------|--------|
| **S**ingle Responsibility | 类只做一件事 | 这个类能用一句话描述吗？ |
| **O**pen/Closed | 对扩展开放，对修改关闭 | 新增功能是否需要改现有代码？ |
| **L**iskov Substitution | 子类可替换父类 | 子类是否违反父类契约？ |
| **I**nterface Segregation | 接口精简专一 | 调用方是否被迫依赖不需要的方法？ |
| **D**ependency Inversion | 依赖抽象而非具体 | 高层模块是否直接依赖低层实现？ |

### 设计原则

| 原则 | 说明 |
|------|------|
| **组合优于继承** | 继承紧耦合，组合松耦合易替换 |
| **面向接口编程** | 依赖抽象接口，而非具体实现 |
| **最小知识原则** | 避免链式调用暴露内部结构 |

### 常用设计模式

| 类型 | 模式 | 适用场景 |
|------|------|----------|
| 创建型 | Factory | 封装对象创建逻辑 |
| 创建型 | Builder | 分步构建复杂对象 |
| 结构型 | Adapter | 接口转换 |
| 结构型 | Decorator | 动态添加职责 |
| 行为型 | Strategy | 可替换算法 |
| 行为型 | Template Method | 定义算法骨架，子类实现细节 |
| 行为型 | Iterator | 数据流处理、管道模式 |

### Checklist

- [ ] 类职责是否单一清晰？
- [ ] 继承层次是否合理（不超过 2-3 层）？
- [ ] 依赖是否指向抽象而非具体实现？
- [ ] 模块边界是否明确？

---

## 4.2.2 接口设计

> **接口设计关注对外暴露的 public API**，内部接口在 4.2.1 中定义。

### 设计原则

| 原则 | 说明 |
|------|------|
| **最小化** | 只暴露必要的接口，隐藏实现细节 |
| **一致性** | 命名、参数顺序、错误处理风格统一 |
| **向后兼容** | 接口变更不破坏现有调用方 |
| **自描述** | 接口签名本身能表达意图 |

### 接口定义要素

```cpp
// 示例：接口定义应包含
class StorageEngine {
public:
    // 1. 方法签名：清晰的命名和参数
    // 2. 参数约束：哪些可为空？取值范围？
    // 3. 返回值：成功/失败如何表示？
    // 4. 错误码：可能返回哪些错误？
    // 5. 线程安全：是否可并发调用？
    
    /**
     * @brief 写入 KV 对
     * @param key 键，不能为空
     * @param value 值
     * @return Status::OK 成功
     *         Status::KeyTooLong key 超过 64KB
     *         Status::IOError 写入失败
     * @thread_safety 线程安全
     */
    virtual Status Put(const Slice& key, const Slice& value) = 0;
};
```

### 版本兼容策略

| 变更类型 | 兼容性 | 处理方式 |
|----------|--------|----------|
| 新增方法 | 向后兼容 | 直接添加 |
| 新增可选参数 | 向后兼容 | 提供默认值 |
| 删除方法 | **不兼容** | 先废弃，下个大版本删除 |
| 修改参数类型 | **不兼容** | 新增方法，废弃旧方法 |

### Checklist

- [ ] 接口是否最小化（不暴露不必要的方法）？
- [ ] 参数和返回值是否清晰定义？
- [ ] 错误码是否完整列出？
- [ ] 线程安全性是否说明？
- [ ] 是否考虑了向后兼容？

---

## 4.2.3 数据模型

> **何时需要**：涉及数据存储、Schema 变更、新增数据结构时。

### 设计要素

| 要素 | 需要明确 |
|------|----------|
| **Schema** | 字段定义、类型、约束 |
| **索引** | 查询模式决定索引设计 |
| **编码格式** | 序列化方式（protobuf/flatbuffers/自定义） |

From davidYichengWei/agentic-engineering-framework, MIT.

More from davidYichengWei/agentic-engineering-framework