如何画出一张优秀的软件文档视图

2023-10-27

技术传播的价值,不仅仅体现在通过商业化产品和开源项目来缩短我们构建应用的路径。加速业务的上线速率,也体现在优秀工程师的工作效率提升、产品性能优化和用户体验改善等经验方面的分享,以提高我们的专业能力。

接下来,阿里巴巴技术专家三画,将分享自己和团队在画好架构图方面的理念和经验,希望对你有所帮助。

当我们想用一张或几张图来描述我们的系统时,是不是经常遇到以下情况:

  • 对着画布无从下手、删了又来
  • 如何用一张图描述我的系统,并且让产品、运营、开发都能看明白
  • 画了一半的图还不清楚受众是谁
  • 画出来的图到底是产品图功能图还是技术图又或是大杂烩
  • 图上的框框有点少是不是要找点儿框框加进来
  • 布局怎么画都不满意……

如果有同样的困惑,本文将介绍一种画图的方法论,来让架构图更清晰。

先厘清一些基础概念

什么是架构?

架构就是对系统中的实体以及实体之间的关系所进行的抽象描述,是一系列的决策。

架构是结构和愿景。系统架构是概念的体现,是对物/信息的功能与形式元素之间的对应情况所做的分配,是对元素之间的关系以及元素同周边环境之间的关系所做的定义。

做好架构是个复杂的任务,也是个很大的话题,本篇就不做深入了。有了架构之后,就需要让干系人理解、遵循相关决策。

什么是架构图?

系统架构图是为了抽象地表示软件系统的整体轮廓和各个组件之间的相互关系和约束边界,以及软件系统的物理部署和软件系统的演进方向的整体视图。

架构图的作用

一图胜千言。要让干系人理解、遵循架构决策,就需要把架构信息传递出去。架构图就是一个很好的载体。

那么,画架构图是为了:

  • 解决沟通障碍
  • 达成共识
  • 减少歧义

架构图分类

搜集了很多资料,分类有很多,有一种比较流行的是 4+1 视图,分别为场景视图、逻辑视图、物理视图、处理流程视图和开发视图。

1.、场景视图

场景视图用于描述系统的参与者与功能用例间的关系,反映系统的最终需求和交互设计,通常由用例图表示。

2、逻辑视图

逻辑视图用于描述系统软件功能拆解后的组件关系,组件约束和边界,反映系统整体组成与系统如何构建的过程,通常由 UML 的组件图和类图来表示。

3、物理视图

物理视图用于描述系统软件到物理硬件的映射关系,反映出系统的组件是如何部署到一组可计算机器节点上,用于指导软件系统的部署实施过程。

4、处理流程视图

处理流程视图用于描述系统软件组件之间的通信时序,数据的输入输出,反映系统的功能流程与数据流程,通常由时序图和流程图表示。

5、开发视图

开发视图用于描述系统的模块划分和组成,以及细化到内部包的组成设计,服务于开发人员,反映系统开发实施过程。

以上 5 种架构视图从不同角度表示一个软件系统的不同特征,组合到一起作为架构蓝图描述系统架构。

怎样的架构图是好的架构图

上面的分类是前人的经验总结,图也是从网上摘来的,那么这些图画的好不好呢?是不是我们要依葫芦画瓢去画这样一些图?

先不去管这些图好不好,我们通过对这些图的分类以及作用,思考了一下,总结下来。

我们认为,在画出一个好的架构图之前, 首先应该要明确其受众,再想清楚要给他们传递什么信息。

所以,不要为了画一个物理视图去画物理视图,为了画一个逻辑视图去画逻辑视图,而应该根据受众的不同,传递的信息的不同,用图准确地表达出来,最后的图可能就是在这样一些分类里。

那么,画出的图好不好的一个直接标准就是:受众有没有准确接收到想传递的信息。

明确这两点之后,从受众角度来说,一个好的架构图是不需要解释的,它应该是自描述的,并且要具备一致性和足够的准确性,能够与代码相呼应。

画架构图遇到的常见问题

方框代表什么?

为什么适用方框而不是圆形,它有什么特殊的含义吗?随意使用方框或者其他形状可能会引起混淆。

虚线、实线什么意思?箭头什么意思?颜色什么意思?

随意使用线条或者箭头可能会引起误会。

运行时与编译时冲突?层级冲突?

架构是一项复杂的工作,只使用单个图表来表示架构很容易造成莫名其妙的语义混乱。

本文推荐的画图方法

C4 模型使用容器(应用程序、数据存储、微服务等)、组件和代码来描述一个软件系统的静态结构。

这几种图比较容易画,也给出了画图要点,但最关键的是,我们认为,它明确指出了每种图可能的受众以及意义。

下面的案例来自 C4 官网,然后加上了一些我们的理解,来看看如何更好的表达软件架构。

语境图(System Context Diagram)

这是一个想象的待建设的互联网银行系统,它使用外部的大型机银行系统存取客户账户、交易信息,通过外部电邮系统给客户发邮件。

可以看到,非常简单、清晰,相信不需要解释,都看的明白,里面包含了需要建设的系统本身,系统的客户,和这个系统有交互的周边系统。

这样一个简单的图,可以告诉我们,要构建的系统是什么;它的用户是谁,谁会用它,它要如何融入已有的 IT 环境。

这个图的受众可以是开发团队的内部人员、外部的技术或非技术人员。即:

  • 构建的系统是什么
  • 谁会用它
  • 如何融入已有的 IT 环境

怎么画?中间是自己的系统,周围是用户和其他与之相互作用的系统。这个图的关键就是梳理清楚待建设系统的用户和高层次的依赖,梳理清楚了画下来只需要几分钟时间。

容器图(Container Diagram)

容器图是把语境图里待建设的系统做了一个展开。

上图中,除了用户和外围系统,要建设的系统包括一个基于 Java\Spring MVC的 Web 应用提供系统的功能入口,基于 Xamarin 架构的手机 App 提供手机端的功能入口,一个基于 Java 的 API 应用提供服务,一个 MySQL 数据库用于存储,各个应用之间的交互都在箭头线上写明了。

看这张图的时候,不会去关注到图中是直角方框还是圆角方框,不会关注是实线箭头还是虚线箭头,甚至箭头的指向也没有引起太多注意。

我们有许多的画图方式,都对框、线的含义做了定义,这就需要画图的人和看图的人都清晰的理解这些定义,才能读全图里的信息。

而现实是,这往往是非常高的一个要求,所以,很多图只能看个大概的含义。

这个图的受众可以是团队内部或外部的开发人员,也可以是运维人员。用途可以罗列为:

  • 展现了软件系统的整体形态。
  • 体现了高层次的技术决策。
  • 系统中的职责是如何分布的,容器间是如何交互的。
  • 告诉开发者在哪里写代码。

怎么画?用一个框图来表示,内部可能包括名称、技术选择、职责,以及这些框图之间的交互,如果涉及外部系统,最好明确边界。

组件图(Component Diagram)

组件图是把某个容器进行展开,描述其内部的模块。

这个图主要是给内部开发人员看的,怎么去做代码的组织和构建。其用途有:

  • 描述了系统由哪些组件/服务组成
  • 厘清了组件之间的关系和依赖
  • 为软件开发如何分解交付提供了框架

类图(Code/Class Diagram)

这个图很显然是给技术人员看的,比较常见,就不详细介绍了。

案例分享

下面是内部的一个实时数据工具的架构图。作为一个应该自描述的架构图,这里不多做解释了。如果有看不明白的,那肯定是还画的不够好。

画好架构图可能有许多方法论,本篇主要介绍了 C4 这种方法,C4 的理论也是不断进化的。

但不论是哪种画图方法论,我们回到画图初衷,是为了更好的交流,我们在画的过程中不必被条条框框所限制。简而言之,画之前想好:画图给谁看,看什么,怎么样不解释就看懂。

画图的工具有:

  • Keynote
  • Xmind
  • EdrawMax
  • Visio
  • OmniGraffle
  • Process On
  • ……

文中物理视图 Download 地址:

作者介绍:三画,曾多年从事工作流引擎研发工作,现专注于高并发移动互联网应用的架构和开发。阿里巴巴技术专家,梓敬、鹏升和余乐对此文亦有贡献。

本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)

如何画出一张优秀的软件文档视图 的相关文章

  • 数据清洗和特征选择

    数据清洗和特征选择 数据清洗和特征挖掘的工作是在灰色框中框出的部分 即 数据清洗 gt 特征 标注数据生成 gt 模型学习 gt 模型应用 中的前两个步骤 灰色框中蓝色箭头对应的是离线处理部分 主要工作是 从原始数据 如文本 图像或者应用数

随机推荐

  • File格式转换MultipartFile格式的四种方式例子

    可以看到MultipartFile是个接口 转成MultipartFile格式则需要转成实现MultipartFile接口的实现类即可 如下选择转成用MockMultipartFile实现 首先 需要先引入依赖包
  • 链表常用函数总结

    创建单链表 PNODE creat list int len int i int val PNODE pHead NULL pHead PNODE malloc sizeof NODE if NULL pHead printf 分配内存失败
  • 电子计算机是采用什么进制法,计算机内部使用什么进制

    计算机内部采用二进制来表示信息 cpu的位是指一次性可处理的数据量是多少 1字节 8位 32位处理器可以一次性处理4个字节的数据量 也就是32位二进制 二进制是计算技术中广泛采用的一种数制 二进制数据是用0和1两个数码来表示的数 拓展资料
  • QT+OpenGL——GLFW编译配置

    环境 Qt5 8 0 VS2015 1 下载glfw源码 地址 https www glfw org download html 2 下载cmake工具 地址 http www cmake org cmake resources softw
  • Linux查看硬盘挂载

    目录 1 查看磁盘情况是否挂载上 2 在指定的硬盘上创建分区 3 设置开机自动挂载分区 1 查看磁盘情况是否挂载上 df h 该命令会显示出挂载磁盘和挂载点 下图分别是系统盘 以及挂载的一个硬盘 dev sda1 若某个磁盘没有挂载上 可以
  • WEBSHELL管理工具流量特征——基础篇

    前言 前一阵子帮别人做取证题目 有很多关于WEBSHELL的流量要分析 想起来还有没好好分析过于是准备写篇文章总结一下帮助大家能够快速的辨别WEBSHELL流量 下面我们展开文章来讲 中国菜刀 这个应该是大家最熟悉的WEBSHELL管理工具
  • 库存系统难破题?且看京东到家如何破

    京东到家库存系统架构设计 目前 京东到家库存系统经历两年多的线上考验与技术迭代 现服务着万级商家十万级店铺的规模 需求的变更与技术演进 我们是如何做到系统的稳定性与高可用呢 下面将会给你揭晓答案 库存系统技术架构图 上图如果进行总结下 主要
  • 《Windows server 2019操作系统》搭建各种服务器综合运用

    搭建域服务器 要求主域名为wgzj com IP地址为192 168 1 200 主机名为sever 搭建DNS服务器 并创建正向查找区域和反向查找区域 搭建FTP服务器 主目录为C wwwroot 搭建Web服务器 主目录为C wwwro
  • 单点登录的简单实现

    1 什么是单点登陆 单点登录 Single Sign On 简称为 SSO 是目前比较流行的企业业务整合的解决方案之一 SSO的定义是在多个应用系统中 用户只需要登录一次就可以访问所有相互信任的应用系统 较大的企业内部 一般都有很多的业务支
  • 机器学习——高斯朴素贝叶斯 Gaussian naive bayes

    问 高斯朴素贝叶斯假设离散特征的取值符合高斯分布 答 错误 高斯朴素贝叶斯假设连续特征的取值符合高斯分布 而不是离散特征 对于离散特征 通常使用多项式朴素贝叶斯或伯努利朴素贝叶斯进行分类 在 sklearn 库中 基于贝叶斯定理的算法集中在
  • win10 自带的远程桌面控制 ubuntu,不是补全

    win10 远程桌面控制ubuntu tab 不能补全 的解决方案 默认 tab 是窗口切换功能 方法有两个 在ubuntu中或者远程桌面中 编辑 config xfce4 xfconf xfce perchannel xml xfce4
  • TCP/IP详解学习笔记1

    为什么会有TCP IP协议 在世界上各地 各种各样的电脑运行着各自不同的操作系统为大家服务 这些电脑在表达同一种信息的时候所使用的方法是千差万别 就好像圣经中上帝打乱了各地人的口音 让他们无法合作一样 计算机使用者意识到 计算机只是单兵作战
  • mciSendString的介绍

    转载至 http blog sina com cn s blog 149e9d2ec0102wzcn html 使用MCI API 源文件中需要包含头文件Mmsystem h 在Project gt Settings gt Link gt
  • Windows 10 自带录制工具

    从知乎上学来的 Windows 10上自带的游戏录制工具 按Win G呼出 可录制游戏和任何一个桌面程序 可以截屏 不能控制录制的质量 录制出来的视频大小适中 只能录制一个程序 切换程序会导致录制停止 输出格式是mp4 视频编码H 264
  • sqlplus连接、登录命令大全(选择实例登录、连接远程数据库实例等等)

    1 默认实例登录 sqlplus username password 如 sqlplus tas yn tas yn 2 选择实例登录 sqlplus username password net service name 如 sqlplus
  • vue 获取微信定位经纬度,并调用高德地图解析出详细地址

    第一步 安装weixin js sdk 命令 npm i S weixin js sdk 或者 npm install weixin js sdk 第二步 在需要的地方引用 import wx from weixin js sdk 第三步
  • 《C和指针》笔记27:递归

    递归所需要的两个特性 存在限制条件 当符合这个条件时递归便不再继续 每次递归调用之后越来越接近这个限制条件 这里没有用计算阶乘和菲波那契数列的例子说明递归 作者指出前者递归并没有提供任何优越之处 而后者效率之低是非常恐怖的 下面程序的目的是
  • matlab中more_sols,薛定宇教授大讲堂(卷Ⅳ):MATLAB最优化计算最新章节_薛定宇著_掌阅小说网...

    2 4 联立方程组的精确求解 前面介绍过 利用图解方法只能求出给定方程的实数根 并不能求出方程的复数根 具体例子可以参见例2 12 另外 如果联立方程有多个实数根 则只能用图形方法绘制出根所在的位置 并不能直接得出根的具体值 需要逐个根进行
  • Java 获取文件Jar包中读取文件

    本文介绍java多种方式从classpath url以及jar中读取文件 文章目录 各种路径获取方式 IDEA中输出的结果 执行JAR包所输出的结果 外部类读取Jar包中的配置文件 判断 是class文件执行还是jar文件执行 各种路径获取
  • 如何画出一张优秀的软件文档视图

    技术传播的价值 不仅仅体现在通过商业化产品和开源项目来缩短我们构建应用的路径 加速业务的上线速率 也体现在优秀工程师的工作效率提升 产品性能优化和用户体验改善等经验方面的分享 以提高我们的专业能力 接下来 阿里巴巴技术专家三画 将分享自己和