bp-distributed-systems

Files (1)

• SKILL.md

SKILL.md (first lines)

# 分布式系统设计原则

> **触发条件**：需求涉及以下任一场景时应加载此 skill：
> - 网络通信（RPC、HTTP、消息队列）
> - 多节点协调（集群、主从、分片）
> - 数据一致性（事务、复制、同步）
> - 故障恢复（重试、failover、降级）

---

## 13 条 Best Practices

每条对应一个常见 Fallacy（错误假设）。

| # | Fallacy | 现实 | Best Practice | 关键设计要点 |
|---|---------|------|---------------|-------------|
| **BP-1** | 网络可靠 | 会丢包、延迟、断连 | 假设网络会失败 | 超时、重试(指数退避)、幂等、断路器 |
| **BP-2** | 延迟为零 | 受距离/拥塞/处理影响 | 延迟是核心考量 | 异步优于同步、批量、本地缓存、预取 |
| **BP-3** | 带宽无限 | 高峰期是稀缺资源 | 最小化传输量 | 压缩、只传必要字段、分页/流式、优先级队列 |
| **BP-4** | 网络安全 | 可被窃听/篡改/攻击 | 零信任架构 | TLS加密、认证授权、输入验证、审计日志 |
| **BP-5** | 拓扑不变 | 节点会增减/故障/迁移 | 适应动态拓扑 | 服务发现、负载均衡、健康检查、优雅上下线 |
| **BP-6** | 单管理员 | 跨多个管理边界 | 多管理域协调 | 接口契约、版本兼容、跨团队沟通、统一监控 |
| **BP-7** | 传输免费 | 消耗带宽/CPU/电力 | 优化传输路径 | 数据本地性、减少跨AZ调用、批量合并、增量同步 |
| **BP-8** | 网络同构 | 不同厂商/配置/性能 | 兼容异构环境 | 不依赖特定网络特性、协议协商、适配不同MTU |
| **BP-9** | 系统单体 | 多个独立组件构成 | 显式管理交互 | 组件边界、清晰接口、依赖管理、部分失败 |
| **BP-10** | 完全可观测 | 状态难以完整获取 | 主动设计可观测性 | 结构化日志、分布式追踪、指标埋点、健康检查 |
| **BP-11** | 永远在线 | 维护/故障/网络都会停机 | 高可用架构 | 冗余部署、自动failover、优雅降级、灾备 |
| **BP-12** | 单一根因 | 多个关联因素 | 多维度故障分析 | 关联分析、保留上下文、时间线重建、故障注入 |
| **BP-13** | 故障罕见 | 规模化后是常态 | 为故障而设计 | 故障隔离(blast radius)、自动恢复、混沌工程 |

---

## SDLC 各阶段 Checklist

### 需求澄清

| BP | 问题 |
|----|------|
| 1 | 网络调用失败时的预期行为？重试策略？ |
| 2 | 可接受的延迟上限？是否需要异步？ |
| 4 | 安全要求？认证/授权/加密？ |
| 10 | 需要哪些监控指标？告警阈值？ |
| 11 | SLA 要求？故障时的降级策略？ |

### 系统设计

| BP | 检查项 |
|----|--------|
| 1 | 所有 RPC 都有超时和重试？ |
| 2 | 热路径是否考虑了缓存/异步？ |
| 5 | 节点增减时系统如何适应？ |
| 9 | 组件边界和接口是否清晰？ |
| 11 | 单点故障有冗余？ |

### 编码

| BP | 检查项 |
|----|--------|
| 1 | 网络调用有 timeout？重试幂等安全？ |
| 4 | 敏感数据加密？ |
| 10 | 关键路径有日志/metrics？ |
| 12 | 错误日志包含足够上下文？ |

### 测试

| BP | 测试场景 |
|----|----------|
| 1 | 网络超时/断连 |
| 2 | 高延迟（注入延迟） |
| 5 | 节点上下线 |
| 11 | 依赖服务不可用 |
| 13 | 故障恢复 |

### Code Review

| BP | 关注点 |
|----|--------|
| 1 | 网络调用有防护？ |
| 3 | 大数据传输分批？ |
| 4 | 有安全漏洞？ |
| 10 | 可观测性充分？ |

### 故障排查

| BP | 排查方向 |
|----|----------|
| 1 | 网络抖动/超时？ |
| 2 | 延迟突增？ |
| 5 | 拓扑变更（节点上下线）？ |
| 12 | 多个关联因素？ |
| 13 | 已知的常见故障模式？ |

From davidYichengWei/agentic-engineering-framework, MIT.

More from davidYichengWei/agentic-engineering-framework