企业官网建设流程全解析

1. 先搞清楚一件事：你写的是"给谁看的地图"，不是"施工图纸"

我这些年参加过的项目评审里，最常出现的一个场面就是：设计师把概要设计书写得密密麻麻，类名、方法名、字段类型全列上去，五六百页；等到了详细设计阶段又拿不出东西，翻来覆去还是那几百页。评审专家问一句"你这个模块到底怎么实现的"，全场安静。

这事归根到底，是没搞清楚概要设计和详细设计各自的定位。我打个比方你去感受一下：

概要设计是画一张城市总规图。它回答的是"这个城市有几大片区、路网怎么走、功能分区在哪里、水电管网怎么接"。你把每条街道的门牌号都标上去，这不是规划图，这是地图册。详细设计是出单栋楼房的施工图，钢筋怎么配、混凝土标号多少、线管怎么埋、插座离地多高，每一处都要落到位，因为施工队要照着干活。

两类文档的差异不在"写得细不细"，而在决策颗粒度。概要设计决策的是"系统怎么切分、模块间怎么通信、数据怎么流动"，详细设计决策的是"单个模块内部怎么实现、类怎么划分、函数怎么组织、异常怎么处理"。前者回答what和why，后者回答how——但这个how是"怎么实现某个具体功能"，不是"整个系统怎么搭建"。

后面我以一套完整的实操拆解来讲清楚这两者到底是什么、各自要输出什么、以及我踩过的那些坑。

2. 概要设计：决定系统"长什么样"的那张蓝图

2.1 概要设计要回答的核心问题

写概要设计之前，先问自己四个问题，答不出来就别动笔：

• 系统要拆成哪几个部分？这些部分之间的边界在哪里？
• 每个部分对外提供什么能力？依赖什么能力？
• 数据在系统里怎么流转？从哪里产生、存到哪里、被谁消费？
• 部署和运行环境怎么组织？各个部分怎么联通？

这四个问题覆盖了概要设计的四大块：总体架构、模块划分、数据结构、部署方案。别小看这四个问题，项目能不能顺利进入编码阶段，全看它们有没有想清楚。

举个例子。前年我接手一个物联网设备管理平台，前任团队做概要设计时，把"设备接入"和"设备数据处理"放在同一个模块里，理由是"逻辑上它们都跟设备相关"。结果开发到一半发现：接入服务要支持高并发长连接，数据服务要做流式计算，两者对资源的需求完全不一样，硬绑在一起导致每次发布都要同时重启，线上抖动互相影响。后来花了三周拆模块，等于概要设计推倒重来。

这就是典型的模块划分没有考虑非功能性需求。模块划分不能只看业务的高内聚，还要看运行时的隔离性、扩展维度的一致性、以及团队协作的便利性。

2.2 总体架构图怎么画才可信

很多概要设计里的架构图，说白了就是画几个方框，连几条线。真正的架构图要能经得起追问：每一个方框是什么？它存在的理由是什么？它跟上下左右是怎么交互的？

我习惯用"分层+分区"的方式来组织架构图。分层解决的是"职责边界"问题，比如接入层、业务层、数据层；分区解决的是"运行边界"问题，比如管理端、客户端、开放接口区。整体上，架构图要能清楚回答三个问题：

1. 用户请求从哪进来，经过了哪些环节，最后落到哪里；
2. 每个环节如果是无状态的，状态存在哪；
3. 每个环节如果挂掉了，影响范围是什么，有没有冗余或降级方案。

画架构图还有个容易被忽略的点：要标出协议和接口风格。模块之间是走HTTP还是RPC？消息是同步还是异步？用的是什么格式？这些不标清楚，概要设计评审的时候架构师一定追问，因为通信方式直接决定了后续的详细设计怎么做。

2.3 模块划分的实操原则

模块划分这块，我现在用的是几个硬性原则，都是交了学费换来的。

第一个原则：一个模块只有一个"变化的理由"。如果两个功能点会因为同一个业务需求而同时修改，它们就应该在一起；如果会因为不同的需求而修改，它们就该分开。比如"订单创建"和"订单导出"，表面上都是订单相关，但导出会随着报表需求频繁变，创建则相对稳定，放一个模块里等于每次报表调整都要重新发布订单模块。

第二个原则：依赖方向必须单向。上层模块依赖下层模块的接口，但下层模块绝对不能反过来依赖上层。违反这个原则的代码，改起来就是牵一发动全身。我在评审时看到一个模块引用另一个模块的内部实现类，直接打回。模块间只能通过公共接口交互，这是底线。

第三个原则：模块的对外接口要"按业务能力"设计，而不是"按实现方式"设计。举个反例，有个项目把"用户信息查询"和"用户画像计算"拆成两个接口，乍一看挺合理，但业务上每次调用都要先查用户再算画像，产生大量往返调用。正确的做法是提供一个"获取用户完整信息"的聚合接口，底层再分成基础信息和画像信息两条实现路径。接口是给调用方用的，设计接口的人要有换位思考的能力。

2.4 接口设计和数据设计的要点

概要设计阶段的接口定义，粒度是"模块级"的。你要确定的是：这个模块向外部暴露哪些服务、每个服务的输入输出大致是什么、出错时用什么错误码体系。不需要定义到字段级、更不需要定义数据库表结构——那是详细设计的事，但接口的语义必须清晰。

数据设计在概要设计阶段要做的是：确定核心实体、实体之间的关系、数据的存储策略（哪些用关系型、哪些适合缓存、哪些要进消息队列）。注意，这里说的是"存储策略"，不是具体表结构。什么时候你会明显感觉概要设计的数据设计做得不好？就是你发现实体的归属说不清楚。比如"订单"这个实体，到底是订单服务自己管理，还是由用户服务统一管理？这种归属不定清楚，详细设计阶段做出来一定是混乱的。

2.5 部署方案：概要设计里最容易被低估的部分

部署方案在很多团队的概要设计里只有一张图，画几个服务器，标注一下nginx、MySQL、Redis。但真正有经验的架构师会在这里花很多精力，因为部署方案直接决定了系统的可用性、性能上限和运维成本。

你要在这个阶段决策的是：

• 每个模块部署几个实例？单机还是有集群？考虑到预期的访问压力，实例数怎么估算？
• 有没有需要区分环境的配置？比如测试环境和生产环境的连接串不同，这些差异怎么管理？
• 数据存储放在哪里？是否需要读写分离？如果需要分库分表，分片键怎么选？

我见过一个典型的反面案例：概要设计阶段没有考虑数据量增长的问题，所有业务数据都放在一个MySQL实例上，上线半年后单表过亿，查询慢到超时，只好半夜停机做迁移。如果概要设计阶段就把"未来的数据量级"作为一个约束条件带入设计，至少会给存储层多留一些扩展的空间。

3. 详细设计：让程序员"不需要动脑就能写代码"的实操文档

3.1 详细设计的输入和输出

详细设计的输入是概要设计确定的模块划分、接口契约和数据存储策略，输出的是可以指导编码的一切细节。换句话说，详细设计做完以后，一个合格的开发应该不需要再思考和模块相关的设计问题，直接照着文档写代码就行。

我习惯把详细设计比作一张"菜谱"。概要设计说了今天要做一桌川菜，有哪些菜；详细设计则是每道菜的食谱——主料配料各多少克、火候多大、焯水几分钟、分几步出锅。没有食谱，厨师全凭经验做，十个人能做出十个味道；有了食谱，来一个新厨子也能做出统一的味道。

详细设计应包含的内容，至少包括以下几个层面：

1. 类设计：有哪些类、类的职责、类的属性方法、类之间的关系（继承、组合、依赖）；
2. 流程设计：关键业务场景的时序流程、状态流转、异常分支；
3. 接口详细定义：方法签名、参数校验规则、返回值结构、错误码映射；
4. 数据库详细设计：表结构、索引策略、事务边界、数据约束；
5. 关键算法说明：如果有需要特定算法支撑的场景（比如限流算法、推荐策略、数据聚合逻辑），给出算法选型和核心逻辑说明；
6. 异常与边界处理：列出可能出现的异常场景和处理策略，保证代码的健壮性。

3.2 类设计的正确打开方式

类设计这块，很多刚入行的开发容易犯一个毛病：只画一个静态的类图，列出一堆类名，但你看不出这些类是怎么协作完成一个功能的。真正的类设计，要围绕职责来界定每个类的边界，并且用典型的调用序列把类的协作关系"演"一遍。

我常用的做法：先写核心业务场景的时序图，时序图里需要出现哪些参与者，就自然想到了需要哪些类；然后根据时序图中每个对象的职责，去定义类的属性和方法。这样做出来的类设计是"长"出来的，不是"造"出来的，可靠得多。

举个例子，一次在做用户积分系统的详细设计时，我先写"用户完成一笔订单后积分增加"的时序：Controller接收请求→校验参数→调用积分服务→积分服务计算本次积分→更新积分明细→返回结果。这个流程里涉及的参与者包括：积分Controller、积分Service、积分规则引擎、积分明细仓储。每个参与者的职责边界，在设计时就定清楚了。后来写代码的时候，基本就是把这些定义翻译成Java类，几乎没有设计上的返工。

3.3 状态机设计：状态流转必须"穷举"到位

业务系统里最怕的不是复杂算法，而是状态流转没有穷举。比如订单状态，你有"待支付、已支付、已发货、已完成、已取消"，看起来很简单，但一问具体场景就漏洞百出：支付超时了怎么处理？支付成功但回调晚到了怎么处理？发货后用户申请退款，状态怎么走？退款被驳回后能不能重新申请？

我强烈建议在详细设计里，给核心业务实体画一份完整的状态机图，并且配合一张"状态迁移表"，把每个可能的状态变迁、触发事件、前置条件、后置动作都列出来。别偷懒觉得"这个写代码的时候自然处理"，真正写代码的时候你会发现，没有穷举清楚的状态就是一个隐藏的地雷。

我做过一个售后系统，当时设计退款状态机，穷举了用户发起退款、商家同意、商家拒绝、用户修改退款申请、平台介入、退款关闭等十几个状态和二十多组迁移关系。列出来之后想清楚了几个容易出问题的场景：退款关闭后用户能不能重新发起？能，但要重新走审核流程，此前的流转记录必须保留。这些细节如果不写进详细设计，开发时一定会漏。

3.4 数据库表结构与索引设计

详细设计阶段的数据库设计，要精细到每个表的每个字段。字段类型、长度、是否可空、默认值、注释，一样都不能少。表设计做好了，代码写起来非常顺；表设计做烂了，再牛的开发也无米下锅。

字段设计有几点经验：

• 主键策略要明确，是自增、UUID还是雪花算法；
• 所有表都要有创建时间和更新时间，这是排查问题的生命线；
• 状态字段的类型要选对，能用整数就别用字符串，除非你的枚举值语义非常复杂；
• 金额字段不要用float/double，用decimal或整数分单位存储；
• 逻辑删除字段要有，但索引设计时要想清楚它会不会影响唯一索引。

索引设计这块，很多人只看"查询快不快"，却忽略了索引的维护成本。我遇到过一个真实案例：生产环境一张表因为加了七八个索引，每次写入要做大量索引维护，高峰期数据库CPU被打满。索引不是越多越好，要结合实际的查询模式、写入频率、数据量综合取舍。

3.5 写详细设计时我要求团队必须做的三件事

这三条是我最近几年带团队总结出来的，每一条都对应着真实事故。

第一，所有外部接口调用，必须定义超时时间和重试策略。做微服务拆分的系统，最大的风险就是依赖链上的某个下游服务变慢，把整个链路上的线程池打满。详细设计里如果没有定义超时和重试策略，开发写代码时的选择就是凭感觉，上线后出了问题就很难定位。

第二，所有状态变化，必须考虑日志留痕。详细设计里要定义清楚哪些操作必须记录审计日志，日志的字段结构是什么。我做过金融相关的项目，因为日志不规范，最后对账时非常痛苦，只好翻原始请求报文。早知如此，设计阶段就该把日志字段定清楚。

第三，所有批量操作，必须定义分批大小和失败处理策略。一个定时任务要处理十万条数据，是一次性查出来还是分批处理？中途失败了是整个重跑还是断点续跑？这些问题在详细设计里写清楚，开发就不需要临场发挥了。

4. 一个贯穿案例：用"订单超时自动关闭"看两种设计的差异

理论讲再多，不如一个具体的例子。我拿一个电商系统里比较经典的场景——"订单超时自动关闭"，来演示同一个功能在概要设计阶段和详细设计阶段分别是怎样呈现的。

4.1 概要设计阶段怎么描述这个功能

概要设计阶段不会直接告诉你"订单超时怎么实现"，而是把它放在消息和定时任务的架构框架里。具体来说，概要设计里会写：

在平台整体架构中，订单模块需要支撑超时订单的自动关闭能力。考虑到系统的可扩展性和实时性要求，超时事件通过延迟消息或定时任务触发，订单模块提供"关闭超时订单"的对外接口，供触发方调用。该接口应具备幂等性，防止重复触发导致的重复关闭。同时，订单状态的变更需按照订单状态机的定义流转，并产生对应的事件消息供下游业务感知。

看见没有，概要设计关心的是：这件事放在整个系统的哪个位置、跟谁交互、接口要有幂等性、状态流转要符合既定规则，但它不关心具体是延迟消息实现还是定时扫描实现，更不关心查哪张表、执行哪条SQL。这些实现细节是详细设计要做的。

4.2 详细设计阶段怎么描述这个功能

详细设计阶段则是这样呈现的：

• 实现方案：采用延迟消息方案。创建订单成功后，发送一条延迟消息，延迟时长对应订单超时时间（如30分钟）；延迟消息到期后，消费者消费消息，调用订单关闭服务。
• 类设计：包括OrderTimeoutConsumer（消息消费者）、OrderCloseService（订单关闭服务）、OrderRepository（订单仓储）等类，每个类的职责和关键方法都会定义清楚。
• 时序流程：用户下单→订单服务创建订单→发送延迟消息→消息队列到期→消费者消费→调用关闭服务→校验订单状态是否为"待支付"→是则更新状态为"已关闭"→发送订单关闭事件消息。
• 异常处理：如果消息消费失败，进入重试队列，重试3次；如果3次后仍然失败，进入死信队列，并由人工介入处理。同时，关闭操作依赖订单当前状态为"待支付"，若状态已变为"已支付"，则跳过不处理。
• 数据库操作：更新订单状态的SQL语句，以及更新前需要校验状态的SQL条件。

这就是两种设计的不同颗粒度。概要设计告诉你有这个功能、它在体系中的位置、它跟外部的契约；详细设计告诉开发这个功能如何一步步写出来。

4.3 边界的灰色地带：什么该放概要设计，什么该放详细设计

实际操作中，设计师最挠头的是"这件事到底该写进概要设计还是详细设计"。我提供一个常用的判断标准：如果这个决策影响了其他模块或整个系统的运行方式，放概要设计；如果只影响当前模块的内部实现，放详细设计。

比如"订单超时用延迟消息还是定时任务"，这个决策会影响消息中间件的选型、部署架构、运维方式，所以应该在概要设计阶段就定下来。而"延迟消息的消费者类名叫什么"、"重试次数是3次还是5次"，属于实现细节，留在详细设计阶段即可。

再比如接口设计：接口的路径、核心参数、返回结构、错误码，这些属于概要设计，因为别的模块要用；接口内部怎么解析参数、怎么校验、怎么调用底层服务，属于详细设计。

5. 常见误区、评审标准和一份可以直接套用的编写清单

5.1 我见过的四个高频误区

误区一：把概要设计写成"详细设计的目录"。我看到有人写概要设计，每个模块下面只写一句话"详见详细设计文档"。这等于没写。概要设计是独立的、能指导高层次决策的文档，不是索引页。

误区二：详细设计里又开始讨论模块划分和接口归属。这就是设计返工。详细设计阶段如果发现模块划分有问题，应该停下来找架构师讨论，而不是悄悄在详细设计里改掉，否则概要设计就失去了它作为"契约"的作用。

误区三：两份文档只有一个作者。有些团队概要设计和详细设计是同一个人写的，好处是思路连贯，坏处是缺少制衡。概要设计是架构师视角，详细设计是技术实现视角，视角不同，发现的问题也不同。

误区四：文档写完了就完了，不跟代码保持同步。这是我见过最普遍的问题。代码改着改着，设计文档早就过时了。我建议团队至少在每个迭代结束的时候，做一次文档与代码的对照更新。设计文档是活的，不是用来应付验收的材料。

5.2 怎么评审一份设计文档

我评审设计文档有一套自己的关注清单，分享出来供你参考：

概要设计评审清单：

• 是否清楚描述了系统的整体架构，以及每个组成部分存在的必要性？
• 模块划分是否遵循了高内聚、低耦合原则？依赖方向是否单向？
• 对外接口的语义是否清晰、稳定？
• 是否定义了关键数据的流转路径和存储策略？
• 是否考虑了非功能性需求（性能、可用性、安全性）？
• 部署方案是否合理？有没有明显瓶颈？

详细设计评审清单：

• 是否有完整的类设计和关键时序图？协作关系是否清晰？
• 核心业务的状态流转是否穷举完整？
• 异常处理和边界条件是否覆盖到位？
• 数据库设计与接口设计之间是否有矛盾？
• 开发人员拿到这份文档，是否可以不再依赖设计师的支持？

5.3 编写清单：照着这份内容写，基本不会返工

详细的编写大纲做了一张表，团队新人在动笔之前都会先过一遍这个清单。

概要设计的核心章节和关键内容：

• 引言：目的、范围、术语、参考资料
• 总体架构：架构风格、分层分区、部署形态
• 模块划分与职责定义：模块清单、模块间依赖关系
• 接口框架：模块对外提供的服务及核心数据契约
• 数据结构：核心实体、实体关系、存储策略
• 关键技术决策：关键技术选型及理由
• 非功能性设计：性能、安全、可用性、可运维性

详细设计的核心章节和关键内容：

• 模块概述：回顾该模块在整体架构中的位置与职责
• 类设计：类职责、关键属性与方法、类间关系
• 流程设计：关键时序、状态机、业务流程图
• 接口设计：详细方法签名、参数、返回值、异常定义
• 数据库设计：表结构、索引、约束、事务边界
• 关键设计细节：算法、并发控制、缓存策略、幂等方案
• 异常与边界：异常清单、处理策略、告警和日志设计

我的经验是，概要设计写完至少要让另一个不参与本项目的人读懂并回答出"这是一个什么样的系统"；详细设计写完要让一个没参与过的开发能照着写出代码。两者都做到了，你的设计文档就是合格的。

6. 踩坑实录：从"文档齐全"到"开发流畅"，我改了三版才想明白的事

最后分享一段我自己的经历。早年间我负责过一个中型系统，自认为文档写得特别全：概要设计一百多页，详细设计三百多页。结果开发阶段还是问题不断，说得最多的就是"这个我没法开始，文档里没说清楚"。

第一版我以为是团队经验不足，后来发现是我把自己脑子里已经知道的"常识"当成了不证自明的前提，压根没写进文档里。比如我写"用户模块提供查询用户信息服务"，心里想的是"这里应该走缓存，缓存没有就查库"，但我没写。开发拿到文档，不知道该不该加缓存，来问我，我还觉得问得蠢——现在回想，他问得对，我没写清楚。

第二版我把这些"常识"补上了，文档厚了一倍，问题变了：大家说"信息太多，找不到关键内容"。我又发现，文档不是越厚越好，而是检索效率要够高。

第三版我开始按照"读者视角"重写，每一章开头先明确"读完这一章你应该知道什么"，然后把结论放在前面，推导过程放在后面，表格和图示都配齐。这一版的效果明显好了，开发基本不需要频繁来问设计问题，各模块的编码节奏顺畅了很多。

这件事给我的启发是：设计文档的价值不是"我写了"，而是"别人用了不卡壳"。写文档的时候，一定不要站在"我什么都知道"的视角，要站在"一个只看了概要设计、没有参与前期讨论的开发"的视角，去审视每一段话是否足够清晰、足够直接。你替读者省掉的每一个疑惑，都是项目进度表上多出来的保障。