架构图
一张图只有在其展示的内容能与读者已有的知识对接时,才算被理解。资深开发者阅读它,是为了顶层流程和那些接缝。一个模块是一个黑盒:它的设计模式、职责、所有者,以及其内部细节隐藏。一个模块通过接缝提供给另一个模块的东西,就是它的接口:包含操作(带参数和返回类型)、错误、跨越接缝的数据类型及其字段,以及一个跨越了什么以及它看起来怎么样的示例。传输方式(REST、OPC UA、进程启动)只是接口的一个属性,绝不能替代接口本身。
在绘图前请阅读 EXAMPLE.md:一个完整的变更,以两种形式呈现。
步骤
1. 读者的词汇
新术语无法建立任何连接。在做其他事之前,先收集读者已有的词汇:来自本次对话中的消息、他们撰写的文档(项目说明、架构页面、术语表、命名法表格),以及所有与之对比的模型。编写词汇表:事物本身、读者的用语、其他会阅读该图表的各方的用语、代码中的名称,以及图表中使用的术语。
- 用读者的用语标记每个模块和接口;代码名称放在其旁边。
- 当两个词汇冲突,或一个词汇被用于错误的事物时,选择一个,在词汇表中说明原因,并在其他位置仅提一次另一个词汇。
- 不创造新词。一个在代码中没有名称的接口,用其两端命名,如
前端 -> 后端。 - 从读者已有的画面开始,即他们自己的图表及其层级和名称,然后将新内容放入其中。
当图表上的每个标签都来自词汇表,并且所有对读者来说是新的术语都作为已知词的从属条目出现在词汇表中时,此步骤完成。
2. 问题
为读者写下问题,每行一个。他们选择视图。
| 问题 | 视图 |
|---|---|
| 有哪些部分,每个部分负责什么,谁拥有它,谁调用谁? | 构建块视图 |
| 哪个接口连接两个部分,它具体传递什么? | 接口,其数据类型及每个接缝上的一个示例 |
| 在关键的场景中,按什么顺序发生什么? | 运行时视图:一个序列 |
| 每个部分在哪里运行? | 每个模块上的 host:;当问题是关于网络或信任边界时,使用部署视图 |
| 变更做了什么,或者两个设计如何不同? | 每个状态采用相同形式,然后展示差异 |
当每个视图都有其对应的问题,并且该问题作为标题位于视图上方时,此步骤完成。
3. 目录
在开始绘图前,从信息来源中填写四个列表。
- 模块:读者的用语和代码中的名称、原型(stereotype)、一句职责描述、所有者、主机。
- 接口,每个接缝一个:提供者、消费者、每个操作的签名
名称(参数: 类型) -> 类型、错误、传输方式。 - 数据类型:签名中提到的每个类型,包含其字段、单位和默认值。
- 示例,每个接口一个:消息在跨越时的真实格式:带输出的命令行、JSON 主体、表行。从一次运行、一段记录、一个测试夹具或数据中获取。基于代码拼凑的示例需要在第一行注明。
每个条目都需要注明来源:代码引用 路径:行号,或一个标签(见下文)。他人绘制的状态、模型文件或草图,按其原样和原有词汇复现;其缺失的内容标记为 [undefined],而您添加的内容则归入一个独立的状态。
当每个模块都有其一句话描述,每个接缝都有其接口(签名从代码复制或已标记),签名的每个类型都有其字段,每个接口都有其示例,且每个条目都有引用或标签时,此步骤完成。
4. 层级
一个状态中的模块是同级的:它们是独立部署、拥有或替换的单元,数量在五到九个之间。文件、函数和模块内部的步骤是其内部细节。放大(zoom) 是一个向下深入一层的图表,仅为该问题关注的模块绘制。
当没有一个模块包含另一个模块,并且每个放大视图都指明了为之付费的问题时,此步骤完成。
5. 形式
- 聊天形式,宽度不超过78列:构建块视图,每个边上显示接口名称及其主要签名,然后目录以表格形式呈现,示例以代码块形式呈现。适用于单一状态或小变更。
- 画布形式,一个静态 HTML 页面,文本图表根据需要尽可能宽:每个边旁边完整显示接口、示例以及带字段的数据类型。适用于多个状态,或当需要完整展示超过三个接缝时。该页面由旁边的生成器脚本构建;聊天回复中需命名该文件,用几句话说明比较结果,并列出未决决策。
- C4 形式,使用 LikeC4 在同一模型上绘制,页面每个状态一个标签页,有可点击和放大的框。文本图表是其原型:先确定词汇、模块、接口和示例,然后渲染。适用于其他人会打开的结果。阅读 LIKEC4.md。
6. 绘制
使用此文件夹中的三个文件进行绘制,以确保框对齐且没有行宽超过其画布。每个文件的文档字符串是其使用手册,运行它会打印一个演示。
| 文件 | 提供 |
|---|---|
grid.py | Grid(带隔间的框、线条、箭头)、sequence(运行时视图)、table |
canvas.py | glance(所有状态在一行内)、overview(状态并排,每层一行)、panel(一个状态:模块、带示例的接口、数据类型) |
page.py | html_page:围绕图表的页面,包含颜色和 ID 之间的链接 |
likec4/ | 用于 C4 形式:template.c4、build.sh、带 tabs.js 的标签页 index.html,以及 clicktest.py |
页面从十秒钟概览图片到细节:概览、词汇表、阅读指南、概览视图、每个状态一个面板、按接缝的差异表格、未决决策、术语表、来源。
7. 检查
- 每个框都是目录中的一个模块,每条边都是一个接口,每个类型框都是一个数据类型;有意从图表中省略的条目需额外说明。
- 每个代码引用都能解析:文件存在且行号显示名称。
- 同一个模块在所有状态中位于相同位置。某个状态缺少的模块用虚线框表示。
- 截取整个页面的截图,逐块阅读:边界对齐,无内容被截断,颜色传达其含义。
- 来源需说明读取了什么、在哪个提交、哪些示例是真实的、以及什么没有读取。
状态
状态可以是代码的现状、他人绘制的目标,或一个方案。通过位置比较状态:使用 glance 中同一列、overview 中同一行的相同模块,以便两个状态的空白区域显示它们如何互补。
一个接缝有一个由状态字母和数字组成的ID,例如 (I4)。在一个接缝处定义的接口或数据类型在其他任何地方通过该ID引用;其字段只编写一次。
差异是一个表格,每个接缝一行,每个状态一列。未决决策也是一个表格:包含问题、选项和决策者。
标签和原型
| 标签 | 含义 |
|---|---|
[code] | 存在于代码中;引用位于其旁边 |
源模型标签,如 [c4] | 由源模型指明;在阅读指南中命名该标签 |
[proposed] | 此处提出,尚未存在于任何地方 |
[new] [changed] [moved] | 变更带来的影响,当只有现状和目标时使用 |
[undefined] | 该状态对此未定义 |
[?1] | 一个未决决策,用编号列出 |
原型为模块扮演的设计模式命名:<<ui>>、<<client>>、<<gateway>>、<<facade>>、<<service>>、<<port>>、<<adapter>>、<<repository>>、<<external>>。当代码扮演该角色时使用一个原型;没有原型的模块也比使用错误原型要好。端口(port)是一个接口,由消费者拥有,提供者实现:<<port>> 位于接口上,<<adapter>> 位于实现它的模块上。源模型自身种类的命名按其写法引用。
解释手段
每一种手段都应以其能回答读者原本会问的问题来证明其存在的价值。谨慎使用。
- 阅读指南:一个展示如何阅读面板以及标签含义的小型图表。
- 代码引用:在每个接口和数据类型上,以便读者可以查阅。
- 简短文本:状态上方的一句话段落,说明在其中需要看到的一点;接口框内的注释,用于读者可能会问为什么的地方。
- 术语表:词汇表未涵盖的术语,每行一个。
- 颜色:仅用于标签、ID,以及一两个在所有状态中保持不变的
key名称。颜色标记状态的共有部分和差异部分;其他内容不用颜色。
正文使用对话的语言。代码和源模型中的名称保持原样。