如何用文档记录软件架构

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

UML(Unified Modeling Language)

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

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

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

行为UML - 活动图表

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

详见活动图表解释

行为UML - 状态机图表

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

详见状态机图表

行为UML - 序列图和通信图

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

详见序列图

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

详见通信图

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

结构UML - 类图表

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

详见类图

结构UML - 组件图表

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

详见组件图

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

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

4+1 视图模型

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

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

详见4+1视图

C4模型

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

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

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

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

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

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

参考

documenting-software-architecture