架构设计基础：概要设计与详细设计的区别与实践

Fri, 30 Oct 2015 00:00:00 +0800

这是一份关于"概要设计 vs 详细设计"的对比梳理，源于 2015 年前后的架构师培训资料。为什么把它单独提一篇？因为在多数团队里，“概要设计"和"详细设计"的边界是模糊的——有人写到伪代码、有人只画个框图，评审会上吵成一团。

一、为什么这篇值得读

很多团队把"设计文档"当成一个文档：写完直接进开发。结果：

评审会上没人能看完 50 页的"设计文档”
设计粒度不统一，有人写到 SQL，有人只画模块图
模块之间的接口没定清楚，联调时互相甩锅

正确做法是先概要、后详细——概要设计解决"分模块、定接口、估工作量"，详细设计解决"模块内算法、流程、状态"。两个文档职责分离、粒度分离、受众分离。

When to use：当一个系统超过 3 个人、超过 3 个月、超过 3 个子系统时，概要设计文档就是必需的。否则项目进入开发就是"集体蒙眼摸象"。

二、概要设计 vs 详细设计：分界

维度	概要设计	详细设计
回答的问题	系统怎么分？模块怎么交互？	模块内部怎么实现？
粒度	模块、子系统、接口	类、函数、算法
产物	分层数据流图、结构图、数据字典	流程图、状态图、伪代码、局部变量说明
受众	架构师、技术总监、项目经理	模块开发者本人
评审重点	模块划分是否合理、接口是否清晰	算法是否正确、边界条件是否覆盖
改动代价	改了概要 → 重新评估工作量	改了详细 → 一般不影响工期
数量级	通常 10-50 页	一个模块 5-20 页（视复杂度）

Tip：概要设计是多人协作的契约——3 个开发者按概要分工，每人拿到的接口定义清晰到**“传什么、返回什么、什么时候调”。详细设计是单人实现的笔记**——算法怎么写、变量怎么命名、异常怎么抛，是开发者自己的事。

三、概要设计的 4 个原则

源文档里写得很清楚：

评价总体设计的可行性——概要设计是判断"这个项目能不能做、按什么方案做"的依据
检查模块是否完整——保证每个功能都有对应模块实现，不能有"无主功能"
评估开发工作量、指导开发计划——尤其在不写详细设计的情况下，模块数 × 经验系数 = 工期
避免两个误区：
- ❌ 过于重视业务流程（应该在需求里画，不该在概要里写）
- ❌ 过于重视细节实现（应该在详细里写，不该在概要里写）

四、概要设计的内容清单

4.1 总述

需求或目标（讲一下事情的起源）、环境、局限

这是给评审者**30 秒内理解"为什么做这个系统"**的入口。

4.2 总体设计

从全局角度说：

组织结构
功能
处理流程
有哪些模块
模块间的关系
运行环境

输出图：

系统结构图
系统流程图
数据流程图

4.3 外部接口

总体说明：

外部用户
软、硬件接口（可用资源）
第三方系统
网络协议
数据格式

4.4 模块设计（核心）

每个模块"做什么"、简要说明"怎么做"（输入、输出、处理逻辑、与其它模块或系统的接口），处在什么逻辑位置、物理位置。

模块描述——说明哪些模块实现了哪些功能
模块层次结构——可使用某个视角的软件框架图表达
模块间的关系——模块间依赖关系描述、通信机制描述
模块的核心接口——说明模块传递的信息、信息的结构（重点！必须写到"参数名+类型+含义"）
处理方式设计——说一些满足功能和性能的算法（只写算法思想，不写实现）

4.5 数据结构

逻辑结构
物理结构

4.6 容灾设计

出错信息
出错处理
降级方案
数据备份与恢复

4.7 监控设计

运行模块组合
控制
时间
告警阈值
日志规范

4.8 用户界面设计

界面布局
交互流程
UI 规范引用

4.9 安全设计

认证
授权
加密
审计

4.10 其它设计

国际化
性能
兼容性
可扩展性

4.11 制定规范

设计原则
代码规范
接口规约
命名规则

五、概要设计的关键产出物

产出物	作用	形式
分层数据流图	描述系统从输入到输出的加工过程	图
结构图	描述模块的层次和调用关系	图
数据字典	描述系统中所有数据项的含义、类型、长度、取值范围	表
模块清单	列出所有模块及功能	表
接口清单	列出所有模块间接口	表
关键流程说明	文字描述关键业务如何流转	文字 + 流程图

六、详细设计：模块内的实现

详细设计阶段，每个模块可以分给不同人并行设计。设计者工作对象是一个模块：

根据概要设计赋予的局部任务和对外接口
设计并表达出模块的算法、流程、状态转换

6.1 详细设计的关键产出

流程图——模块内主要处理流程
状态图——模块涉及的状态机
局部变量——模块内使用的临时变量
关键函数签名——参数、返回值、异常

6.2 详细设计 vs 概要设计的回退规则

如果发现有结构调整（如分解出子模块等）的必要，必须返回到概要设计阶段，将调整反应到概要设计文档中，而不能就地解决、不打招呼。

Why：详细设计改了不影响别人，但概要设计改了影响所有模块的接口。默默改概要设计 = 让所有下游模块的接口定义失效。

七、概要设计的 5 个常见坑

接口定义不细——只写"调用模块 A"，不写"传什么、返回什么、什么时机调"。联调时两套理解
数据字典缺失——文档里所有"用户 ID"都是一个意思吗？长度？类型？枚举值？没有数据字典就各写各的
过度细化——把详细设计的内容写到概要设计，评审会变成代码 review，没人能看完
不画部署图——只有逻辑架构，没有物理部署。运维拿不到"这台机器跑什么"的答案
不写非功能——性能、可用性、安全、合规等都不写，验收时客户发现没满足

八、核心 5 点提炼

概要设计是"分模块、定接口、估工期"的契约——它的粒度停在模块和接口，不写到类和方法
详细设计是"单模块的实现笔记"——粒度到函数和算法，单模块可并行设计
数据结构 > 算法——概要设计阶段数据字典比算法重要，因为数据结构是模块间共享的
改了概要必须通知所有相关人——默默改概要 = 默默改契约 = 撕毁合作基础
不写详细设计时，概要要写得更细——反之则要保留详细设计的预算

九、When to use

场景	必备设计
1 人、1 个月、1 模块	不需要正式设计文档
2-3 人、2-3 个月、单一系统	概要设计
3+ 人、3+ 月、多子系统	概要设计 + 详细设计
多团队、外部审计、合规项目	概要设计 + 详细设计 + 评审记录 + 变更记录

参考资料

2024+ 视角

2015 年的"概要 vs 详细"分界到 2024-2026 年依然成立，但形式与协作方式发生了几个关键变化：

C4 模型取代大段文字：Simon Brown 的 C4 模型（Context → Container → Component → Code）成为软件架构图的事实标准。一张 C4 上下文图顶 50 页"总体设计说明"。Structurizr DSL + Structurizr Lite 是写 C4 的工具首选。
ADR（Architecture Decision Records）正式成为评审产物：每个重要决策一个 ADR（Markdown 文件 + git 管理），模板：
- 状态：提议 / 已接受 / 已废弃 / 已取代
- 上下文：要解决什么问题
- 决策：选了哪个方案
- 后果：trade-off、风险、未来影响
架构评估从 ATAM → ADR + Fitness Functions：
- 2015 年前用 ATAM（架构权衡分析法） 做架构评审
- 2024 年用 ADR 累积 + 持续验证：每个架构属性（性能 / 可用性 / 安全）有对应的 Fitness Function（自动测试），CI 中持续验证
云原生架构让"物理部署"和"逻辑架构"分离：
- 概要设计要写"逻辑架构" + “物理部署（K8s/Serverless）” 两层
- Infrastructure as Code（Terraform / Pulumi / Crossplane）让部署图也是 git 的一部分
微服务架构的概要设计新要素：
- 服务边界（按业务能力 / DDD 子域）
- 通信模式（同步 REST/gRPC vs 异步事件）
- 数据一致性（Saga / Outbox / CDC）
- 可观测性（OTel / RED/USE 指标）
架构师角色升级：从"画图 + 评审"到"决策 + 治理 + 演进"——C4 + ADR + Fitness Function + ADR 看板 + 架构腐化检测（SonarQube / ArchUnit）。
“概要 vs 详细"边界依然不变：
- 概要：模块 / 接口 / 部署 / 数据流（C4 Level 1-3）
- 详细：类 / 函数 / 算法 / 状态机（C4 Level 4 + 序列图）
- 永远不要在概要设计里写伪代码——让代码本身就是详细设计

2015 视角 vs 2024 视角对照：

维度	2015	2024
图表	Visio / Rational Rose	C4 + Structurizr + Mermaid
决策记录	邮件 / Word 评审	ADR（git 管理）
物理部署	表格 + Visio	Terraform / Helm / Crossplane
架构评估	ATAM 评审会	ADR + Fitness Function + 持续验证
架构腐化	人工 review	ArchUnit + SonarQube

结论：2015 年这篇"先概要、后详细"的方法论至今仍是行业最佳实践，但工具从 Visio 转向 C4 + ADR + IaC，治理从一次性评审转向持续验证。

架构设计 on Liangweidong's blog