如何画架构图:完整教程 | text2diagram
架构图的 5 种类型、5 个基本元素、6 步画法,以及 arc42 和 C4 该怎么选、什么时候不用。
一、什么是架构图
架构图 是系统的一张地图:有哪些部件、怎么连、跑在哪。它回答三个连非技术同事都会问的问题 —— 系统里有什么、信息怎么流、东西在哪运行。
它比类图和 ER 图高一层。不画每个函数、每个字段,只画 组件(服务、数据库、队列、前端)和 关系(调用、读写、发布、部署)。看图的人是要做决定的人,不是编译器。
每张架构图都在细节和清晰之间做取舍。好的架构图只放刚好够回答某一个问题的信息:边界在哪、请求怎么走、数据存在哪。想一张图讲完所有事,是最常见的失败方式。
二、为什么要画架构图
3 类具体的麻烦,每一类都对应一个「当初要是有张图就好了」的时刻:
- 新人上手要花几天,而不是几小时。 新同事要么读一周源码,要么花五分钟看一张图。结论一样,时间差一个数量级。
- 跨团队沟通经常走死。 产品、DBA、运维、安全,各说各的话。架构图是所有人都能指的那块画布 —— 指「那个方框」不会有歧义,说「用户服务」会。
- 架构在悄悄变形。 系统会漂。原本分层清楚的应用,长出一条前端直连数据库的捷径。没有图,通常要等到安全审计或者一条慢 SQL 才有人发现。每个季度更一次图,能在代价还小的时候把它抓住。
三、架构图的五种类型
架构图不是只有一种。真实项目里主要就这 5 种,知道该画哪一种,事情就成了一半:
| 系统架构图 | 最外面一层:整个系统是一个方框,周围是用户、外部服务、跟它对话的其他系统。给业务方和产品负责人看,回答「边界里面是什么」。 |
| 软件架构图 | 往里一层:系统内部有哪些组件(服务、前端、消息队列、数据库),它们怎么通信。给开发和架构师看。大部分人说「架构图」指的就是这张。 |
| 云架构图(AWS / GCP / Azure) | 同样的组件,但明确落到云服务上(EC2 / S3 / Lambda / RDS / Cloud Run / App Service / Azure Functions 等等)。给运维、管成本的人、安全审计看,要画出 VPC、可用区、区域。 |
| 数据架构图 | 只看数据怎么流:从哪来、怎么变换、进哪个数仓、谁在下游用。跟 ER 图不一样 —— ER 图画表结构,数据架构图画流动。给数据工程和数据分析看。 |
| 集成架构图 | 只看系统之间的接口:REST API、消息代理、事件流、ETL 管道。给做集成的人和对外合作的团队看。系统一多(20 个以上互相连着)就少不了这张。 |
大多数项目需要其中 2-3 种,不是全部 5 种。先画系统架构图(最外层)和软件架构图(内部)。等有人明确问到部署、数据流或者接口,再补云 / 数据 / 集成那几张。
四、架构图的核心组件
画得好的架构图,用的都是同一套很小的词汇。这 5 种元素用对了,视觉语法的 90% 就自然对了:
- 方框 —— 组件。 一个方框是一个可部署的东西:一个服务、一个数据库、一个队列、一个前端。方框上既写名字也写类型:
UserService [Spring Boot],而不是光一个UserService。类型是在告诉读者,这东西在现实里对应什么。 - 箭头 —— 关系。 每条箭头都要有方向和标签,说明流过去的是什么:「读取」「发布事件」「HTTPS/JSON」。没标签的箭头是噪音,有标签的箭头在讲一件事。
- 分组 —— subgraph 或者分层。 相关的组件摆在一起:前端层、服务层、数据层。视觉上的分组就是概念上的分组。用 subgraph 还是用色块都行,选一种,全图统一。
- 外部角色 —— 用户和外部系统。 系统之外、但要跟它打交道的一切:终端用户、合作方 API、第三方登录、支付网关。一般画在图的边上,用小人图标或者普通矩形。
- 边界 —— 信任和部署。 认证在哪发生?数据在哪离开 VPC?用户输入在哪过校验?用虚线或色块画出来。边界经常比方框本身更重要。
五、如何画架构图:分步流程
一套可以照着走的流程。按顺序来,每一步的产出就是下一步的输入:
- 第 1 步:先说清楚给谁看、回答什么。 用一句话写下来:「这张图给 [谁] 看,回答 [什么问题]。」这句话写不完整就别动手,你会画出一张谁都用不上的图。
- 第 2 步:列组件。 把每个服务、数据库、队列、前端、外部系统都列出来,各自写上名字和类型。超过 15 个,多半是层级选错了,拆成两张。
- 第 3 步:分组。 按职责把组件归堆 —— 前端、服务、数据、外部。这就是 subgraph 的结构。分好组,图才能一眼扫完。
- 第 4 步:画箭头,带标签。 有通信的两个组件之间画一条箭头,写清楚流过去的是什么。写不出标签就删掉 —— 那条通信多半不存在。
- 第 5 步:画信任边界和部署边界。 在 VPC、安全区、可用区外面画虚线。这一步是普通图和架构图的分界:读者从这里才看得出风险在哪。
- 第 6 步:回到第 1 步验收。 把图放一放再冷读一遍,它真的回答了当初那个问题吗?没有,就是画多了、画少了,或者画错了对象。改。
这 6 步对第 3 节那 5 种图都适用。用 AI 可以省掉第 4、5 步:把前 3 步用文字描述给 text2diagram,几秒钟出图(见第 7 节)。
六、进阶:用 arc42 与 C4 模型画系统架构
画过几张之后,会碰到两套方法论:arc42(12 节文档模板)和 C4 模型(Simon Brown 提出的 4 层抽象)。两套都跟画法无关,也都免费。
arc42 是什么。 它给了 12 个编号的章节,你 可以 往里写:引言与目标、约束、上下文与范围、解决方案策略、构建块视图、运行时视图、部署视图、横切概念、架构决策(ADR)、质量需求、风险与技术债、术语表。重点不是每节都填 —— 多数项目只填 4-6 节 —— 而是知道有这些节,好有意识地跳过。完整模板见 arc42.org/overview。
C4 模型:Context → Container → Component → Code。 把架构切成 4 层来看。第 1 层 System Context,一个方框代表你的系统,加上用户和外部系统(就是第 3 节说的系统架构图)。第 2 层 Container,内部的应用和数据存储 —— 注意 C4 里的 container 指应用或数据存储,不是 Docker 容器。第 3 层 Component,一组由接口封起来的功能,跑在某个 container 的进程里。第 4 层 Code,类图;C4 自己都说别手工维护,交给 IDE 生成。完整规范见 c4model.com。
什么时候用哪个,什么时候都不用。 README 里的图,画一张普通的软件架构图就行,不需要方法论。给开发看的上手文档,用 C4 的 Context + Container,半小时到一小时。要长期维护的治理或审计文档、受监管的环境,用 arc42 做外壳,在第 3 节和第 5 节里嵌 C4 图。白板上随手画,两个都别用,直接画。方法论是工具,不是规定。
七、text2diagram 架构图案例
两个实际例子。两段 prompt 复制到 text2diagram 都能复现:第一段出软件架构图,第二段是同一个系统的 C4 System Context 图。
Example 1 — Software architecture (developer audience):
Please draw an architecture diagram for a small B2B analytics SaaS.
Components:
- Web App [Next.js SPA]
- API Server [Node.js REST + WebSocket]
- Query Engine [Rust service]
- Warehouse [ClickHouse cluster]
- Ingest [Kafka topic + consumer]
- Auth0 [external OIDC]
Tiers: Frontend / Services / Data
External: Customer browser uses the Web App; customer app pushes events to Ingest.Example 2 — C4 System Context (business audience, same system):
Please draw a system context diagram for AnalyticsPlatform.
Central box: AnalyticsPlatform (whole system, no internals)
External actors:
- Marketing analyst — logs in, runs queries
- Customer's application — streams raw events
- Auth0 — handles all sign-ins
- Customer's BI tool — pulls query results
Use business language, no technology names inside the box.同样 6 个组件,两张长得完全不一样的图。这就是第 5 节说的「先定给谁看」,具体到画面上的样子。
八、画架构图的常见误区
真实项目里反复出现的 6 种,每一种认出来之后都好修:
- 一张图想给所有人看。 结果是一团乱,谁都用不上。修法:画两张。业务方看 Context,开发看 Container。
- 箭头没有标签。 「UserService → Database」等于什么都没说:是读?是写?异步事件还是同步 HTTP?每条箭头都标上,写不出标签就删掉。
- 没画信任边界。 图上有组件,但看不出安全边界在哪。审计的人想知道,想攻进来的人也想知道。VPC、认证边界、非受信区,都画出来。
- 把 Docker 容器和 C4 container 混为一谈。 C4 里的 container 是「应用或数据存储」—— 一个跑着 SPA 的浏览器就是一个 C4 container。Docker 容器只是其中一种实现方式。没有上下文的时候别光说「container」。
- 不写版本、不写日期。 页脚没有「截至 2026-07,v2.1」的图,会在原地变旧。一年后看的人分不清它还准不准。所有图都打时间戳。
- 没想清楚给谁看就开始画。 最大的一个错。第 5 节第 1 步别跳:打开任何工具 之前,先写下「这张图给谁看,回答什么」。
常见问题
架构图、流程图、ER 图有什么区别?
架构图画 组件 和它们的 关系,是系统静态的形状。流程图画 步骤 随时间往下走,一件事怎么经过判断和动作。ER 图画 数据实体 和 schema 层的关系,也就是数据库长什么样。三者在不同的抽象层上,真实系统通常三张都要。
必须用 arc42 或者 C4 吗?
不必,两套都是可选的。README 或者白板草图,用了也不加分。给开发做上手文档,C4 的 Context + Container 很合适。要长期维护的治理文档,arc42 外壳里嵌 C4 图是现在的常见做法。但一张画得好的普通软件架构图(第 3 节),永远好过一套用错的方法论。
画架构图用什么工具?
看目的。头脑风暴用白板。要跟代码一起进 Git 的图用文本工具(Mermaid / PlantUML / text2diagram),diff 干净,改起来快。要精确控制每个元素的位置,用可视化编辑器(Lucidchart / draw.io / Excalidraw)。专门画云架构,用云厂商自己的图标库(AWS 图标 / Azure 蓝图)。想直接从文字生成,text2diagram 覆盖第 3 节这 5 种图。
架构图应该画到多细?
刚好够回答 一个 问题就停。业务方问「这系统是干什么的」,画一个方框加它的邻居。开发问「下单流程怎么走」,画参与的那 5-8 个服务和它们之间的箭头。经验值:一张图 12-15 个方框是人的工作记忆上限,超了就拆两张。
怎么让架构图不过期?
两个习惯。一是把图当文本存进 Git(Mermaid / PlantUML),这样 code review 能像抓 bug 一样抓架构漂移。二是凡是动到架构的 PR(加服务、加集成、加数据存储),在 checklist 里明确写一条「更新架构图」。躺在二进制文件里没人打开的图会过期,跟代码一起版本化的图不会。
text2diagram 能画第 3 节那 5 种图吗?
能。系统 / 软件 / 云 / 数据 / 集成都可以,输出 Mermaid flowchart,或者带云图标(AWS / GCP / Azure / K8s)的 architecture-beta。对话模式会先问你给谁看、看哪一层、重点在哪,所以同一批组件对不同读者能出不一样的图。见第 7 节的两个例子。