bp-component-design

name: bp-component-design description: 提供组件级设计原则，包括类/模块设计、接口设计、数据模型、并发模型、错误处理。在系统设计阶段讨论组件详细设计时使用，或在 code review 中评估组件质量时使用。

组件设计

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

第一性原理

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

4.2.1 核心类/模块设计

SOLID 原则

设计原则

常用设计模式

Checklist

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

4.2.2 接口设计

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

设计原则

接口定义要素

// 示例：接口定义应包含
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 演进

Checklist

• Schema 字段是否完整定义？
• 索引是否满足查询需求？
• 是否考虑了 Schema 演进？
• 迁移/回滚方案是否明确？

4.2.4 并发模型

何时需要：涉及多线程、异步操作、共享状态时。

设计要素

常见模式

Checklist

• 线程模型是否清晰？
• 共享状态是否明确，保护机制是否合理？
• 是否有死锁风险？
• 锁粒度是否合适（不过粗也不过细）？

4.2.5 错误处理

何时需要：涉及外部依赖、I/O 操作、可能失败的场景时。

设计要素

错误分类

重试策略

// 指数退避 + 抖动
int delay_ms = min(base_delay * (1 << retry_count), max_delay);
delay_ms += random(0, delay_ms * 0.1);  // 10% jitter

Checklist

• 所有可能的失败模式是否列出？
• 错误表示方式是否统一？
• 可重试 vs 不可重试是否区分？
• 失败后的清理/恢复逻辑是否考虑？

反模式

与其他 Skill 协同