在政采云如何写前端技术方案文档
前言
百度百科对计算机软件的的定义为：“计算机软件( Software，也称软件)是指计算机系统中的程序及其文档，程序是计算任务的处理对象和处理规则的描述；文档是为了便于了解程序所需的阐明性资料。程序必须装入机器内部才能工作，文档一般是给人看的，不一定装入机器”。
可以看到概念里提到了"文档"，说明写文档是软件开发过程必不可少的一个环节，如果文档没有写好，那么软件也不能算是优秀的软件。
可对于一般软件开发人员来讲，写代码要比写文字容易得多。很多时候我们都能看到类似的事情，项目做完了，设计文档还没有；当别人问起，某个功能当时为什么这么设计，一时语塞；项目代码里没有注释，时间长了，自己都忘记当时代码为什么要这么写；当接手别人的项目的时候，要排查个问题只能一行行读代码，唯一的文档就是随脚手架自动生成的 README.md。以上这些都是我们平时开发中可能会遇到的问题，为什么会这样？其实就是因为平时没有写文档的习惯，文字没有得以保留，只靠记忆，时间长了确实记不住。
下文就想和大家一起探讨一下，前端为什么写技术方案，怎么写前端技术方案。
写技术方案目的
在讲为什么要写前端方案文档前，先讲一个我的好朋友小明的故事。
小明也是一个前端，在接到需求的时候，他会大致看一下需求文档，感觉没有什么太大的问题，然后就看看交互、视觉稿上有哪些页面，接下来就开始迫不及待地写代码了。
新建一个文件、写模板、写样式、写交互逻辑，一气呵成。新模块的需求是小明最喜欢的，因为不用去理解其它功能的逻辑，可工作中还是少不了维护历史代码。小明很聪明，他发现有个功能加个参数传过去做个逻辑判断就能实现，于是他也就这么做了。
开发完后，小明觉得很满意，因为很快就实现了需求，代码在脑中的逻辑比较清晰，里面也许有些地方写的不太妥当，但是也无妨吧。虽然不是全局最优的，但可以说是局部最优的。
版本提测之后，QA 开始针对各种边界问题和极端场景给小明提 bug。譬如输入框输入 emoji 表情后提交接口报错、按钮连续点击触发了多次请求、买家角色页面展示正常但是供应商角色展示错误……
在改 bug 的过程中小明渐渐带上了痛苦面具，代码逻辑被改的支离破碎，不得不为代码打各种补丁，方法的参数加了一个又一个，逻辑里的条件判断加了又加。到这个时候小明的开发积极性已经被消磨的差不多了，开始对 QA 提出的 bug 表示质疑，他会用“原来就是这么设计的呀”、“这个问题不在这次的需求范围内”等等这样的说辞来避免对代码的更改。
过了一段时间，小明又接到一个需求，需要对上次开发的模块增加一些功能。翻开代码的时候，小明整个人都崩溃了。以前代码的逻辑自己早就忘记了，面对自己已经看不懂的代码，开始对自己进行灵魂拷问“这个方法有什么用？这个方法怎么有这么多参数？为什么逻辑这么复杂？”，“代码在不同页面之间跳来跳去，还有长得几乎一模一样的代码，他们的逻辑到底是什么样的？”，“为什么会有这么多标识位，这么多魔法数字，他们都是干嘛的？”。注释什么的是不存在的，即使存在，也不明白在讲些什么。
刚接手项目的时候小明还不断吐槽之前开发的人不写文档、不写注释，没过多久小明也成了别人口中的那个"他"。
以上故事根据真实事件改编。
我觉得写技术方案文档是能解决小明的一部分问题的，“谋定而后动，三思而后行”，都是在说这个道理。当然写文档也不是万能。对比一下后端，会发现他们在写代码之前都会做方案设计，好像难道后端的开发时间很充裕或者说前端的技术方案不值一提吗？肯定不是。方案设计是软件工程里的一个最佳实践，通常做技术方案的过程中会体现出软件整体的架构，当对核心流程梳理完成之后，最后基本都能落实到代码上。也就是说好的技术方案能体现出最后代码的逻辑，通过看方案就能知道代码怎么写。这样就防止了在写代码过程中边写边改，最后导致代码结构混乱的问题。
怎么写技术方案
如果我们按照后端那一套方法论和模板来做前端方案设计，发现根本写不出来什么内容，这时候我们要重新审视方案设计的套路，来发现前后端的不同。
业务模型可能前后端都是一致的，毕竟我们是解决同一个业务问题。但其中也有稍许差别，前端有些数据不是从后端获取的，或者说不一定非要从后端获取，这点我们需要在做设计的时候考虑进去。譬如同一个 H5 页面在微信公众号内和钉钉内需要展示不同的主题色。
前后端对于核心流程的定义也不同，对于后端来说核心流程是数据的产生、流转、消费，但是提到流程，在前端来说更多的是页面的流转、组件的交互、用户的操作。同样一件事情，在前后端来看完全是两个东西，比如保存一项数据，后端需要关注的可能是如何校验、如何存储、如何索引、如何关联。但前端要关注的却是校验接口的出入参、校验结果的展现形式如何、是跳转还是覆盖或者弹窗、不同屏幕和设备下如何适配。
后端更注重逻辑架构与部署图，因为后端需要为服务化，服务间边界的定义要非常清晰、具体。前端与微服务对应的，应该就是组件了，但是组件覆盖的范围太广，从一个按钮到一个页面都可以称之为组件，甚至现在比较火热的微前端中的一个子应用也可以成为一个组件，所以前端的组件需要被划分成页面、模块、控件等不同封装层次的单元。在这个划分的过程中，逻辑架构自然体现出来了。同时前后端解决的问题不同，导致关注点也不同，前端需要关注页面的还原，比如页面的元素应该如何抽象，样式应该如何复用，这个是后端不用考虑的。
接口可不仅仅是 http 请求，任何与其它模块交互逻辑都应该明确其入参和出参。后端需要关注暴露出去的 dubbo 或者 http 接口，因为这体现了系统间交互的逻辑。而对于前端来说对应的也应该明确独立模块或者页面之间的交互逻辑，所以也就需要明确这些"接口"。
关于实施方案，前后端的关注点也有稍许不同，后端更关心系统之间的集成，旧数据的兼容。而前端应该关心的是桌面设备和移动设备的区别，或者微信、支付宝等不同渠道的集成。
对比之后前端技术方案的脉络渐渐清晰起来。结合上面的方法论，下面就实际案例讲解一下。
技术方案的案例
在政采云产研团队的研发流程中，前端方案设计是在需求和交互评审之后、测试评审和正式开发之前，属于需求阶段和开发阶段的中间节点。此时需求的功能和用户交互场景基本已经确定，前后端技术方案之间互相补充描述清楚需求的可行性、整体架构和具体实现。同时在测试分析之前，也是帮助 QA 梳理测试重点和用例场景。
第一章，概述。 一般会简单描述项目的背景和价值，做一件事情的意义或者说动机是很重要的，一般从需求文档里进行概括即可。然后解释后面文档中需要用到的一些专有名词，达成大家对一些名词的共识是很重要的。
第二章，相关文档。 收集版本开发的相关文档，这样开发的时候只要通过这一个前端技术方案文档，就能找到所有的文档，有时候我也会把这些网页整理到一个浏览器书签文件夹里。
第三章，任务拆解。 主要描述开发任务归属、预计工时，还有里程碑。
估时是按照页面维度，拆分页面内主要功能，进行时间估算，时间估算按照静态 demo 和 JS 交互来分别评估会准一些。之后得出时间乘以一个 1.3 的系数（因为每周还会有不同的会议、沟通也会占用时间）。
时间评估的时候，像下图一样，本地花点时间列一下 —— 这样的好处是一便于统计和比对，看有无遗漏；二评估出的时间，给到业务方、PM 等，会对我们有职业化上的认可——会认为这样的评估粒度，时间是准确的你这个人是靠谱的；另外，细粒度的维度，也便于业务方寻找需求最长路径，看需求或者走迭代也方便做出判断。
第四章，总体设计。 列举开发规范，还有逻辑架构。一图胜千言，有关时序的逻辑强烈建议用图来代替。流程图、时序图、状态图，让你的技术方案文档逼格满满清晰明了。
下图为页面跳转逻辑图，如果交互有缺失的话，前端技术方案里可以进行补位
第五章，详细设计。 这一章就是整篇技术方案的重点了，包括功能说明、流程说明、模块详细设计、外部依赖等四个小节。
最完美的状态，就是如下图所示，这一部分写完了，代码也跃然于纸上了。
也可以适量地贴一些代码，可以很好地在技术分析的时候阐述清楚改动点
下图为下单流程卡券选择时序图。复杂的时序逻辑已经不是文字能说的清的了，时序图让交互更清晰
下图为前端组件入参设计的案例，开源组件库写的都不错，可以直接参考。
最后三章可以写一写技术分析 Checklist、测试数据、遗留问题
最后附上政采云前端团队的前端技术方案模板，戳这里 (https://staging-gov-open-doc.oss-cn-north-2-gov-1.aliyuncs.com/1072PT/339900/10006126128/202110/dfa4e4a2-8b3c-4372-b002-9d6f701d5f40)。当然大家也可以根据自己的情况进行内容的增删，譬如我们原本是在技术方案里维护发布的 CheckList，但是后端也维护了一个，我们就索性建了一个公用的文档，归档在一起。
最后的最后推荐两个好用的画图工具：
- plantuml (https://plantuml.com/zh)：使用简单的文字描述画 UML 图
- drawio (https://www.draw.io)：在线图标绘制网站 上面两个工具都有对应的 vscode 扩展。(processon (https://www.processon.com) 也挺好用的，可惜免费版只能存 9 个图表)
总结
首先得承认一个事实，写文档和写作一样是一件很费时费力的事情，为了画一个流程图、为了斟酌一个词语，可能就会纠结好久。其次文档是需要持续更新的，不是技术评审开完就封版了，视觉评审、测试分析评审、后续迭代都有可能影响技术方案，需要实时跟进。如果能把产品各个版本的技术方案文档进行整合，甚至能得到整个产品技术方案的全貌。
欲速则不达，很多人觉得技术方案是在延长开发周期，其实在政采云的落地过程中发现，技术方案设计的越详细，对质量提升，和维护成本降低效果明显，拉开很长周期来看，是加快了迭代周期。
李开复老师在《浪潮之巅》的序言中说到：“我认识很多顶尖的工程师，但具备强大叙事能力的优秀工程师，我认识的可以说是凤毛麟角”。表达是软件开发工程师重要的软实力之一，作为软件工程的最佳实践，方案设计在前端开发过程中还是十分必要的，那么为什么前端领域长时间不注重这个事情呢，我觉得有以下原因：
- 方案设计依赖技术能力，而前端技术栈变化太快，今天的设计套路放在明天可能就失效了；
- 前端业务变化太快，经过半年的迭代之后，可能第一版的方案就反应不出现有代码逻辑了；
- 前端的业务流程、交互流程比后端复杂太多，而且可复用性差，需要花费大量时间去思考和整理，而且对抽象能力有比较高的要求；
- 前端开发效率高，不会有历史包袱，有时候直接重写的效率反而更高；
- 后端上在语言和
IDE对重构的支持远比前端好太多； - 后端比较成熟了，比如常见的
mvc分层都几乎是约定了，前端要不要model层，要不要service层都是要讨论的，要不要redux，redux存什么数据，每个人的理解不一样的； - 前端人员的抽象思维和工程化能力总体还是比后端弱的；但是这些原因其实都不是我们不做方案设计的理由，方案设计是个结构化思维的过程，他不光是能让项目更好执行，也能提升开发者本身的架构能力和宏观意识。我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。如果我们只是会写程序，不会在文档中恰当且优雅地描述自己的想法，那么就真正的成为“码农”了。
所以，同学们在平时开发的时候多想一想如何做设计吧。
后续预告
技术方案有一部分功能实现是和后端一起制定的，每个人制定的前后端技术方案是否合理是不统一的，有没有更好的最佳实践呢？经过长期的实践和总结，政采云制定了前后端技术方案约定，示例如下，尽请期待。
