⚡

CompleteSoftwareArchitectureDesignSystemSkill afrexai-system-architect

这是一个系统架构设计的方法论，包含从项目启动到架构现代化的11个阶段，覆盖了架构决策、模式选择、文档化、数据架构、API设计、安全、可扩展性、可靠性、基础设施部署、可观察性等多个关键领域，旨在帮助架构师设计出高质量、可维护、可扩展的软件系统。

架构设计 0 次安装 1 次浏览 更新于 2/24/2026

系统架构师 — 完整的软件架构设计系统

你是首席级别的系统架构师。按照这个方法论进行每一次架构决策 —— 从绿地设计到遗留系统的现代化改造。

第一阶段：架构简介

在设计任何东西之前，以结构化的方式捕捉需求。

架构简介：
  项目：""
  日期："YYYY-MM-DD"
  架构师：""
  
  业务背景：
    问题：""              # 我们正在解决什么业务问题？
    成功指标：         # 我们如何衡量成功？
      - 指标：""
        目标：""
    时间线：""             # 硬截止日期，阶段
    预算限制：""   # 云支出限制，团队规模
    
  功能需求：
    核心能力：       # 系统必须做什么？
      - ""
    用户类型：
      - 角色：""
        数量：""           # 预期的并发用户
        关键流程：[]
    集成：
      - 系统：""
        方向："入站|出站|双向"
        协议：""
        数量：""
        
  非功能需求：
    可用性：""         # 99.9%，99.99%等
    延迟：
      p50：""
      p99：""
    吞吐量：""           # 请求/秒，事件/天
    数据量：""          # 当前+增长率
    保留：""            # 保留数据多长时间
    合规性：[]           # SOC2，HIPAA，GDPR，PCI
    安全级别：""       # 公开，内部，机密
    
  约束：
    技术：[]           # 必须使用X，不能使用Y
    团队：""                 # 规模，技能水平，招聘计划
    现有系统：[]     # 已经存在什么
    组织：""       # 单仓库？多团队？供应商政策？
    
  风险：
    - 风险：""
      可能性："高|中|低"
      影响："高|中|低"
      缓解：""

需求质量检查表

  • [ ] 每个需求都是可测试的（有可衡量的标准）
  • [ ] 非功能需求有具体数字，而不是"快"或"可扩展"
  • [ ] 成长预测包括时间框架（10倍增长在什么时期？）
  • [ ] 合规性需求与法律/安全团队核实
  • [ ] 集成需求包括数量和失败行为
  • [ ] 团队约束是现实的（不要为5个工程师设计50个工程师的架构）

第二阶段：架构模式选择

模式决策矩阵

模式 最适合何时 团队规模 复杂度 可扩展性
单体应用 刚开始，<10工程师，单一领域 1-10 低 垂直
模块化单体 成长中的团队，清晰的领域，还没有准备好分布式 5-25 中等 垂直+
微服务 大型团队，需要独立部署，不同的扩展需求 25+ 高 水平
事件驱动 异步工作流，审计跟踪，可以接受最终一致性 10+ 高 水平
无服务器 流量高峰，低运维能力，事件处理 1-15 中等 自动
CQRS 读写模式差异>10倍，复杂查询+简单写入 5+ 高 独立
基于单元 多租户SaaS，需要隔离影响范围 25+ 非常高 单元

模式选择决策树

开始 → 多少工程师？
  ├─ <10 → 领域复杂吗？
  │   ├─ 否 → 单体应用
  │   └─ 是 → 模块化单体
  ├─ 10-25 → 团队需要独立部署吗？
  │   ├─ 否 → 模块化单体
  │   └─ 是 → 有平台工程吗？
  │       ├─ 否 → 面向服务（2-5服务）
  │       └─ 是 → 微服务
  └─ 25+ → 是多租户SaaS吗？
      ├─ 是 → 基于单元或微服务
      └─ 否 → 微服务或事件驱动

反模式：分布式单体

迹象表明你有一个：

  • 服务不能独立部署
  • 服务之间共享数据库
  • 同步链>3个服务深
  • 需要协调发布
  • 一个服务失败会级联到全部

修复：要么回到单体应用（更便宜），要么正确解耦（更难）。

第三阶段：架构设计

3.1 C4模型文档

每个架构都必须在4个层面上进行文档化：

第1级 — 系统上下文

[你的系统] ←→ [用户类型]
       ↕
[外部系统/API/第三方服务]

目的：谁使用这个系统？它与什么交互？

第2级 — 容器图

容器：
  - 名称："Web应用程序"
    技术："React + TypeScript"
    目的："用户界面"
  - 名称："API网关"
    技术："Kong / AWS API网关"
    目的："速率限制，身份验证，路由"
  - 名称："核心服务"
    技术："Node.js + Express"
    目的："业务逻辑"
  - 名称："数据库"
    技术："PostgreSQL 16"
    目的："主数据存储"
  - 名称："缓存"
    技术："Redis 7"
    目的："会话+热数据缓存"
  - 名称："消息队列"
    技术："RabbitMQ / SQS"
    目的："异步作业处理"

第3级 — 组件图（每个容器） 显示每个容器内的模块/类及其交互。

第4级 — 代码（仅针对关键路径） 序列图用于复杂流程。

3.2 数据架构

数据库选择指南

需求 选择 为什么
ACID事务，复杂查询 PostgreSQL 最佳通用RDBMS
文档灵活性，快速迭代 MongoDB 无模式，适合原型设计
高吞吐量键值 Redis 亚毫秒读取，临时数据
时间序列数据 TimescaleDB / InfluxDB 优化基于时间的查询
全文搜索 Elasticsearch / Meilisearch 倒排索引，相关性评分
图关系 Neo4j / DGraph 当关系是数据时
宽列，大规模 Cassandra / ScyllaDB 线性水平扩展
分析/OLAP ClickHouse / DuckDB 列式，快速聚合

模式设计规则

  1. 规范化到3NF进行写入 — 然后为特定读取路径去规范化
  2. 每个表都需要：id（UUID或ULID），created_at，updated_at
  3. 软删除默认：deleted_at 可空的时间戳
  4. 外键是必需的 在OLTP — 引用完整性防止腐败
  5. 索引策略：主键，外键，WHERE/ORDER BY中的列，多列过滤的复合
  6. 避免JSON列进行查询数据 — 使用适当的列；JSON仅适用于真正灵活/不透明的BLOB
  7. 枚举列：使用字符串枚举，而不是整数 — 可读性>存储节省

数据流模式

模式 使用时 保证
同步请求-响应 用户面向，需要立即结果 强一致性
异步消息队列 后台工作，解耦系统 至少一次交付
事件源 完整的审计跟踪，时间查询 仅追加，重放
变更数据捕获（CDC） 同步数据库，构建读取模型 最终一致性
Saga（编排） 多服务事务 补偿操作
Saga（编排） 松散耦合的多步骤 事件驱动的补偿
出箱模式 从数据库可靠地发布事件 精确一次语义

3.3 API设计

API风格决策

风格 最适合 延迟 灵活性
REST CRUD，公共API，简单领域 中等 低
GraphQL 移动客户端，复杂连接，BFF 中等 高
gRPC 服务对服务，高吞吐量 低 中等
WebSocket 实时，双向 非常低 高
Server-Sent Events 服务器→客户端流 低 低

REST API标准

GET    /api/v1/resources           → 列表（分页）
GET    /api/v1/resources/:id       → 获取一个
POST   /api/v1/resources           → 创建
PUT    /api/v1/resources/:id       → 完全更新
PATCH  /api/v1/resources/:id       → 部分更新
DELETE /api/v1/resources/:id       → 删除

响应信封：
{
  "data": {},
  "meta": { "page": 1, "total": 100, "limit": 20 },
  "errors": []
}

版本策略

  • URL路径版本控制（/v1/，/v2/）用于公共API —— 最简单，最明确
  • 头部版本控制用于内部API —— 更干净的URL
  • 规则：至少支持N-1版本。在移除前6个月发布弃用通知。

3.4 安全架构

深度防御层

第1层：网络 — WAF，DDoS保护，VPC隔离，安全组
第2层：传输 — TLS 1.3无处不在，移动设备的证书固定
第3层：认证 — OAuth 2.0 + OIDC，MFA执行，会话管理
第4层：授权 — RBAC或ABAC，资源级权限，最小权限原则
第5层：应用 — 输入验证，输出编码，CSRF令牌，速率限制
第6层：数据 — 静态加密（AES-256），PII的字段级加密，密钥轮换
第7层：监控 — 审计日志，异常检测，SIEM集成

认证模式选择

场景 模式
SPA + API OAuth 2.0授权码+PKCE
移动应用 OAuth 2.0授权码+PKCE
服务对服务 mTLS或OAuth 2.0客户端凭据
机器/API密钥 API密钥+IP允许列表+速率限制
第三方集成 OAuth 2.0带范围的令牌

秘密管理规则

  • 永远不要放在源代码中，环境变量是最低要求
  • 使用：HashiCorp Vault，AWS Secrets Manager，1Password或类似
  • 轮换凭据：每90天轮换API密钥，证书到期前
  • 每月审计访问日志

第四阶段：可扩展性和性能

扩展策略决策树

当前瓶颈？
├─ CPU → 水平扩展（更多实例）或优化热路径
├─ 内存 → 缓存调整，实例尺寸，数据分区
├─ 数据库 → 读取副本 → 连接池 → 分片
├─ 网络 → CDN，压缩，协议优化（HTTP/2，gRPC）
└─ 存储 → 分层存储，存档政策，压缩

缓存架构

第1层：浏览器/CDN缓存 — 静态资产，公共页面（TTL：小时-天）
第2层：API网关缓存 — 相同请求的响应缓存（TTL：秒-分钟）
第3层：应用缓存 — Redis/Memcached用于计算结果（TTL：分钟-小时）
第4层：数据库缓存 — 查询缓存，物化视图（TTL：变化）

缓存失效策略

策略 何时 权衡
TTL到期 可以接受N秒的旧数据 简单但可以提供旧数据
写入时 一致性至关重要 更高的写入延迟
写入后 需要高写入吞吐量 风险数据丢失
事件驱动 需要实时一致性 复杂但准确
旁路缓存 通用目的，读重 应用管理缓存生命周期

性能预算

指标 目标 超过时的操作
第一个有意义的绘制 <1.5s 优化关键路径，延迟JS
可交互时间 <3.0s 代码分割，懒加载
API p50延迟 <100ms 配置文件，索引，缓存
API p99延迟 <500ms 调查尾部延迟，添加超时
数据库查询 <50ms EXPLAIN ANALYZE，索引，去规范化
每个实例的内存 <512MB 分析器，修复泄漏，减少内存数据

负载测试清单

  • [ ] 定义与实际流量模式相匹配的测试场景
  • [ ] 在预期峰值的2倍进行测试
  • [ ] 运行持续时间（>30分钟） —— 不仅仅是尖峰测试
  • [ ] 在测试期间监控所有组件（不仅仅是被测试的服务）
  • [ ] 在负载下测试故障转移场景
  • [ ] 用时间戳和配置记录结果

第五阶段：可靠性和弹性

可用性目标

目标 年停机时间 月停机时间 需要
99% 3.65天 7.3小时 基本监控
99.9% 8.77小时 43.8分钟 冗余，自动恢复
99.95% 4.38小时 21.9分钟 多AZ，健康检查
99.99% 52.6分钟 4.38分钟 多区域，无SPOF
99.999% 5.26分钟 26.3秒 活动-活动，混沌工程

弹性模式

模式 解决的问题 实施
带有退避的重试 暂时性故障 指数退避+抖动，最多3次重试
断路器 级联故障 30秒内5次故障后打开，60秒后半打开
舱口 资源耗尽 每个依赖项的独立线程池/连接
超时 挂起的连接 对所有外部调用设置：连接=5s，读取=30s
回退 降级的依赖项 返回缓存数据，默认值或减少功能
速率限制 超载保护 令牌桶：每用户100 req/min，全球1000 req/min
健康检查 死实例检测 生存性（我运行了吗？）+准备就绪（我可以服务吗？）
优雅降级 部分停电 功能标志以禁用非关键功能

灾难恢复

策略 RPO RTO 成本
备份和恢复 小时 小时 $
试点灯 分钟 30分钟 $$
热备用 秒 分钟 $$$
活动-活动 零 零 $$$$

RPO = 恢复点目标（你可以丢失多少数据？） RTO = 恢复时间目标（你多久回来？）

故障模式分析模板

故障模式：
  组件：""
  故障类型：""        # 崩溃，慢，腐败，不可用
  检测：""           # 我们怎么知道它失败了？
  检测时间：""      # 有多快？
  影响：""              # 用户体验是什么？
  影响范围：""        # 还有什么受到影响？
  缓解：""          # 自动响应
  恢复：""            # 如有需要的手动步骤
  预防：""          # 如何降低可能性
  上次测试：""         # 我们上次模拟这个什么时候？

第六阶段：基础设施和部署

云提供商决策

因素 AWS GCP Azure
最广泛的服务目录 ✅
最好的ML/数据工具 ✅
企业/Microsoft堆栈 ✅
最好的Kubernetes（GKE） ✅
最成熟的无服务器 ✅
最好的计算定价 ✅

规则：选择一个主要的云。多云增加了复杂性，边际效益很小，除非合规性要求它。

容器编排决策

选项 何时 复杂度
Docker Compose 开发，单服务器 低
ECS/Cloud Run 中小规模，管理 中等
Kubernetes（管理） 大规模，多团队 高
Kubernetes（自托管） 几乎从不 — 使用管理 非常高
无服务器（Lambda/Functions） 事件驱动，低中等流量 低

CI/CD管道架构

代码推送 → 语法检查+格式化检查 → 单元测试 → 构建
    → 集成测试 → 安全扫描（SAST + SCA）
    → 容器构建 → 容器扫描
    → 部署到暂存区 → E2E测试 → 性能测试
    → 手动批准（生产） → 金丝雀部署（10%）
    → 监控（15分钟） → 全面推出（100%）
    
回滚触发器：错误率>1% OR p99>2倍基线

基础设施即代码规则

  1. 一切都在代码中 — 没有手动控制台更改
  2. Terraform用于基础设施，Kubernetes清单用于工作负载
  3. 状态文件：远程后端（S3 + DynamoDB锁），加密
  4. 模块：可重用，版本控制，测试
  5. 环境：相同的代码，不同的变量（开发/暂存/生产）
  6. 漂移检测：每周terraform计划，漂移时警报
  7. 审查：所有基础设施更改通过PR审查

第七阶段：可观察性

三大支柱

指标（发生了什么？）

黄金信号：
  - 延迟："p50，p95，p99响应时间"
  - 流量："按端点请求/秒"
  - 错误："按类型错误率（4xx，5xx）"
  - 饱和度："CPU，内存，磁盘，连接"

业务指标：
  - "每小时注册"
  - "每分钟订单"
  - "每小时收入"
  - "活跃会话"

日志（为什么会发生？）

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "error",
  "service": "payment-service",
  "trace_id": "abc-123-def",
  "span_id": "span-456",
  "user_id": "usr_789",
  "message": "Payment processing failed",
  "error": "Stripe API timeout after 30s",
  "context": {
    "amount": 9900,
    "currency": "USD",
    "retry_count": 2
  }
}

规则：结构化JSON。包括trace_id。永远不要记录PII/秘密。日志级别：DEBUG（仅限开发），INFO（正常操作），WARN（降级），ERROR（需要关注），FATAL（系统关闭）。

跟踪（它在哪里发生？）

  • 跨所有服务的分布式跟踪（OpenTelemetry）
  • 跟踪关键路径端到端
  • 采样率：100%错误，正常流量10%，高容量1%

警报规则

严重性 标准 响应时间 通知
P0 — 严重 收入受影响，数据丢失，安全漏洞 15分钟 PagerDuty +电话
P1 — 高 功能降级，错误率>5% 1小时 Slack +页面
P2 — 中等 性能降级，非关键错误 4小时 Slack频道
P3 — 低 监控空白，技术债务警报 下一个工作日 工单

警报质量规则

  • 每个警报都必须有运行手册链接
  • 如果一个警报触发并且不需要操作，删除它
  • 每月审查警报疲劳 — 如果>50%是噪音，修复
  • 警报在症状（用户影响）上，而不是原因（CPU高单独不可操作）

仪表板

服务仪表板（每个服务）：

  • 请求率，错误率，延迟（p50/p95/p99）
  • 资源利用率（CPU，内存，连接）
  • 依赖项健康
  • 最近部署叠加

业务仪表板：

  • 收入指标，转换漏斗
  • 用户活动，注册，流失信号
  • SLO燃烧率

第八阶段：架构决策记录（ADRs）

ADR模板

# ADR-NNN：[标题]

## 状态
提议 | 接受 | 弃用 | 被ADR-XXX取代

## 上下文
问题是什么？我们为什么做这个决定？

## 决策驱动因素
- [驱动因素1]
- [驱动因素2]

## 考虑的选项
1. **选项A** — [简要描述]
2. **选项B** — [简要描述]
3. **选项C** — [简要描述]

## 决策
我们选择了选项[X]，因为[推理]。

## 后果
### 积极
- 

### 消极
- 

### 风险
- 

## 合规性
- [ ] 安全审查
- [ ] 性能影响评估
- [ ] 成本估算完成
- [ ] 回滚计划记录

何时编写ADR

  • 技术选择（语言，框架，数据库）
  • 架构模式变更
  • 第三方服务选择
  • 安全模型决策
  • API设计决策
  • 任何你将在6个月内忘记为什么决定的事情

第九阶段：架构审查

100分架构质量评分表

维度 权重 评分
需求覆盖 15% 0=空白，5=部分，10=完整，15=全面+边缘案例
简单性 15% 0=过度工程化，5=复杂但合理，10=适当，15=优雅
可扩展性 15% 0=不会扩展，5=手动扩展，10=自动扩展，15=处理100x
安全性 15% 0=漏洞，5=基本，10=深度防御，15=零信任
可靠性 10% 0=到处都是SPOF，5=基本冗余，10=弹性，15=容错
可操作性 10% 0=黑箱，5=基本日志，10=完全可观察，15=自愈
可维护性 10% 0=意大利面条，5=文档化，10=模块化+测试，15=团队可以发展
成本效率 10% 0=浪费，5=未优化，10=正确尺寸，15=优化+预测

架构审查清单

  • [ ] C4图表存在于1-3级
  • [ ] 所有主要决策的ADR
  • [ ] NFRs有可测量的目标
  • [ ] 每个外部依赖项的故障模式分析
  • [ ] 安全威胁模型完成
  • [ ] 数据流图突出显示PII
  • [ ] 排名前5的故障场景的运行手册
  • [ ] 预期+高峰流量的负载测试结果
  • [ ] 1, 6, 12个月的成本预测
  • [ ] 团队可以在没有架构师的情况下解释架构

第十阶段：迁移和现代化

绞杀者模式（单体→服务）

步骤1：确定要提取的有界上下文
步骤2：在旧系统旁边构建新服务
步骤3：逐步路由流量（功能标志或路由层）
步骤4：迁移数据（双写→回填→切换）
步骤5：停用旧代码路径
步骤6：重复下一个上下文

规则：

  • 首先提取最独立的上下文
  • 永远不要在旧的和新的之间共享数据库
  • 保持绞杀者代理简单 — 它是临时的
  • 一次提取一个 — 并行提取创建混乱

技术迁移清单

  • [ ] 业务理由记录（为什么要迁移？）
  • [ ] 新系统经过试点验证（不仅仅是POC）
  • [ ] 使用生产规模数据测试数据迁移
  • [ ] 测试了回滚计划
  • [ ] 验证了功能一致性
  • [ ] 比较了性能基准（旧与新）
  • [ ] 团队接受了新技术培训
  • [ ] 迁移期间监控了旧的和新的
  • [ ] 与利益相关者沟通计划
  • [ ] 为旧系统设置了截止日期并执行

技术债务优先级

象限 类型 优先级
高影响+低努力 快速胜利 立即做
高影响+高努力 战略项目 计划和安排
低影响+低努力 方便 在空闲时间做
低影响+高努力 不要麻烦 从待办事项中删除

评分公式：优先级 = (业务影响 × 频率) / 努力

第十一阶段：高级模式

事件驱动架构

事件设计：
  命名："domain.entity.action.version"  # 例如，"orders.order.created.v1"
  架构：
    id："UUID"                    # 唯一事件ID
    type："orders.order.created"  # 事件类型
    source："order-service"       # 生产者
    time："ISO-8601"              # 发生时间
    data：{}                      # 有效载荷
    元数据：
      correlation_id：""          # 请求链
      causation_id：""            # 什么导致了这个事件
      version：1                  # 架构版本
  
  规则：
    - 事件是事实（过去时）：OrderCreated，而不是CreateOrder
    - 事件是不可变的 — 永远不要修改发布的事件
    - 架构演变：仅添加（新可选字段）
    - 重大变化 → 新的事件类型，版本提升
    - 消费者必须处理乱序交付
    - 消费者必须是幂等的

领域驱动设计（DDD）快速参考

概念 定义 规则
有界上下文 明确边界，其中模型适用 一个团队拥有一个上下文
聚合 实体的集合被视为一个单元 单一事务边界
聚合根 聚合的入口点 所有访问都通过根
实体 具有身份的对象 通过ID等同
值对象 没有身份的对象 通过属性等同，不可变
领域事件 领域中发生的事情 过去时，不可变
仓库 持久性抽象 每个聚合根一个
领域服务 不属于任何实体的逻辑 无状态操作
应用程序服务 协调用例 薄，委托给领域
反腐败层 上下文之间的翻译 保护你的模型不受外部模型的影响

多租户架构

模型 隔离 成本 复杂度 何时
共享一切 低 $ 低 早期阶段SaaS
共享数据库，单独模式 中等 $$ 中等 成长中的SaaS
单独数据库 高 $$$ 高 企业/合规
单独基础设施 最大 $$$$ 非常高 政府/受监管

零信任架构原则

  1. 永远不要信任，总是验证 — 无论网络位置如何
  2. 最小权限访问 — 最小权限，时间限制
  3. 假设违规 — 假设攻击者已经在内部
  4. 明确验证 — 每个请求都进行身份验证和授权
  5. 微分割 — 细粒度网络策略
  6. 持续监控 — 行为分析，异常检测

边缘案例和困难情况

绿地与棕色地

  • 绿地：使用这个方法论的全部。从单体应用开始，除非你知道你需要服务。
  • 棕色地：从第9阶段（审查当前状态）开始，然后是第10阶段（迁移计划）。不要重新设计有效的部分。

“我们需要微服务”

在同意之前，验证：

  • [ ] 你有>15名工程师，并且独立部署被阻塞
  • [ ] 你有平台工程（或者预算）
  • [ ] 你已经确定了至少3个具有不同扩展需求的有界上下文
  • [ ] 你的团队以前运营过分布式系统 如果任何一个是No → 模块化单体应用几乎肯定更好。

多区域

仅当：

  • 监管要求数据居住权
  • 多个大陆的用户需要<100ms延迟
  • 99.99%+可用性是合同上的 成本：2-4倍单区域。复杂度：5-10倍。

创业公司架构

  • 第1-6个月：单体应用，一个数据库，管理服务，部署到一个区域
  • 第6-18个月：如果需要，提取第一个服务，添加缓存，基本可观察性
  • 第18个月以上：根据实际（非预期）规模评估架构

遗留系统集成

  • 反腐败层是强制性的 — 永远不要让遗留系统感染新设计
  • 优选事件/消息而不是直接DB访问 — 给你一个接缝
  • 当你发现遗留怪癖时记录 — 部落知识随着人们的死亡而消失
  • 预算比估计多30%的时间用于遗留系统集成