architecture-design

架构设计

适用场景

• 启动需要系统设计的新产品或重大功能
• 在单体、模块化单体、微服务或事件驱动模式之间做出选择
• 为新项目选择数据库（SQL、NoSQL 或专用数据库）
• 分析依赖项中的循环引用、耦合问题或过时的软件包
• 为文档或评审创建架构图（Mermaid、PlantUML、ASCII）
• 为技术决策编写架构决策记录（ADR）
• 评估可扩展性瓶颈或规划容量

所需上下文

从 startup-context 获取：产品描述、技术栈、当前状态（原型／测试版／扩展中）、团队规模、预期规模（用户数、每秒请求数、数据量）。如果缺少信息，请询问：

• 这个系统需要实现什么功能？（核心用例）
• 目标规模是多少？（用户数、每秒请求数、数据量）
• 团队规模多大，后端经验水平如何？
• 是否有硬性约束？（合规性、延迟、预算、现有基础设施）

工作流

1. 收集需求 — 确定功能需求（用例）、非功能需求（延迟、吞吐量、可用性、一致性）和约束（预算、团队规模、合规性）。
2. 评估架构 — 分析现有项目结构，识别当前模式（MVC、分层、六边形、微服务指标）、代码组织问题（上帝类、关注点混杂）和分层违规。
3. 分析依赖项 — 检查 npm、Python、Go 或 Rust 项目的依赖树，找出循环依赖、耦合度和过时的软件包。
4. 选择架构模式 — 使用下方的决策流程，根据团队规模、部署需求和数据边界匹配合适的模式。对于大多数早期创业公司，建议采用模块化单体。
5. 选择数据库 — 使用下方的选择流程，根据数据特征、规模要求和一致性需求匹配合适的数据库技术。
6. 设计数据模型 — 使用 Mermaid 绘制 ER 图。定义实体归属：哪个模块／服务负责写入，其他模块／服务通过 API 读取。
7. 定义 API 契约 — 指定关键端点的方法、路径、请求／响应结构和错误代码。从第一天起就进行版本控制。
8. 生成架构图 — 使用 Mermaid C4 图或流程图，展示组件、数据存储、外部服务和通信模式。
9. 编写 ADR — 使用下方的 ADR 格式记录关键决策。
10. 识别风险 — 指出单点故障、数据一致性风险和扩展瓶颈，并提供缓解措施。

输出格式

交付一份结构化的架构文档，包含以下部分：

• 需求摘要 — 功能需求、非功能需求和约束
• 架构评估 — 识别出的模式及其置信度、问题和建议
• 系统图 — Mermaid C4 图或流程图（组件、分层或部署视图）
• 领域模型 — 包含实体归属的 Mermaid ER 图
• 模块边界 — 表格：模块、职责、数据所有权、公开的 API
• API 契约 — 关键端点的方法、路径、请求／响应结构
• ADR — 关键决策的架构决策记录
• 依赖分析 — 依赖总数、耦合度、循环依赖、过时的软件包
• 风险与缓解措施 — 表格：风险、影响、可能性、缓解措施

框架与最佳实践

架构模式选择

团队规模	推荐起点
1-3 名开发者	模块化单体
4-10 名开发者	模块化单体或面向服务
10 名以上开发者	考虑微服务

需求	推荐模式
快速开发 MVP	模块化单体
团队独立部署	微服务
复杂领域逻辑	领域驱动设计
读写比例差异大	CQRS
需要审计轨迹	事件溯源
第三方集成	六边形架构 / 端口与适配器

**早期初创公司的默认选择：**采用模块化单体，并明确模块边界，以便日后拆分。微服务会增加运维开销，拖累小团队。

单体与微服务检查清单

**选择单体的情况：**团队规模较小（<10），领域边界不明确，优先考虑快速迭代，并且可以接受共享数据库。

**选择微服务的情况：**团队能够端到端地负责服务，独立部署至关重要，各组件的扩展需求不同，且领域边界明确。

**混合方案：**从单体开始。仅在模块的扩展需求显著不同、团队需要独立部署，或技术限制要求分离时，才拆分出服务。

数据库选择

有关系或 ACID 需求的结构化数据适合使用 SQL。架构灵活或不断演进的数据，以及面向文档的数据，适合使用 NoSQL。快速参考：PostgreSQL（大多数应用的默认选择）、MongoDB（文档存储）、Redis（缓存/会话）、DynamoDB（无服务器自动扩展）、TimescaleDB（时间序列）、CockroachDB/Spanner（全球分布）。

ADR 格式

使用以下五个字段：状态（提议/已接受/已弃用/已取代）、背景（决策缘由）、决策（选择了什么及原因）、后果（权衡和剩余风险）、考虑过的替代方案（评估了哪些其他方案及其未被采用的原因）。

关键设计原则

• 每个实体都有明确的所有者（由一个模块写入，其他模块通过 API 读取）
• 如果采用多服务架构或未来可能拆分，请使用 UUID 作为主键
• 从第一天起就对 API 进行版本管理（/v1/resource）；所有列表端点都要分页（优先使用基于游标的分页）
• 统一错误格式：{ "error": { "code": "...", "message": "..." } }
• 设计写入操作时应确保幂等性（幂等键）
• 需要即时确认的查询使用同步调用（HTTP/gRPC）；通知、分析和跨服务数据同步使用异步事件
• 避免分布式事务——使用 Saga 或最终一致性

相关技能

• tech-stack-eval — 选择架构的具体技术时与此技能串联
• security-review — 实现前串联此技能，检查架构的威胁向量
• code-review — 实现后串联此技能，确认代码符合架构意图

示例

提示词：“我正在构建一个 SaaS 项目管理工具，有 3 名工程师。应该如何设计架构？”

良好输出片段：

Given your team of 3 and early stage, I recommend a modular monolith.
Domain modules:

1. Auth Module — user accounts, roles, sessions
2. Projects Module — workspaces, projects, permissions
3. Tasks Module — tasks, assignments, comments, activity log
4. Notifications Module — email digests, in-app notifications

Each module gets its own DB schema (auth.*, projects.*) and communicates
through internal function calls with typed interfaces — not HTTP. This
gives you service-like boundaries without deployment complexity.

Architecture Assessment:
  Detected pattern: Layered Architecture (confidence: 85%)
  ✓ controllers/  - Presentation layer
  ✓ services/     - Business logic layer
  ✓ repositories/ - Data access layer

提示词：“实时协作应该使用 WebSockets 还是 SSE？”

良好输出片段：

## ADR-001: Use WebSockets for Real-Time Collaboration
- Status: Proposed
- Context: Document editor needs sub-200ms latency for cursor positions
  and concurrent edits across 2-50 users per document.
- Decision: WebSockets via Socket.io with Redis pub/sub for horizontal
  scaling. SSE only supports server-to-client; we need bidirectional
  communication for operational transforms.
- Consequences: Adds WebSocket infrastructure (sticky sessions or Redis
  adapter), ~2KB memory per connection. Team needs OT/CRDT knowledge.
- Alternatives: SSE + POST (simpler but higher edit latency),
  Firebase Realtime DB (vendor lock-in, cost at scale).