如何用文档记录软件架构

890 阅读3分钟

我们经常需要向团队里的新人、一起合作的同事、应用负责人等解释应用软件是如何工作的,那么如何才能清晰的阐述整个应用是如何构建并工作的呢?

UML(Unified Modeling Language)

UML通过使用图表的形式来展现软件组件。主要可以分成两大类:

  • 行为UML图表
  • 结构UML图表

下方示例并不是完整的各种图表类别,仅选了几种我认为常用的形式

行为UML - 活动图表

对一个活动和另一个活动之间的协作进行建模,可以看做是流程图的更高版本。 比如可以通过加上泳道来描述销售去会见新客户的一些逻辑

image.png

详见活动图表解释

行为UML - 状态机图表

实体的行为不仅依赖于输入,而且和之前的状态有关。比如订单配送状态机

image.png

详见状态机图表

行为UML - 序列图和通信图

以读书逾期为例,可以分别用序列图和通信图来做如下陈述:
序列图:用来阐述对象之间的协作通信

image.png

详见序列图

通信图:用来展示对象之间是如何进行通信的

image.png

详见通信图

通信图 vs 序列图:二者语义上是一样的,都展示的是一样的信息,不同的是序列图的图表是按照时间进行陈列,而通信图是按照空间

结构UML - 类图表

类图表用图表来阐述面向对象系统类、属性、方法、对象之间的关系。比如订单系统的类图可能是这样的:

image.png

详见类图

结构UML - 组件图表

组件图将整个系统分解成各种高层次的抽象(功能),每个组件在系统中都负责一个确定的事情。一个订单的组件可能就是这样

image.png

详见组件图

不恰当的使用UML可能带来的问题

当系统描述过于庞大,可能可读性就会不太好

image.png

4+1 视图模型

image.png

  • 逻辑视图(Logical View):主要关注点在功能上,它提供了那些功能,代码是如何设计来支持这些功能的;
  • 开发视图(Development View):主要关注点在代码的组织结构上,比如:模块、模型、包;
  • 运行视图(Process View):主要关注系统运行时的情况,比如:通信、并发、性能等;
  • 物理视图(Physical View): 主要关注代码运行所在硬件情况,比如:拓扑结构;
  • 场景(Scenarios/用例):主要通过几个用例来帮助解释架构;

可以通过这个下图来看到更细节4+1视图模型 image.png 详见4+1视图

C4模型

使用4种不同的粒度的层级来描写软件架构,从最顶层放大可以看到“里层”的实现细节,根据诉求对应到相应层级即可

image.png

可以想象看地图的场景,最大级别是可以看到亚洲国家,然后缩放能看到省,依次可以看到更细节的东西,这就是C4的基本思路

  • 系统上下文图:最粗的粒度,表达系统与用户以及其它系统的关系,在大多数情况下,一个系统被一个开发团队独享;
  • 容器图:容器代表一个应用或者数据存储,每一个容器都是可以独立部署运行的;
  • 组件图:通过一个良好接口封装的所有功能的组合,在C4模型中,它是不可单独部署的单元;
  • 代码:展示组件是如何通过代码来实现的;

详见c4模型官网用于软件架构的 C4 模型Simon Brown的C4分享

架构决策记录(ADR Architecture Decision Records)

以日志的形式记录下来当时选择这种架构的原因。可以自行拟定这个日志的格式,或参考github ADR说明

参考

documenting-software-architecture