不只是画图：用Graphviz+Python自动生成系统架构图，提升文档效率
不只是画图：用Graphviz+Python自动生成系统架构图，提升文档效率
在技术文档和系统设计过程中，图表是不可或缺的沟通工具。然而，传统的手动绘制方式往往效率低下，特别是在架构频繁变更的场景下。本文将展示如何利用Python的graphviz库，将数据结构自动转换为专业级系统架构图，实现"代码即图表"的高效工作流。
1. 为什么选择代码生成架构图
手动绘制架构图存在几个明显痛点：修改成本高、版本控制困难、风格不统一。而使用代码生成图表可以完美解决这些问题：
- 版本友好：图表定义以代码形式存储，可与项目代码一起进行版本控制
- 修改便捷：调整架构只需修改几行代码，无需重新绘制
- 风格一致：通过预定义样式模板确保所有图表风格统一
- 自动化集成：可嵌入CI/CD流程，在文档构建时自动生成最新图表
# 简单示例：创建一个包含三个节点的流程图 from graphviz import Digraph dot = Digraph(comment='简单流程') dot.node('A', '数据采集') dot.node('B', '数据处理') dot.node('C', '结果存储') dot.edges(['AB', 'BC']) dot.render('simple_flow', view=True)2. Graphviz核心概念与Python实现
2.1 基本元素定义
Graphviz通过几个基本元素构建图表：
- 节点(Node)：系统组件或处理单元
- 边(Edge)：组件间的关系或数据流
- 子图(Subgraph)：逻辑分组，可控制布局
# 定义带有属性的节点和边 dot = Digraph('architecture', format='png') dot.node('db', '数据库', shape='cylinder', color='blue') dot.node('api', 'API服务', shape='box', style='filled', fillcolor='#f0f0f0') dot.edge('db', 'api', label='查询', fontsize='10')2.2 样式定制技巧
通过属性字典实现批量样式设置：
# 全局样式设置 style = { 'node': { 'fontname': 'Arial', 'shape': 'box', 'color': '#333333' }, 'edge': { 'fontname': 'Arial', 'fontsize': '10', 'color': '#666666' } } dot = Digraph() dot.attr('node', **style['node']) dot.attr('edge', **style['edge'])3. 从数据结构自动生成架构图
3.1 字典转架构图
将Python字典自动转换为系统组件关系图：
def dict_to_graph(data, graph_name): dot = Digraph(graph_name) for component, details in data.items(): dot.node(component, details['label'], **details.get('attrs', {})) for dep in details.get('dependencies', []): dot.edge(component, dep) return dot system = { 'load_balancer': { 'label': '负载均衡', 'dependencies': ['web_server'] }, 'web_server': { 'label': 'Web服务', 'dependencies': ['database'] } } graph = dict_to_graph(system, 'web_architecture') graph.render('web_arch', format='svg')3.2 类关系可视化
自动生成类继承关系图：
import inspect def class_hierarchy(cls): dot = Digraph() for base in cls.__bases__: dot.edge(cls.__name__, base.__name__) dot = class_hierarchy(base) + dot return dot # 示例使用 class Animal: pass class Mammal(Animal): pass class Dog(Mammal): pass class_hierarchy(Dog).render('class_hierarchy')4. 高级应用场景
4.1 微服务架构可视化
services = [ {'name': 'user', 'type': 'service', 'deps': ['auth', 'database']}, {'name': 'auth', 'type': 'service', 'deps': ['database']} ] dot = Digraph('microservices') for svc in services: dot.node(svc['name'], shape='ellipse' if svc['type']=='service' else 'box') for dep in svc['deps']: dot.edge(svc['name'], dep) dot.render('microservices_arch', cleanup=True) # cleanup自动删除临时文件4.2 动态流程图生成
def generate_workflow(steps): dot = Digraph('workflow', engine='dot') for i, step in enumerate(steps): dot.node(str(i), step['name']) if i > 0: dot.edge(str(i-1), str(i), label=step.get('condition', '')) return dot steps = [ {'name': '开始'}, {'name': '验证输入', 'condition': '输入有效'}, {'name': '处理数据'} ] generate_workflow(steps).render('workflow')5. 集成到文档工作流
5.1 与Markdown集成
在文档构建流程中自动生成并插入图表：
# docs_gen.py def generate_docs(): arch_graph = create_architecture() arch_graph.render('docs/images/arch') with open('docs/architecture.md', 'w') as f: f.write(f"# 系统架构\n\n")5.2 自动化样式指南
创建可复用的样式模板：
class DiagramStyle: @staticmethod def aws(): return { 'ec2': {'shape': 'box3d', 'color': 'orange'}, 'rds': {'shape': 'cylinder', 'color': 'blue'} } dot = Digraph() aws_style = DiagramStyle.aws() dot.node('web', 'Web服务器', **aws_style['ec2']) dot.node('db', 'MySQL', **aws_style['rds'])实际项目中，我们会将常用组件封装为工厂函数，进一步简化图表创建过程。例如，定义一个create_service()函数，自动应用团队统一的样式规范。