谈一份技术设计文档中应该出现的图

谈一份技术设计文档中应该出现的图

前言

最近在听过李智慧老师的课，正好在讲一份技术架构文档如何编写，觉得李老师说的很清晰也很明白。我们今天就再次对此话题进行一番讨论。只求能更详细的说明问题，技术的路的没有尽头，也希望大家多加指，大家一起进步。

浅谈做软件架构

正如李老师所说，一切皆可以用架构来概述。要想做好一件事情，在最开始一定是有一个合理的架构规划。从软件开发的早期，开发人员使用传统的瀑布开发模型，开发拿到需求之后按部就班缺少规划，越到后面发现每一个阶段的开展都需要依赖上一步骤的成果才能进行，软件开发过程中的变数很多，越到最后越发现这样没有规划的工作会很难做好一件事情。到后来，人们对合作方式和项目架构加以改进，不同的情况就去使用不同的战略战术，比如什么场景使用什么样的项目合作方式才能更好的得到结果。如果一个团队的能力平均，那这个团队做到民主制程序员组更容易成功。若这个团队某个人的能力更突出，可能主程序组合作方式更有效率。复杂的情况，可能现代的程序员组更好。这一切组合都来自于对实际情况的认真思考。事情都需要提前做好规划，生活需要有架构。

进入正题

4+1 视图模型

引自：https://www.ibm.com/developerworks/cn/rational/r-4p1-view/index.html

我们常听说4+1软件视图，它基本能涵盖我们所有的软件架构设计，我们不做4+1背景介绍了，我们只来提炼一些精髓，方便我们架构文档的设计。

软件架构涉及到抽象、分解和组合、风格和美学

大神总有如上说，也确实说的好。软件架构是一些元素、形式、关系/约束的组合。软件架构 ＝ {元素，形式，关系/约束}
4个视图指的是：

• 逻辑视图
• 过程视图
• 物理视图
• 开发视图
  最后用一些场景或约束来贯穿整体，从而形成5个视图。
  下图为4+1视图对应我们软件工程中各角色各阶段的分工产物，总结的很清晰到位。
  

部署图

正式规划一个项目文档，在描述清楚一些技术或非技术需求后，最先开始需要着手的就是部署图。部署图可以体现对整体架构的规划，部署图需要体现出节点或组件间的依赖关系。通过部署图，可以了解到整体项目的规划部署，从而对整体架构有一个宏观的认识。

组件图

组件图体现出对系统内部的一个微观架构的规划。一个架构可以分为宏观视角和微观视角，如果说部署图体现的是架构的宏观视角，那么组件图更多体现的是架构的微观视角，更多的是体现在一个服务内部的组件规划。一个系统的组件规划，也更适合出现在整体架构的开始，例如架构部署图后紧接着就是组件规划图。

序列图/时序图

序列图是表示时序活动的一种图，可以用来描述系统间的时序关系、组件间的时序关系或是接口之间的时序调用关系。序列图适合出现在一个软件设计文档的各个地方，如果需要体现不同系统之间的调用关系，比如一个商城交易服务，会涉及到支付、库存、物流、订单等不同系统服务，那么时序图就可以体现他们之间的调用关系或是返回结果。如果是一个系统内部组件之间的调用，那么时序图就应该出现在组件设计部分，用来体现组件间的调用关系。如果是接口调用，那么时序图更应该体现接口之间的交互信息。

用例图

用例图其实更适合于需求分析阶段，以不同的角色去定位不同场景的用例关系。在一份软件设计文档中，更多的细节是针对不同的场景去设计具体的实现， 这时候用例图就可以体现一个场景规划的作用，让读者更容易明白该模块设计的意图。

活动图/状态图

活动图和状态图既适合于某个场景内部的设计中，也可以出现在整体规划开始，让人一眼就看明白系统的活动状态。

• 活动图
  
• 状态图
  

类图

类图在UML中是最具体最详细的设计体现了，所以一般也只会出现在技术详细设计中，开发人员基本可以按照此进行编码开发了。类图可以出现在组件设计模块，用来体现某一组件具体的落地实现。

其他图

一份合格的技术设计文档中，大体包括以上设计图来表达一份技术描述通常已经足够了。我们大部分都是喜欢看图胜过看文字或是语音，在图形之外，我们可以结合场景用一些文字来辅助描述，正好起到点睛之笔了。
在上面提到的设计图外，我们更多还会用很多图，例如

• ER图
• 流程图
• 泳道图
• HIPO图
• 结构图
• 等等
  其实仔细看，这只是UML中组件图或活动图或状态图的变形了。具体用哪种图才能说明场景问题，也需要看我们不同的使用场景了。

最后的建议

技术文档如何才能做到条理清晰，和架构师的叙事逻辑也有很大的关系。比如我们的故事是倒序还是正序，结构采用总分还是分总，也是值得我们考虑的事情。