Java互联网科技Java 杂谈

互联网架构实践心得S1E9：架构评审一百问和设计文档五要素

2019-05-14  本文已影响2人  Java_苏先生

本文我会来说说我认为架构评审中应该看的一些点，以及我写设计文档的一些心得。助你在架构评审中过五关斩六将，助你写出能让人收藏点赞的设计文档。

技术架构评审一百问

架构评审或技术方案评审的价值在于集众人的力量大家一起来分析看看方案里是否有坑，方案上线后是否会遇到不可逾越的重大技术问题，提前尽可能把一些事情先考虑到提出质疑其实对项目的健康发展有很大的好处。很多公司都有架构评审委员会都有架构评审的流程，做业务的兄弟要么看到这个流程往往心惊胆战害怕自己做的方案被毙了咋整，要么就是认为这是一种过场，随便糊弄一点文档发给委员会看一下就算过去了。我做过架构评审委员也做过提交评审方案的业务兄弟，不管哪个角色我都不害怕而是喜欢这一流程，评审这个事情做的好其实可以很享受，大家都是一起学习的过程，不存在谁为难谁。下面说说我觉得架构评审（非代码评审）中看重的需要评审的一些点。

组件选型

组件特别是存储组件选型挺重要的，真心建议事先可以有那么几周的时间搭一个高可用的集群，使用接近于真实的数据对组件进行压测（你看之前我博客上的Mongodb的压测文章停火的，说明很多人没有这个时间和条件对一些组件进行压测）。眼见为实耳听为虚，自己通过压测对比一下自己得出的数据和公开的数据是否有差异，如果有的话说不定还能发现自己使用上的一些问题。尽量还是选用使用的人多的开源组件吧，出了问题至少Patch不会来的太慢。

性能

对于重要的项目，建议做一下整体压测，没有经过压测得出来的估计的结论往往可能是错的，我们总以为最终会死在最后的存储上，但是很可能早早就死在了程序的低级错误上，比如在一些存储组件的Client使用上，如果没把控好最佳实践（把应该作为单例使用Clinet每次都去创建一次，默认的线程数小的可怜应该重新配置但是保留了默认值），死的非常难看。

可伸缩性

灵活性

可扩展性

可靠性

安全性

兼容性

弹性处理

事务性

可测试性

可运维性

监控

看了这么多问题可能会觉得这架构设计是没法做了，其实不同阶段的项目有不同的目标，我们不会在项目起步的时候做99.99%的可用性支持百万QPS的架构，高效完成项目的业务目标也是架构考虑的因素之一。而且随着项目的发展，随着公司中间件和容器的标准化，很多架构的工作被标准化替代，业务代码需要考虑架构方面伸缩性运维性等等的需求越来越少，慢慢的这些工作都能由架构和运维团队来接。一开始的时候我们可以花一点时间来考虑这些问题，但是不是所有的问题都需要有最终的方案。

技术设计文档五要素

如果你在Google搜索架构设计文档、技术设计文档、概要设计文档可以搜索到很多模板，很多公司也会以这些模板作为设计文档的模板来让大家填写。对于大部分所谓的项目只是一个项目中的一个小环节是一个具体的业务逻辑，因此总是可以看到大家写的所谓的技术设计文档只能填满文档的20%，其余都不知道怎么写。当你不知道文档应该写哪些内容的时候可以这么来考虑问题，就是你这个项目接下去是要卖给别人来用的，你没有机会当面和他把这个项目说清楚，你只能通过文档来把事情写清楚，别人就给你一次机会，如果看不懂你文档表达的意思，不能理解你的项目，你的项目就卖不出去不值钱，这个时候你一定会从各个角度来剖析你的系统想尽一切办法来把事情说清楚，用这个方法逼一下自己的，你的文档会很优秀。接下去我想说一下如果是我的话我看重技术设计的哪些部分以及这些部分的文档的写作方式，这些内容构成了一个必要的（概要）设计文档，算是抛砖引玉。

交代背景和需求全貌

在这里，推荐使用脑图在技术角度给出一下自己理解的项目需求的分布。PRD中的产品功能脑图可以和这里技术角度的脑图有差异，在说清楚需求的同时侧重技术层面，体现在：

看了这个图基本产品需求就可以理解个大概，具体的细节规则可以进一步参考PRD。

系统架构图

在本系列文章的第二到第五篇中，我都配了一个架构图。架构图需要传递清楚下面的信息：

UML里会有一些具体的分类，什么类图、组件图、部署图等等，我觉得不必拘泥于这些细节，通过线线框框的架构图能把模块和模块之间的关系表述请求，然后再配以一定的文字来说明每一个组件即可。我自己常用的是gliffy，只要能说清楚，Word画也可以。根据项目的大小，图上的模块不一定是需要独立部署的进程，模块也可以是项目内部的一个模块或类。对于复杂的项目，要画一个图说清楚很难，可以画一个大的架构图，然后针对每一个模块或流程再细化画不同层次的图。

对外API定义

API的详细定义可以由Swagger UI、Spring REST Doc、Miredot等等工具生成，这些生成的接口是按照代码来组织层次关系的，只能体现接口的参数定义不能体现接口的形态等，是没有思想的，不适合用来阅读，只适合用来参考。因此还是建议做一个脑图来总体阐述一下接口的：

图上可以不显示出参数清单，但可以以简单的文字来描述重要参数，比如下单接口：->@用户身份，优惠券ID，[{商品ID,数量}]<-订单号，下单结果（0-失败，1-成功）。（->代表输入，<-代表输出，[]代表数组，@代表隐式参数，代表可空参数等等）。

之前强调过好多次涉及到和外部交互的API是设计中非常重要的一个环节，不仅仅体现了系统对外输出的能力，也体现了系统设计在安全性、复用性、封装等方面的平衡。

交互时序

时序图的表达非常重要，可以表现需求脑图、架构图和API脑图无法表现出来的几个方面，清晰展现了某个事情：

我觉得能在比较高的层面说一下技术（对接）流程即可，不一定要详细到类和类之间的交互，类和类之间的交互阅读代码或直接看全链路调用的图就可以。如果项目有多个合作方多个依赖方，项目流程比较复杂，那么序列图是能把这个事情说清楚的最好的方式。

对于这种时序图，采用传统的工具来画费时费力，推荐下面两个工具（https://www.websequencediagrams.com/和http://plantuml.com/sequence-diagram），可以在几分钟内生成需要的图。

我们输入类似的文字：

title 合作流程

用户->XX:投资YY标的

XX->YY:同步投资情况，更新可用额度

用户->YY:在额度内消费

YY->XX:同步消费情况，更新可用额度，更新回款计划

YY->XX:还款

XX->用户:回款（已消费部分作为手续费给XX）

opt 线下流程

XX->YY:对于YY用户的消费出账单

YY->XX:对账确认账单

XX->YY:打款开具发票

End

网站生成类似的时序图，还可以自由选择自己喜欢的样式：

数据库ER

ER图就是实体联系图。形式上我们可以在图上表现几个点：

在有的时候我们可以省略属性的类型定义，甚至可以直接省略具体的属性（实体名和M对N的关系是必须的），把图简化为类似下面的部分：

ER图的信息量非常大，绝对不是粘贴一下表结构的DDL可以替代的，原因是：

比如下图，是否一眼就可以看明白一套P2P金融业务整个数据结构的架构呢：

（随便画的图，不代表任何意义，请不要以这个图做P2P的表结构设计）

所有的图，文字只是一个维度，我们要学会利用边框类型（矩形、圆角矩形），边框样式（虚线，实线），填充色，文字颜色，关联线条粗细颜色样式，框内ICON来增加我们要表现信息的维度，最多可以增加到6维+，这种能力是文字很难实现的。一图胜过千言，所以我一直认为图是设计文档中非常重要的部分。

其它

之前我说了我们可以以五图的形式（需求脑图、架构图、API脑图、序列图、数据库ER图）把系统大概介绍一个底朝天，说清楚了需求、架构、对外接口、交互流程和数据结构设计这几个事情，业务项目说清楚这些足够了。

对于偏向于中间件（不管是基础中间件还是业务中间件，中台）的项目（而不是业务项目），这里我再补充几个重要的方面，需要在设计文档中有体现：

这些点我就不一一展开说了，在第一节说架构评审的时候都有提到过，针对那些问题写一下自己的设计是怎么应对的吧。

这些点我认为可以构成一个合格的设计文档，文档的形式不重要，重要的是可以把业务的技术实现梳理清楚，确保我们在开发之前有一个清晰的思路，在开发上线后，文档也是一个后人熟悉系统的非常重要的手段。你可能会提出疑问说这样的设计文档是不是太粗略了一点，完全没有体现到软件层面设计的细节，没错是这样，但是我一直说的是互联网架构心得，敢问现在互联网项目从0开始的大项目1到2个月上线，大的版本迭代2周一次，如果设计的时间是五分之一的话，设计也就是2天到一周这样子，我们有多少时间和能力来细化文档呢，如果能把我这里说的五要素都做好，对于互联网项目已经笑死。

还有一点往往会比较可惜，我们或许可以做到在开发之前有一个概要设计文档的产出，但是我们很难做到在系统上线后随着迭代还能继续维护第一版产品上线时那个大而全的文档。随着产品的迭代，我们的技术文档也像PRD迭代文档一样只说这次迭代的技术改动的话，这种设计文档因为没有全局观意义不大。对于这个情况，我觉得对于每一条业务线的产品，我都建议我们至少能维护大而全的下面这些文档的全量版本：

定期回顾一下这五个文档，根据最近的需求改改，可能也只需要花费几小时的时间，对于大项目其意义往往是新人的灵魂导师（之前我有画过一个比较复杂系统的架构图，这个架构图我看到有人做了桌面）。

写在最后

点关注，不迷路，每天跟新Java相关技术及资讯

上一篇下一篇

猜你喜欢

热点阅读