architecture-patterns

架构模式

概述

架构服务于功能。每项架构决策都应追溯到某项功能需求。

核心原则： 根据功能设计架构，而不是为了架构设计功能。

在 v10 中，此技能仅供参考。它用于梳理决策和权衡，不凌驾于明确的用户需求、仓库规范或已批准的计划／设计文档之上。

重点领域（参考模式）

• RESTful API 设计，包含恰当的版本管理和错误处理
• 服务边界定义和服务间通信
• 数据库架构设计（规范化、索引、分片）
• 缓存策略和性能优化
• 基本安全模式（身份验证、速率限制）

铁律

NO ARCHITECTURE DESIGN BEFORE FUNCTIONALITY FLOWS ARE MAPPED

如果你尚未记录用户流程、管理员流程和系统流程，就不能设计架构。

需求分流

首先，确定需要哪类架构工作：

请求类型	路由至
“设计 API 端点”	API 设计部分
“规划系统架构”	完整架构设计
“设计数据模型”	数据模型部分
“规划集成”	集成模式部分
“做出决策”	决策框架部分

通用问题（先回答）

设计前务必回答：

1. 我们要构建什么功能？ - 用户故事，而非技术功能
2. 参与者有哪些？ - 用户、管理员、外部系统
3. 用户流程是什么？ - 用户逐步执行的操作
4. 系统流程是什么？ - 内部处理步骤
5. 有哪些集成？ - 外部依赖项
6. 有哪些约束？ - 性能、安全、合规性
7. 需要哪些可观测性？ - 日志、指标、监控、告警

功能优先的设计流程

阶段 1：梳理功能流程

在进行任何架构设计之前：

User Flow (example):
1. User opens upload page
2. User selects file
3. System validates file type/size
4. System uploads to storage
5. System shows success message

Admin Flow (example):
1. Admin opens dashboard
2. Admin views all uploads
3. Admin can delete uploads
4. System logs admin action

System Flow (example):
1. Request received at API
2. Auth middleware validates token
3. Service processes request
4. Database stores data
5. Response returned

阶段 2：映射到架构

每个流程都映射到相应组件：

流程步骤	架构组件
用户打开页面	前端路由 + 组件
用户提交数据	API 端点
系统进行验证	验证服务
系统进行处理	业务逻辑服务
系统存储数据	数据库 + 仓储
系统进行集成	外部客户端／适配器

阶段 3：设计组件

为每个组件定义：

• 用途：支持什么功能
• 输入：接收什么数据
• 输出：返回什么数据
• 依赖项：需要什么
• 错误处理：可能发生什么故障

架构视图

系统上下文（C4 第 1 级）

┌─────────────────────────────────────────────┐
│                 SYSTEM                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   Web   │  │   API   │  │Database │     │
│  │   App   │──│ Service │──│         │     │
│  └─────────┘  └─────────┘  └─────────┘     │
└─────────────────────────────────────────────┘
       │              │              │
    ┌──┴──┐        ┌──┴──┐        ┌──┴──┐
    │User │        │Admin│        │ Ext │
    └─────┘        └─────┘        └─────┘

容器视图（C4 第 2 级）

• Web 应用：React/Vue/Angular 前端
• API 服务：REST/GraphQL 后端
• 数据库：PostgreSQL/MongoDB 等
• 缓存：Redis/Memcached
• 队列：用于异步处理的 RabbitMQ/SQS

组件视图（C4 第 3 级）

• 控制器：处理 HTTP 请求
• 服务：业务逻辑
• 仓储：数据访问
• 客户端：外部集成
• 模型：数据结构

LSP 驱动的架构分析

使用 LSP 梳理实际代码依赖关系：

架构任务	LSP 工具	输出
梳理组件依赖关系	lspCallHierarchy(outgoing)	各组件使用的内容
查找服务的所有使用方	lspCallHierarchy(incoming)	影响分析
验证接口实现	lspFindReferences	所有实现者
追踪数据流	连续调用 lspCallHierarchy	完整流程图

梳理实际架构：

1. localSearchCode("ServiceName") → find entry points
2. lspCallHierarchy(outgoing) → map dependencies
3. For each dependency: repeat step 2
4. Build dependency graph from results

先使用 LSP，再绘制架构图——通过代码验证假设。

重要： 务必先通过 localSearchCode 获取 lineHint。切勿猜测行号。

API 设计（与功能对齐）

将用户流程映射到端点：

User Flow: Upload file
→ POST /api/files
  Request: { file: binary, metadata: {...} }
  Response: { id: string, url: string }
  Errors: 400 (invalid), 413 (too large), 500 (storage failed)

User Flow: View file
→ GET /api/files/:id
  Response: { id, url, metadata, createdAt }
  Errors: 404 (not found), 403 (not authorized)

Admin Flow: Delete file
→ DELETE /api/files/:id
  Response: { success: true }
  Errors: 404, 403

API 设计检查清单：

• 每个端点都对应一个用户／管理员流程
• 请求架构与流程输入相匹配
• 响应架构与流程输出相匹配
• 错误涵盖所有失败模式
• 已记录身份验证／授权要求

集成模式

将集成需求映射到模式：

需求	模式
不稳定的外部服务	指数退避重试
响应缓慢的外部服务	熔断器 + 超时
需要异步处理	消息队列
需要实时更新	WebSocket/SSE
需要同步数据	事件溯源

对于每项集成：

### [Integration Name]

**Functionality**: What user flow depends on this?
**Pattern**: [Retry/Circuit breaker/Queue/etc]
**Error handling**: What happens when it fails?
**Fallback**: What's the degraded experience?

依赖项分类

选择模式前，先对依赖项进行分类：

类别	示例	测试策略
进程内	纯计算、内存状态	直接测试——合并模块并验证
可由本地替代	数据库（PGLite）、文件系统（内存文件系统）	在测试套件中使用本地替代实现进行测试
远程但自有	自有微服务、内部 API	定义端口（接口），注入传输层。使用内存适配器进行测试
真正的外部依赖	Stripe、Twilio、第三方 API	在边界处模拟。将依赖项作为端口注入

类别决定模式。进程内依赖无需任何处理。真正的外部依赖需要模拟。中间两类需要端口和适配器。

实现顺序——从叶节点向内构建：

Level 0 (no deps):      [Pure utils] [Config]
        ↓
Level 1 (Level 0 only): [Repositories] [External clients]
        ↓
Level 2 (Level 0-1):    [Services]
        ↓
Level 3 (Level 0-2):    [Controllers] [API routes]

0 级组件可立即测试。后续每一级只依赖前一级。此顺序可避免早期阶段的测试过度依赖模拟，并符合规划器的 DAG 约束（阶段只依赖前序阶段，绝不依赖未来阶段）。

可观测性设计

为每个组件定义：

方面	问题
日志记录	记录哪些事件？使用什么级别？采用结构化格式吗？
指标	测量什么？计数器、仪表、直方图？
告警	阈值是什么？通知谁？
追踪	Span 边界？关联 ID？

最低限度的可观测性：

• 在边界处记录请求／响应日志
• 错误率和延迟
• 健康检查端点
• 传播关联 ID

决策框架

对于每项架构决策：

### Decision: [Title]

**Context**: What functionality requirement drives this?

**Options**:
1. [Option A] - [Brief description]
2. [Option B] - [Brief description]
3. [Option C] - [Brief description]

**Trade-offs**:
| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Performance | Good | Better | Best |
| Complexity | Low | Medium | High |
| Cost | Low | Medium | High |

**Decision**: [Option chosen]

**Rationale**: [Why this option best supports functionality]

危险信号——停止并重新设计

如果你发现自己在：

• 映射流程之前设计架构
• 添加功能不明确的组件
• 因为“这是最佳实践”而选择模式
• 为假设的规模过度设计
• 忽略现有架构模式
• 未记录权衡就做出决策

停止。回到功能流程。

保持简单（参考模式）

后端架构方法：

1. 从明确的服务边界开始
2. 采用契约优先的方式设计 API
3. 考虑数据一致性要求
4. 从第一天起就规划水平扩展
5. 保持简单——避免过早优化

架构输出检查清单：

• API 端点定义及请求／响应示例
• 服务架构图（mermaid 或 ASCII）
• 包含关键关系的数据库架构
• 技术建议及简要依据
• 潜在瓶颈和扩展注意事项

始终提供具体示例。注重实际实现，而非理论。

防止合理化

借口	实际情况
“这种模式是行业标准”	它支持这项功能吗？
“我们以后可能会用到”	YAGNI。为当下设计。
“微服务更好”	对这项功能而言是这样吗？请给出理由。
“大家都在用”	这不是权衡分析。
“它更灵活”	不需要的灵活性 = 复杂性。

输出格式

# Architecture Design: [Feature/System Name]

## Functionality Summary
[What this architecture supports - trace to user value]

## Flows Mapped

### User Flows
1. [Flow 1 steps]
2. [Flow 2 steps]

### System Flows
1. [Flow 1 steps]
2. [Flow 2 steps]

## Architecture

### System Context
[Diagram or description of actors and system boundaries]

### Components
| Component | Purpose (Functionality) | Dependencies |
|-----------|------------------------|--------------|
| [Name] | [What flow it supports] | [What it needs] |

### API Endpoints
| Endpoint | Flow | Request | Response |
|----------|------|---------|----------|
| POST /api/x | User uploads | {...} | {...} |

## Key Decisions

### Decision 1: [Title]
- Context: [Functionality driver]
- Options: [List]
- Trade-offs: [Table]
- Decision: [Choice]
- Rationale: [Why]

## Implementation Roadmap

### Critical (Must have for core flow)
1. [Component/feature]

### Important (Completes flows)
1. [Component/feature]

### Enhancement (Improves experience)
1. [Component/feature]

最终检查

在完成架构设计前：

• 已梳理所有用户流程
• 已梳理所有系统流程
• 每个组件都可追溯到相应功能
• 每个 API 端点都可追溯到相应流程
• 已记录决策及其权衡
• 已对实施路线图进行优先级排序