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

一、为什么这篇值得读

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

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

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

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

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

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

三、概要设计的 4 个原则

源文档里写得很清楚：

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

四、概要设计的内容清单

4.1 总述

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

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

4.2 总体设计

从全局角度说：

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

输出图：

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

4.3 外部接口

总体说明：

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

4.4 模块设计（核心）

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

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

4.5 数据结构

• 逻辑结构
• 物理结构

4.6 容灾设计

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

4.7 监控设计

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

4.8 用户界面设计

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

4.9 安全设计

• 认证
• 授权
• 加密
• 审计

4.10 其它设计

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

4.11 制定规范

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

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

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

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

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

6.1 详细设计的关键产出

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

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

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

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

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

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

八、核心 5 点提炼

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

九、When to use

参考资料

• 项目全流程模板/2设计/1概要设计.md
• 项目全流程模板/2设计/设计.md
• 项目全流程/2设计/设计.md

2024+ 视角

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

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

2015 视角 vs 2024 视角对照：

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