架构设计模板
架构设计模板
架构设计文档的价值不在于文档本身，而在于写文档的过程——它迫使我们在动手之前系统性地思考。一份好的设计文档能回答三个问题：为什么要做、怎么做、做到什么程度算完。
然而实际工作中，设计文档常见两类问题：要么太空——通篇架构图但缺乏落地细节；要么有遗漏——上线后才发现没考虑容灾、没定义回滚方案。根本原因是缺少一个结构化的思考框架。
本文提供一套经过实践验证的架构设计模板，包含 11 个维度。它的设计思路遵循一条主线：
问题驱动 → 方案设计 → 工程落地
- 问题驱动（第 1 章）：搞清楚为什么要做，边界在哪
- 方案设计（第 2-9 章）：从架构到细节，把方案想透
- 工程落地（第 10-11 章）：怎么部署、怎么分期交付
这 11 个维度既可以作为写设计文档的提纲，也可以当作评审时的 Checklist。每个维度给出要回答的关键问题和具体交付物，文末附可直接复用的 Markdown 模板。
1. 需求介绍
需求介绍的核心任务是把「为什么要做」讲清楚。它不是产品需求文档（PRD）的复述，而是从技术视角回答：现状有什么问题、我们打算怎么解决、做到什么程度算成功。
要回答的关键问题：
- 现状与痛点：当前系统/流程存在什么问题？对业务造成了哪些可量化的影响（故障频率、延迟、人工成本等）？
- 目标与范围：新方案要解决哪些问题？同样重要的是——不解决哪些问题？明确的边界能防止需求蔓延。
- 核心场景：列出 3-5 个最重要的使用场景。场景是连接需求与设计的桥梁——拆得越细，后面的设计越不容易遗漏。
- 干系人：谁是用户？谁会被改动影响？谁需要配合？
- 约束条件：时间窗口、预算、技术栈限制、合规要求等。
- 验收标准：用可量化的指标定义「做完了」，如 P99 延迟 < 200ms、可用性 > 99.95%、数据一致性延迟 < 1s。
实践建议：
用「场景走查」来验证需求完整性——把每个核心场景从头到尾走一遍，记录每一步涉及的系统、数据和人员。走查过程中自然会暴露出遗漏的约束和边界条件。
交付物： 需求背景文档（含场景列表、干系人矩阵、约束条件、验收标准）
2. 架构总览
架构总览是整个设计文档的「地图」。评审者和后续加入的开发人员，通常最先看的就是这一章。它需要回答：系统长什么样、分几块、各块之间怎么协作。
多视角描述架构：
业界常用 4+1 视图模型 或 C4 模型 来组织架构描述。对于多数项目，以下三个视角已经够用：
- 概念模型：系统中有哪些核心领域概念？它们之间的关系是什么？概念模型是整个设计的骨架。看似简单的概念定义——比如「部署包 = 介质包 + 配置」——往往直接决定了后续的技术设计。建议用 UML 类图或 ER 图表达。
- 逻辑架构图：系统分几层？每层有哪些模块？模块之间的依赖方向是什么？建议按能力分层（接入层 → 业务逻辑层 → 领域服务层 → 基础设施层），并标注每个模块的核心职责。
- 系统上下文图（System Context）：聚焦系统边界——哪些能力自研，哪些依赖外部系统？与周边系统的交互协议和数据格式是什么？这张图对于跨团队协作尤其关键。
画图原则：
架构图的唯一标准是易懂。一些实用建议：
- 每张图只表达一个层次的信息，避免在同一张图中混合部署细节和业务逻辑
- 用颜色/形状区分不同类型的组件（自研服务、外部依赖、中间件、数据存储）
- 标注关键数据流的方向和协议
- 推荐工具：Excalidraw（轻量手绘风）、draw.io（标准流程图）、PlantUML（文本生成图）
实践建议：
好的架构图是改出来的，不是一次画对的。建议在正式评审前做一次小范围宣讲，一是统一理解，二是通过反馈优化设计。
交付物： 概念模型图、逻辑架构图、系统上下文图
3. 核心流程
架构总览展示了系统的静态结构，核心流程则展示系统的动态行为——各组件如何协作完成具体业务场景。架构图 + 时序图是设计评审中最有价值的两张图，前者回答「是什么」，后者回答「怎么运转」。
场景驱动的梳理方法：
- 列出核心场景：从用户/调用方的视角，挑出最重要的 3-5 个场景（通常就是需求介绍中的核心场景）
- 画出 Happy Path：每个场景走一遍完整调用链路，用时序图（Sequence Diagram）标注参与方、调用顺序、数据流向
- 标注关键路径：在时序图上标记性能瓶颈点、状态变更点、数据持久化点
- 补充异常流程：这是最容易被忽略但最重要的部分——下游超时怎么办？重试是否幂等？消息丢了怎么补偿？数据不一致怎么修复？
常见陷阱：
很多设计文档只画了「晴天场景」，对异常路径一笔带过。但线上故障绝大多数发生在异常分支。建议对每个核心流程至少补充以下异常场景：
- 依赖服务不可用
- 网络超时 / 部分失败
- 数据不一致（如消息乱序、重复投递）
- 资源耗尽（连接池满、磁盘满、内存 OOM）
交付物： 核心场景的时序图（含 Happy Path 和关键异常流程）
4. 详细设计
详细设计是对架构中复杂组件的「放大镜」。不需要面面俱到，但对核心模块和高风险模块必须写清楚。
通常涵盖以下几类：
数据模型
- 核心表结构设计（字段、类型、约束）
- 索引策略（查询模式决定索引设计，而非反过来）
- 数据生命周期：冷热分离策略、归档/清理规则、数据保留期限
- 数据量评估：初始数据量、增长速率、单表上限
接口契约
- 对外 API 定义：路径、方法、入参、出参、错误码、版本策略
- 如涉及多系统协作，还需定义 SPI（扩展点接口）——即「我提供框架，你来实现具体逻辑」的扩展机制
- 接口幂等性设计：哪些接口需要幂等？幂等 Key 怎么生成？
- 建议遵循 OpenAPI 规范，便于自动生成文档和客户端代码
状态机
- 如业务有复杂状态流转（订单、审批、工单等），一张状态机图比大段文字清晰得多
- 明确每个状态转换的触发条件、执行动作和失败回退
关键算法/策略
- 路由策略（一致性 Hash、权重轮询等）
- 调度算法（优先级队列、公平调度等）
- 限流算法（令牌桶、滑动窗口等）
实践建议：
详细设计不必一次写完，可以在开发过程中迭代补充。但有两样东西必须在写代码之前定好：接口契约和数据模型——它们的变更成本最高，影响面最广。
交付物： 数据模型设计、接口文档（API/SPI）、状态机图（如有）、关键算法说明
5. 高可用设计
高可用设计回答一个核心问题：系统的某个部分挂了，整体还能不能用？ 这是从「能跑」到「能扛」的关键一步。
冗余与容灾
- 服务层：是否多实例部署？是否跨可用区（AZ）部署？单个 AZ 故障时服务是否仍然可用？
- 数据层：数据库是否有主从/多副本？故障切换是自动还是手动？RPO（数据丢失量）和 RTO（恢复时间）的目标是多少？
- 降级方案：核心链路和非核心链路是否隔离？当非核心依赖不可用时，核心功能是否能继续运行？降级是自动触发还是手动开关？
故障检测与自愈
- 健康检查：Liveness Probe（进程是否存活）和 Readiness Probe（是否可接收流量）分别怎么设计？
- 熔断策略：使用什么熔断器（如 Sentinel、Resilience4j）？熔断阈值和恢复策略如何配置？
- 限流策略：在哪一层限流（网关层 / 应用层）？限流粒度是什么（全局 / 租户 / 接口）？
- 隔离机制：线程池隔离、信号量隔离还是进程隔离？
数据一致性
- 一致性模型选择：强一致（CP）还是最终一致（AP）？在什么场景下可以接受最终一致？
- 跨服务一致性方案：Saga、TCC、本地消息表、事务消息等，各有适用场景。选择依据是什么？
- 补偿机制：当一致性被破坏时，如何检测和修复？是否需要对账任务？
可观测性
- 监控三支柱：Metrics（指标）、Logging（日志）、Tracing（链路追踪）各自的方案是什么？
- 关键监控指标按 RED 方法 分类：Rate（请求速率）、Errors（错误率）、Duration（延迟分布）
- 告警规则：分级（P0/P1/P2/P3）、阈值、通知渠道、响应 SLA
- 故障定位：如何从告警快速定位到根因？是否有 Runbook（故障手册）？
交付物： 高可用方案说明（含冗余策略、故障恢复流程、可观测性方案、告警清单）
6. 高性能设计
高性能设计的核心原则是先定目标，再找瓶颈，最后谈优化。没有量化目标的优化是盲目的。
性能目标
- QPS/TPS 目标：峰值多少？日常多少？需要预留多少 Buffer？
- 延迟目标：P50、P95、P99 分别是多少？（只看平均值会掩盖长尾问题）
- 数据量级：当前数据量多大？未来 1-3 年的增长预期？
瓶颈分析
- 识别系统是 CPU 密集型还是 IO 密集型
- 找出关键路径上的瓶颈点：数据库查询、外部 API 调用、序列化/反序列化、锁竞争等
- 使用 Amdahl 定律 评估优化收益——优化非瓶颈环节收效甚微
分层优化策略
| 层次 | 常用手段 |
|---|---|
| 接入层 | CDN 加速、负载均衡、连接复用、协议优化（HTTP/2、gRPC） |
| 应用层 | 本地缓存（Caffeine）、分布式缓存（Redis）、异步化（MQ）、批量合并、并行调用 |
| 数据层 | 读写分离、分库分表、索引优化、热点数据隔离、查询结果缓存 |
| 基础设施 | 水平扩容、弹性伸缩（HPA）、资源池化、JVM/Runtime 调优 |
压测验证
- 工具选择：JMeter（全功能）、wrk/hey（轻量 HTTP）、k6（脚本化场景）
- 压测策略：阶梯加压找出拐点，而非直接打满
- 压测环境与生产环境的差异要记录清楚（机器规格、数据量、网络拓扑）
- 压测报告要包含：吞吐量曲线、延迟分布、资源利用率、瓶颈定位
交付物： 性能目标定义、瓶颈分析、分层优化方案、压测计划
7. 可扩展性设计
可扩展性回答两个问题：加功能容不容易（业务扩展性）和加机器扛不扛得住更多量（容量扩展性）。
业务扩展性
好的扩展性设计遵循 开闭原则——对扩展开放，对修改关闭。具体评判标准：
新增一类需求时，是加配置就行，还是要写代码？写代码的话，是新增代码就行，还是要改已有代码？越往前者靠，扩展性越好。
常见的扩展性手段：
- 插件化 / SPI 机制：通过接口抽象 + 实现注册，新增场景只需新增实现类
- 策略模式 + 配置驱动：将业务规则外化为配置，通过策略分发路由到不同处理逻辑
- 事件驱动：核心流程产出事件，扩展功能订阅事件，彼此解耦
- 合理的领域划分：按业务能力（而非技术层次）划分模块，模块间通过明确的接口通信
容量扩展性
- 服务层：是否无状态？能否直接水平扩容？如果有状态（如本地缓存、WebSocket 长连接），扩容时如何处理？
- 数据层：数据库如何扩展？是否预留了分片键？分片策略是什么？
- 消息队列：Partition 数量是否支持后续扩展？Consumer Group 的 Rebalance 策略是什么？
- 单点瓶颈：系统中是否存在不可水平扩展的单点？如何规避或缓解？
交付物： 扩展点清单、领域划分图、容量扩展方案
8. 安全设计
安全设计即使当前没有明确需求，也应作为 Checklist 在评审中显式确认。写「经评估，本期暂不涉及」远好过完全不提——前者是有意识的决策，后者是遗漏。
认证与授权
- 认证方案：JWT、OAuth 2.0、Session、OIDC？Token 的签发、刷新和吊销机制？
- 授权模型：RBAC（基于角色）、ABAC（基于属性）？权限粒度到什么级别（菜单/按钮/数据行）？
- 服务间认证：内部服务间调用是否需要认证？方案是什么（mTLS、服务账号、JWT 传递）？
数据安全
- 敏感数据识别：哪些字段属于 PII（个人可识别信息）？如密码、手机号、身份证号、银行卡号
- 存储加密：敏感字段是否加密存储？加密算法和密钥管理方案？
- 数据脱敏：日志、监控、非生产环境中的敏感数据是否脱敏？脱敏规则是什么？
- 数据合规：是否涉及 GDPR、个人信息保护法等合规要求？数据跨境传输策略？
传输安全
- 是否全链路 HTTPS？TLS 版本和加密套件？
- 内部服务通信是否加密（mTLS）？证书管理方案？
审计与防护
- 审计日志：哪些关键操作需要记录？日志包含哪些字段（who/when/what/where）？日志的保留期限？
- 防攻击：SQL 注入、XSS、CSRF、SSRF 的防护措施？是否使用 WAF？
- 限流防刷：敏感接口（登录、短信验证码、支付）是否有专门的限流策略？
交付物： 安全设计说明（含认证方案、数据分级与保护策略、审计要求）
9. 技术选型
技术选型是影响最深远的决策之一——选错了，后续所有人都在还债。好的选型不追求「最先进」，而追求「最合适」。
要回答的关键问题：
- 核心语言和框架的选择依据是什么？
- 中间件的选择（消息队列、缓存、数据库、搜索引擎等）基于什么考量？
- 是否做过技术预研或 PoC 验证？结论是什么？
选型的评估维度：
| 维度 | 要点 |
|---|---|
| 功能匹配度 | 能否满足当前和可预见的未来需求？ |
| 生产成熟度 | 是否有大规模生产验证？社区活跃度和生态完善度？ |
| 团队匹配度 | 团队是否熟悉？学习曲线和上手成本？——技术再好，团队用不起来也白搭 |
| 运维成本 | 部署复杂度、监控支持、故障排查难度、升级迁移成本 |
| 许可证合规 | 开源许可证是否满足商业需求（注意 AGPL、SSPL 等传染性许可证）？ |
实践建议：
- 用 ADR（Architecture Decision Records） 记录每个关键技术决策的上下文、选项、决策和后果，方便后续团队理解「当初为什么这么选」
- 如有多个候选方案，列对比表时不要超过 5 个维度，聚焦最关键的差异点
- 团队编码规范、Git 工作流、Code Review 流程等工程规范也可以写在这一节
交付物： 技术栈清单、关键选型对比表（或 ADR）、工程规范说明
10. 部署方案
部署方案不只是「怎么把服务跑起来」，更要回答：怎么安全地发布变更、出了问题怎么快速回滚。
环境规划
- 环境定义：开发（Dev）→ 测试（Test/QA）→ 预发（Staging）→ 生产（Production）
- 环境隔离：各环境之间如何隔离（独立集群 / Namespace 隔离 / 标签路由）？
- 配置管理：配置与代码是否分离？环境差异（副本数、资源配额、域名、Feature Flag）通过什么机制管理？推荐 ConfigMap + 密钥管理服务（如 Vault）
发布策略
- 滚动更新（Rolling Update）：适合大多数无状态服务，K8s 原生支持
- 蓝绿部署（Blue-Green）：适合需要快速切换和回滚的场景，需双倍资源
- 灰度发布（Canary）：适合风险较高的变更，按流量比例 / 用户标签 / 地域逐步放量
- 发布过程中的健康检查（Readiness Gate）和自动回滚（基于错误率 / 延迟的 Rollback 策略）
回滚方案
- 代码回滚流程：谁触发？如何执行？回滚后是否需要通知下游？
- 数据库回滚：Schema 变更是否向下兼容？是否准备了回滚脚本？建议采用 Expand-Contract 模式处理不兼容变更
- 配置回滚：配置变更是否有版本化和快速回滚能力？
资源规划
- 每个服务的 CPU / 内存 Request 和 Limit 如何设定？建议基于压测数据而非经验估算
- 是否需要 HPA（Horizontal Pod Autoscaler）？扩缩容的指标和阈值？
- 存储方案：云盘（持久化）、对象存储（文件/图片）、本地盘（临时缓存）分别用在哪里？
交付物： 部署架构图（物理视图）、环境配置清单、发布策略说明、回滚 Runbook
11. 架构演进规划
大型项目不可能一步到位，分阶段交付是常态。架构演进规划的目标是让团队在每个阶段都知道做什么、为什么先做这个、后面还要做什么。
MVP 定义
- 最小可用版本的范围是什么？用场景定义 MVP——用户能跑通哪些核心场景，就是 MVP
- 建议在 MVP 之前做一次架构原型验证（Walking Skeleton）：用最小的端到端场景跑通整个架构，验证核心技术方案的可行性。这一步能在早期暴露架构层面的问题，避免后期大面积返工
里程碑规划
- 按阶段拆分：每期交付什么功能？交付标准是什么？
- 阶段间的技术依赖：前一期没完成是否会阻塞后一期？有没有可以并行的工作？
- 建议用甘特图或里程碑表格可视化，让进度一目了然
技术债务管理
- 当前设计中有哪些已知的妥协和 TODO？为什么现在不做？
- 每笔技术债务的「利息」是什么——不偿还会导致什么后果？
- 计划在什么时间点偿还？建议将技术债务纳入迭代计划，而非无限期搁置
团队分工
- 各模块由谁负责？模块间的接口由谁定义、谁联调、谁验收？
- 团队能力与分工是否匹配？是否需要安排技术预研或培训？
- 再好的架构，如果不考虑团队的实际能力，也未必落得了地
交付物： MVP 范围定义、里程碑计划表、技术债务台账、团队分工矩阵
附：可复用的架构设计文档模板
以下模板可直接复制使用，按实际情况填写或删除不需要的章节。
# [系统名称] 架构设计文档
> 作者：xxx | 日期：yyyy-MM-dd | 版本：v1.0 | 状态：Draft / In Review / Approved
---
## 1. 需求介绍
### 1.1 现状与痛点
<!-- 当前系统存在什么问题？可量化的业务影响？ -->
### 1.2 目标与范围
<!-- 要解决什么？不解决什么（明确边界）？ -->
### 1.3 核心场景
| # | 场景名称 | 场景描述 | 优先级 |
|---|----------|----------|--------|
| 1 | | | |
### 1.4 干系人
| 角色 | 人员 | 职责 |
|------|------|------|
| | | |
### 1.5 约束条件
<!-- 时间、预算、技术栈、合规等 -->
### 1.6 验收标准
| 指标 | 目标值 | 度量方式 |
|------|--------|----------|
| | | |
---
## 2. 架构总览
### 2.1 概念模型
<!-- 核心领域概念及其关系（附图） -->
### 2.2 逻辑架构图
<!-- 系统分层、模块划分、依赖关系（附图） -->
### 2.3 系统上下文
<!-- 与周边系统的交互：协议、数据格式、调用方向（附图） -->
---
## 3. 核心流程
### 3.1 场景一：[场景名称]
**Happy Path：**
<!-- 时序图 -->
**异常流程：**
<!-- 超时 / 下游不可用 / 数据不一致 的处理方式 -->
### 3.2 场景二：[场景名称]
<!-- 同上 -->
---
## 4. 详细设计
### 4.1 数据模型
<!-- 核心表结构、索引策略、数据生命周期 -->
### 4.2 接口契约
<!-- API / SPI 定义：路径、方法、入参、出参、错误码 -->
### 4.3 状态机
<!-- 状态流转图（如有） -->
### 4.4 关键算法
<!-- 核心算法/策略的描述 -->
---
## 5. 高可用设计
### 5.1 冗余与容灾
<!-- 多实例 / 跨 AZ / 主从切换 / 降级方案 -->
### 5.2 故障检测与自愈
<!-- 健康检查 / 熔断 / 限流 / 隔离 -->
### 5.3 数据一致性
<!-- CP vs AP 选择 / 跨服务一致性方案 / 补偿机制 -->
### 5.4 可观测性
| 类型 | 指标/工具 | 告警阈值 | 响应 SLA |
|------|-----------|----------|----------|
| Metrics | | | |
| Logging | | | |
| Tracing | | | |
---
## 6. 高性能设计
### 6.1 性能目标
| 指标 | 目标值 |
|------|--------|
| QPS | |
| P99 | |
| 数据量级 | |
### 6.2 瓶颈分析
<!-- 关键路径上的瓶颈点及根因分析 -->
### 6.3 优化方案
<!-- 按接入层 / 应用层 / 数据层 / 基础设施分层说明 -->
### 6.4 压测计划
<!-- 工具、场景、环境差异、通过标准 -->
---
## 7. 可扩展性设计
### 7.1 业务扩展性
<!-- 扩展点清单 / SPI 机制 / 领域划分 -->
### 7.2 容量扩展性
<!-- 无状态服务扩容 / 有状态组件扩展 / 单点瓶颈规避 -->
---
## 8. 安全设计
- **认证与授权**：
- **数据安全**：
- **传输安全**：
- **审计日志**：
- **防攻击**：
<!-- 如本期不涉及，请注明「经评估，本期暂不涉及」并说明原因 -->
---
## 9. 技术选型
| 类别 | 选型 | 备选方案 | 选择依据 |
|------|------|----------|----------|
| | | | |
### 关键决策记录（ADR）
<!-- 对于有争议的选型，记录上下文、选项、决策和后果 -->
---
## 10. 部署方案
### 10.1 环境规划
| 环境 | 集群/NS | 副本数 | 资源配额 | 域名 |
|------|---------|--------|----------|------|
| Dev | | | | |
| Test | | | | |
| Staging | | | | |
| Prod | | | | |
### 10.2 发布策略
<!-- 滚动更新 / 蓝绿 / 灰度，以及健康检查和自动回滚机制 -->
### 10.3 回滚方案
<!-- 代码回滚流程 / 数据库兼容性 / 配置回滚 -->
---
## 11. 架构演进规划
### 11.1 MVP 定义
<!-- 第一个版本的最小可用范围（用场景定义） -->
### 11.2 里程碑
| 阶段 | 时间 | 交付内容 | 验收标准 | 依赖 |
|------|------|----------|----------|------|
| | | | | |
### 11.3 技术债务
| 债务 | 产生原因 | 影响（利息） | 计划偿还时间 |
|------|----------|--------------|--------------|
| | | | |
### 11.4 团队分工
| 模块 | 负责人/团队 | 上下游依赖 |
|------|-------------|------------|
| | | |
---
## 附录
### 术语表
| 术语 | 定义 |
|------|------|
| | |
### 参考文档
<!-- 相关 PRD、技术预研报告、竞品分析等 -->
### 变更记录
| 版本 | 日期 | 变更人 | 变更内容 |
|------|------|--------|----------|
| v1.0 | | | 初稿 |