[Python] Python Diagrams库详解：用代码绘制云架构图，GitHub星标超41k

Diagrams是一个基于Python的开源库，它允许开发者和架构师使用代码来定义和生成专业的系统架构图。该项目在GitHub上已获得超过41k的星标，是“架构图即代码”（Diagrams as Code）理念的杰出代表。

为什么选择“图表即代码”？

在传统的开发流程中，架构图通常使用拖拽式绘图工具（如Visio、Draw.io）制作。这种方式虽然直观，但也存在明显的痛点：

• 难以维护：架构一旦变更，需要手动调整图形，易出错且耗时。
• 无法版本控制：图表文件（如图片或特定格式文件）难以像代码一样进行diff和merge，追溯变更历史困难。
• 缺乏自动化：无法与CI/CD流程集成，导致文档与真实架构脱节。

Diagrams通过将图表定义转化为Python代码，完美解决了上述问题，使得架构图可以像应用程序代码一样被编写、版本管理和自动化生成。

核心特性与安装

核心特性：

1. 丰富的图标库：内置支持AWS、GCP、Azure、阿里云、Kubernetes等主流云服务商和技术栈的图标。
2. 简洁的编程模型：只需掌握Diagram（图表）、Node（节点）、Cluster（集群）三个核心概念和 >>、<<、- 等操作符即可上手。
3. 自动化友好：生成的.py脚本可直接纳入Git管理，并能轻松集成到任何自动化流程中。

安装步骤：
Diagrams依赖于Graphviz进行图形渲染，因此需要两步安装：

1. 安装Graphviz（渲染引擎）：
   • macOS: brew install graphviz
   • Ubuntu/Debian: sudo apt install graphviz
   • Windows: 从Graphviz官网下载安装，并确保bin目录已添加到系统PATH。
2. 安装Diagrams库：

   pip install diagrams

快速入门：绘制你的第一张架构图

以下是一个简单的示例，创建一个包含负载均衡器、Web服务器和数据库的基础Web服务架构图。

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

# 使用Diagram上下文管理器，定义图表名称和布局方向（LR表示从左到右）
with Diagram("Simple Web Service", show=False, direction="LR"):
    # 定义组件节点
    lb = ELB("Load Balancer")
    web = EC2("Web Server")
    db = RDS("Database")

    # 使用 `>>` 操作符定义数据流或依赖关系
    lb >> web >> db

将代码保存为web_service.py并运行，即可在脚本同目录下生成一张名为simple_web_service.png的图片。

进阶示例：绘制微服务架构

对于更复杂的架构，可以使用Cluster来对组件进行逻辑分组，使图表更加清晰。

from diagrams import Diagram, Cluster
from diagrams.aws.compute import ECS
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Microservices with DB Cluster", show=False):
    # 定义外部服务
    gateway = ELB("API Gateway")
    frontend = ECS("Frontend Service")

    # 使用Cluster创建一个名为“DB Cluster”的分组
    with Cluster("DB Cluster"):
        # 在分组内定义[数据库](https://yunpan.plus/f/23-1)主从节点
        db_primary = RDS("Primary")
        db_replicas = [RDS("Replica1"), RDS("Replica2")]
        # 使用 `-` 操作符表示无方向的连接（如集群内部通信）
        db_primary - db_replicas

    # 定义服务间的依赖关系
    gateway >> frontend >> db_primary

这段代码会生成一张层次分明的架构图，清晰地展示了服务边界和数据库的主从复制关系。

优势对比与应用场景

典型应用场景：

• 系统设计：快速绘制和迭代架构原型。
• 项目文档：将图表脚本作为“活文档”存入代码库，确保实时更新。
• 运维手册：为运维团队提供精确的基础设施拓扑图。
• 技术分享：生成高质量的架构插图用于演示材料。

总结

Diagrams成功地将工程化思维引入架构图绘制领域。它可能无法替代需要高度自由设计的美工绘图，但对于追求准确性、可维护性和自动化的技术团队而言，无疑是管理架构文档的强大工具。在云原生和基础设施即代码（IaC）普及的今天，用代码定义和可视化架构正成为一种最佳实践。

项目地址：https://github.com/mingrammer/diagrams