概念、概要、详细设计编写心法

一文讲清概念设计、概要设计、详细设计别再把三种文档写混了设计文档不是越细越好而是要在正确阶段回答正确问题概念设计统一业务语言概要设计搭系统骨架详细设计画代码施工图。很多研发同学写设计文档时最容易混淆三个词概念设计、概要设计、详细设计。有人把概念设计写成需求背景有人把概要设计写成接口清单也有人在概设里直接写函数、字段、错误码。结果评审时大家越看越累业务没对齐架构没讲清代码细节倒是堆了一堆。这三类文档不是互相替代而是从粗到细、从业务到技术、从共识到实现的三层设计。一、先用一句话区分三者文档类型核心问题一句话理解概念设计我们在设计一个什么业务世界把业务概念、角色、边界和规则讲清楚概要设计系统整体准备怎么实现把架构、模块、链路和关键方案讲清楚详细设计开发具体应该怎么写把接口、数据结构、状态、异常和实现细节讲清楚如果用盖房子类比文档类比概念设计先确定这是住宅、商铺还是办公室里面有哪些人和空间概要设计决定几层楼、怎么分区、水电怎么走、哪些系统连接详细设计画施工图标清尺寸、材料、管线、开关位置和施工细节二、概念设计怎么写概念设计的目标是把“大家脑子里默认知道的东西”写成明确共识。它不急着讲技术而是先回答这个业务里有哪些角色、对象、关系、规则和边界1. 概念设计主要写什么内容写法业务背景为什么需要这个系统或功能它解决什么真实问题目标用户 / 参与者谁会使用它谁会被它影响谁提供外部能力核心概念这个业务里有哪些关键名词例如订单、商品、支付、取货码概念关系这些概念之间是什么关系例如一个用户可以有多个订单核心场景用户在什么场景下使用最典型路径是什么业务规则哪些事情允许哪些不允许哪些状态必须满足边界与非目标本次设计覆盖什么不覆盖什么2. 概念设计不要写什么不建议写原因具体类名和函数名这已经进入详细设计数据库字段定义概念设计只需要说明有哪些业务对象接口路径和请求参数接口属于概要设计或详细设计技术选型细节概念设计重点是业务共识不是技术方案完整异常分支只需要说明关键业务规则不展开每个错误码概念设计最怕两种问题一种是只有大词没有概念另一种是直接跳到技术实现。例如只写“提升用户体验、提高效率、优化流程”这不是概念设计因为没有讲清业务世界。反过来如果一上来就写接口、表结构、线程模型也不是概念设计因为跳得太细了。三、概要设计怎么写概要设计的目标是说明系统整体怎么搭起来。它站在技术方案层面回答模块怎么拆、链路怎么走、数据怎么流、失败怎么兜底。1. 概要设计主要写什么内容写法设计目标与非目标明确本方案做什么、不做什么防止评审发散现状链路当前系统怎么工作问题在哪里总体方案新方案的整体结构和关键思路模块职责哪些模块参与每个模块负责什么关键链路典型请求从哪里来到哪里去中间经过哪些模块关键数据与配置只写核心输入输出、关键参数来源和消费方兼容性与兜底老版本、不支持场景、失败场景怎么处理风险与应对方案风险、性能风险、稳定性风险如何控制测试验证思路如何证明方案有效不必列完整测试用例2. 概要设计不要写太细不建议写应该放到哪里每个函数内部怎么 if else详细设计完整接口字段校验规则详细设计数据库索引、字段长度、默认值详细设计所有错误码和提示文案详细设计代码级伪实现详细设计概要设计里可以有“关键链路”和“关键数据”但重点是跨模块协作不是代码施工。概设可以写不建议写成用户提交订单后订单服务创建待支付订单某个函数第一个 if 判断什么支付成功后订单状态更新并通知门店某个字段长度是多少支付失败时订单保持待支付或超时关闭某个错误码具体是多少四、详细设计怎么写详细设计的目标是让开发可以照着落地让测试可以据此补充验证让后续维护者能看懂当时的实现选择。它进入代码和接口层面关注字段、状态、时序、异常、并发、幂等、数据一致性等具体问题。1. 详细设计主要写什么内容写法接口设计请求路径、方法、入参、出参、错误码、鉴权方式数据结构表结构、字段含义、索引、默认值、约束状态机状态有哪些状态之间如何流转非法流转如何处理核心算法 / 逻辑关键判断、计算规则、排序策略、调度策略异常处理网络失败、超时、重复请求、数据不一致怎么处理并发与幂等重复提交、回调乱序、多端操作如何保证正确性配置与开关配置项、灰度开关、默认值、回滚方式日志与监控打哪些日志、上报哪些指标、如何排查问题测试点功能、边界、异常、兼容、性能、安全等测试点2. 详细设计要具体到什么程度设计项详细设计粒度接口到字段名、类型、是否必填、错误码数据库到字段、索引、唯一约束、状态枚举状态机到每个状态允许从哪里来、到哪里去异常到超时、重试、回滚、补偿策略并发到锁、幂等键、事务边界、重复回调处理日志到关键日志点和排查字段详细设计最怕“看起来完整其实不能指导编码”。例如只写“支付成功后更新订单”还远远不够。一份可落地的详细设计至少要继续回答支付回调重复怎么办订单已取消后又收到支付成功怎么办回调金额和订单金额不一致怎么办数据库更新失败怎么办通知门店失败是否回滚订单日志里如何定位这笔订单五、三者边界怎么判断可以用一个简单问题判断这段内容是在帮大家统一业务理解还是在帮大家判断技术方案还是在指导开发写代码你正在写的内容更适合放在哪里订单、商品、门店、取货码分别是什么意思概念设计用户下单后系统经过哪些模块概要设计创建订单接口有哪些字段详细设计订单有哪些状态业务上表示什么概念设计 / 概要设计都可写高层即可订单状态流转的完整校验规则详细设计支付服务和订单服务如何协作概要设计支付回调重复到达如何幂等详细设计本期不支持配送只支持自取概念设计 / 概要设计表字段、索引、唯一键详细设计最简单的口诀是文档口诀概念设计先把业务世界说清楚概要设计再把系统骨架搭起来详细设计最后把代码施工图画出来六、用一个通俗例子串起来线上点咖啡到店自取假设我们要做一个小功能用户可以在手机上下单买咖啡支付后到店凭取餐码取咖啡。同一个需求在概念设计、概要设计、详细设计里应该怎么写1. 概念设计示例先讲清业务世界概念设计不急着讲服务、接口和数据库而是先讲这个业务怎么理解。项目内容目标用户提前点咖啡并在线支付到店后凭取餐码自取价值减少排队等待提高门店出杯效率非目标本期不支持外卖配送不支持多人拼单不支持会员积分角色说明顾客在手机上下单、支付、查看取餐码门店店员接收订单、制作咖啡、标记完成支付平台完成支付并通知系统结果系统管理商品、订单、支付状态和取餐码概念含义门店用户选择取咖啡的线下地点商品可以购买的咖啡或加料选项订单用户一次购买行为的记录支付用户为订单付款的动作和结果取餐码支付成功后生成用于到店取咖啡订单状态订单从创建到完成的业务阶段这就是概念设计讲清“业务世界有哪些东西它们怎么互相作用”。2. 概要设计示例再讲系统怎么搭概要设计要从业务共识进入技术方案。重点不是字段细节而是模块怎么协作。模块职责用户端展示商品、提交订单、发起支付、展示取餐码商品模块管理商品、价格、上下架状态订单模块创建订单、维护订单状态、生成取餐码支付模块创建支付单、接收支付回调、通知订单模块门店后台展示待制作订单支持店员标记制作完成通知模块支付成功、咖啡可取时通知用户阶段关键动作下单用户选择门店和商品订单模块创建待支付订单支付支付模块发起支付支付成功后通知订单模块制作门店后台看到已支付订单店员开始制作取餐制作完成后展示取餐码用户到店自取完成店员核销取餐码订单变为已完成这就是概要设计讲清“系统由哪些模块组成主流程怎么闭环失败时怎么兜底”。3. 详细设计示例最后讲代码怎么落详细设计开始进入接口、字段、状态和异常处理。状态含义允许流转到CREATED订单已创建等待支付PAID、CLOSEDPAID已支付等待制作MAKING、REFUNDINGMAKING门店正在制作READYREADY制作完成等待取餐COMPLETEDCOMPLETED用户已取餐订单完成不允许继续流转CLOSED超时未支付或用户取消不允许继续流转REFUNDING退款处理中CLOSED设计点说明创建订单接口入参包含用户、门店、商品、杯型、温度、糖度出参包含订单 ID、金额、状态、支付单信息支付回调幂等使用支付单号或订单号保证重复回调只处理一次金额校验回调金额必须等于订单应付金额状态校验只有 CREATED 状态可以变为 PAID取餐码核销只有 READY 状态允许核销为 COMPLETED日志要求核销时记录门店、订单、操作人、时间和结果这就是详细设计讲清“开发具体怎么实现边界怎么校验异常怎么处理”。七、总结概念设计、概要设计、详细设计不是三份重复文档而是三种不同粒度的思考方式。文档解决的问题典型产物概念设计业务理解是否一致角色、概念、关系、规则、边界概要设计技术方案是否成立架构、模块、链路、数据流、风险兜底详细设计代码实现是否清楚接口、字段、状态机、异常、幂等、日志、测试点如果只写概念设计方案会停留在业务描述开发不知道怎么做。如果只写概要设计系统骨架有了但代码细节容易走偏。如果只写详细设计很容易在业务和架构没对齐时就陷入实现细节。更合理的顺序是顺序目的概念设计先统一业务语言概要设计再确定系统骨架详细设计最后指导代码落地写设计文档的本质不是为了堆格式而是为了降低沟通成本、提前暴露风险、让团队在动手写代码之前先达成共识。一句话记住阶段你要证明什么概念设计我们理解的是不是同一个业务概要设计这个技术方案能不能跑通详细设计开发照着写会不会出问题