如何写前端技术方案文档?

前言

百度百科对计算机软件的的定义为：“计算机软件( Software，也称软件)是指计算机系统中的程序及其文档，程序是计算任务的处理对象和处理规则的描述；文档是为了便于了解程序所需的阐明性资料。程序必须装入机器内部才能工作，文档一般是给人看的，不一定装入机器”。

可以看到概念里提到了"文档"，说明写文档是软件开发过程必不可少的一个环节，如果文档没有写好，那么软件也不能算是优秀的软件。

可对于一般软件开发人员来讲，写代码要比写文字容易得多。很多时候我们都能看到类似的事情，项目做完了，设计文档还没有；当别人问起，某个功能当时为什么这么设计，一时语塞；项目代码里没有注释，时间长了，自己都忘记当时代码为什么要这么写；当接手别人的项目的时候，要排查个问题只能一行行读代码，唯一的文档就是随脚手架自动生成的README.md。以上这些都是我们平时开发中可能会遇到的问题，为什么会这样？其实就是因为平时没有写文档的习惯，文字没有得以保留，只靠记忆，时间长了确实记不住。

下文就想和大家一起探讨一下，前端为什么写技术方案，怎么写前端技术方案。

写技术方案目的

在讲为什么要写前端方案文档前，先讲一个我的好朋友小明的故事。

小明也是一个前端，在接到需求的时候，他会大致看一下需求文档，感觉没有什么太大的问题，然后就看看交互、视觉稿上有哪些页面，接下来就开始迫不及待地写代码了。

新建一个文件、写模板、写样式、写交互逻辑，一气呵成。新模块的需求是小明最喜欢的，因为不用去理解其它功能的逻辑，可工作中还是少不了维护历史代码。小明很聪明，他发现有个功能加个参数传过去做个逻辑判断就能实现，于是他也就这么做了。

开发完后，小明觉得很满意，因为很快就实现了需求，代码在脑中的逻辑比较清晰，里面也许有些地方写的不太妥当，但是也无妨吧。虽然不是全局最优的，但可以说是局部最优的。

版本提测之后，QA 开始针对各种边界问题和极端场景给小明提 bug。譬如输入框输入emoji表情后提交接口报错、按钮连续点击触发了多次请求、买家角色页面展示正常但是供应商角色展示错误……

在改 bug 的过程中小明渐渐带上了痛苦面具，代码逻辑被改的支离破碎，不得不为代码打各种补丁，方法的参数加了一个又一个，逻辑里的条件判断加了又加。到这个时候小明的开发积极性已经被消磨的差不多了，开始对 QA 提出的 bug 表示质疑，他会用“原来就是这么设计的呀”、“这个问题不在这次的需求范围内”等等这样的说辞来避免对代码的更改。

过了一段时间，小明又接到一个需求，需要对上次开发的模块增加一些功能。翻开代码的时候，小明整个人都崩溃了。以前代码的逻辑自己早就忘记了，面对自己已经看不懂的代码，开始对自己进行灵魂拷问“这个方法有什么用？这个方法怎么有这么多参数？为什么逻辑这么复杂？”，“代码在不同页面之间跳来跳去，还有长得几乎一模一样的代码，他们的逻辑到底是什么样的？”，“为什么会有这么多标识位，这么多魔法数字，他们都是干嘛的？”。注释什么的是不存在的，即使存在，也不明白在讲些什么。

刚接手项目的时候小明还不断吐槽之前开发的人不写文档、不写注释，没过多久小明也成了别人口中的那个"他"。

以上故事根据真实事件改编。

我觉得写技术方案文档是能解决小明的一部分问题的，“谋定而后动，三思而后行”，都是在说这个道理。当然写文档也不是万能。对比一下后端，会发现他们在写代码之前都会做方案设计，好像难道后端的开发时间很充裕或者说前端的技术方案不值一提吗？肯定不是。方案设计是软件工程里的一个最佳实践，通常做技术方案的过程中会体现出软件整体的架构，当对核心流程梳理完成之后，最后基本都能落实到代码上。也就是说好的技术方案能体现出最后代码的逻辑，通过看方案就能知道代码怎么写。这样就防止了在写代码过程中边写边改，最后导致代码结构混乱的问题。

怎么写技术方案

如果我们按照后端那一套方法论和模板来做前端方案设计，发现根本写不出来什么内容，这时候我们要重新审视方案设计的套路，来发现前后端的不同。

业务模型可能前后端都是一致的，毕竟我们是解决同一个业务问题。但其中也有稍许差别，前端有些数据不是从后端获取的，或者说不一定非要从后端获取，这点我们需要在做设计的时候考虑进去。譬如同一个 H5 页面在微信公众号内和钉钉内需要展示不同的主题色。

前后端对于核心流程的定义也不同，对于后端来说核心流程是数据的产生、流转、消费，但是提到流程，在前端来说更多的是页面的流转、组件的交互、用户的操作。同样一件事情，在前后端来看完全是两个东西，比如保存一项数据，后端需要关注的可能是如何校验、如何存储、如何索引、如何关联。但前端要关注的却是校验接口的出入参、校验结果的展现形式如何、是跳转还是覆盖或者弹窗、不同屏幕和设备下如何适配。

后端更注重逻辑架构与部署图，因为后端需要为服务化，服务间边界的定义要非常清晰、具体。前端与微服务对应的，应该就是组件了，但是组件覆盖的范围太广，从一个按钮到一个页面都可以称之为组件，甚至现在比较火热的微前端中的一个子应用也可以成为一个组件，所以前端的组件需要被划分成页面、模块、控件等不同封装层次的单元。在这个划分的过程中，逻辑架构自然体现出来了。同时前后端解决的问题不同，导致关注点也不同，前端需要关注页面的还原，比如页面的元素应该如何抽象，样式应该如何复用，这个是后端不用考虑的。

接口可不仅仅是http请求，任何与其它模块交互逻辑都应该明确其入参和出参。后端需要关注暴露出去的dubbo或者http接口，因为这体现了系统间交互的逻辑。而对于前端来说对应的也应该明确独立模块或者页面之间的交互逻辑，所以也就需要明确这些"接口"。

关于实施方案，前后端的关注点也有稍许不同，后端更关心系统之间的集成，旧数据的兼容。而前端应该关心的是桌面设备和移动设备的区别，或者微信、支付宝等不同渠道的集成。

对比之后前端技术方案的脉络渐渐清晰起来。结合上面的方法论，下面就实际案例讲解一下。

技术方案的案例

在政采云产研团队的研发流程中，前端方案设计是在需求和交互评审之后、测试评审和正式开发之前，属于需求阶段和开发阶段的中间节点。此时需求的功能和用户交互场景基本已经确定，前后端技术方案之间互相补充描述清楚需求的可行性、整体架构和具体实现。同时在测试分析之前，也是帮助 QA 梳理测试重点和用例场景。

第一章，概述。一般会简单描述项目的背景和价值，做一件事情的意义或者说动机是很重要的，一般从需求文档里进行概括即可。然后解释后面文档中需要用到的一些专有名词，达成大家对一些名词的共识是很重要的。

第二章，相关文档。收集版本开发的相关文档，这样开发的时候只要通过这一个前端技术方案文档，就能找到所有的文档，有时候我也会把这些网页整理到一个浏览器书签文件夹里。

第三章，任务拆解。主要描述开发任务归属、预计工时，还有里程碑。

估时是按照页面维度，拆分页面内主要功能，进行时间估算，时间估算按照静态 demo 和 JS 交互来分别评估会准一些。之后得出时间乘以一个 1.3 的系数（因为每周还会有不同的会议、沟通也会占用时间）。

时间评估的时候，像下图一样，本地花点时间列一下 —— 这样的好处是一便于统计和比对，看有无遗漏；二评估出的时间，给到业务方、PM 等，会对我们有职业化上的认可——会认为这样的评估粒度，时间是准确的你这个人是靠谱的；另外，细粒度的维度，也便于业务方寻找需求最长路径，看需求或者走迭代也方便做出判断。

第四章，总体设计。列举开发规范，还有逻辑架构。一图胜千言，有关时序的逻辑强烈建议用图来代替。流程图、时序图、状态图，让你的技术方案文档逼格满满清晰明了。

下图为页面跳转逻辑图，如果交互有缺失的话，前端技术方案里可以进行补位

第五章，详细设计。这一章就是整篇技术方案的重点了，包括功能说明、流程说明、模块详细设计、外部依赖等四个小节。

最完美的状态，就是如下图所示，这一部分写完了，代码也跃然于纸上了。

也可以适量地贴一些代码，可以很好地在技术分析的时候阐述清楚改动点

下图为下单流程卡券选择时序图。复杂的时序逻辑已经不是文字能说的清的了，时序图让交互更清晰

下图为前端组件入参设计的案例，开源组件库写的都不错，可以直接参考。

最后三章可以写一写技术分析 Checklist、测试数据、遗留问题

最后附上政采云前端团队的前端技术方案模板，戳这里 ()。当然大家也可以根据自己的情况进行内容的增删，譬如我们原本是在技术方案里维护发布的 CheckList，但是后端也维护了一个，我们就索性建了一个公用的文档，归档在一起。

最后的最后推荐两个好用的画图工具：

Node 社群

我组建了一个氛围特别好的 Node.js 社群，里面有很多 Node.js小伙伴，如果你对Node.js学习感兴趣的话（后续有计划也可以），我们可以一起进行Node.js相关的交流、学习、共建。下方加 考拉 好友回复「Node」即可。