Django Extensions graph_models 命令完全指南:从 Django 模型生成 GraphViz 架构图
Django Extensions graph_models 命令完全指南:从 Django 模型生成 GraphViz 架构图
导读
graph_models 是 django-extensions 提供的 Django 管理命令,它读取指定 app(或 INSTALLED_APPS 全部应用)的 models.py,解析模型、字段与关系,输出一份 GraphViz DOT 格式的图形化概览,并可在安装 pygraphviz 或 pydot 后直接渲染为 PNG、SVG、PDF 等图片。本文以 docs/graph_models.rst 为主线,结合 graph_models.py、modelviz.py 的源码实现与 test_graph_models.py 测试用例,系统讲解安装选型、全局默认配置、模板定制、按 app 着色、模型包含/排除、关系样式等全部能力,读完即可在实际项目中一键输出可读的模型关系图。
一、命令定位与整体工作流程
命令的帮助信息与文档第一句一致:"Creates a GraphViz dot file for the specified app names."。你可以传入多个 app 名称,它们会被合并进同一个模型图中;输出通常被重定向(>)到一个 dot 文件,也可以使用 -o 直接指定输出文件。
从源码看,命令执行分为几个阶段(见 graph_models.py 的 handle 方法):
- 确定 app 列表:读取位置参数
app_label;若为空且未开启--all-applications,则回退到settings.GRAPH_MODELS['app_labels'],否则抛出CommandError: need one or more arguments for appname。 - 确定输出格式:根据
--pydot / --pygraphviz / --json / --dot选项、-o文件扩展名以及库可用性,自动决策输出为 dot 文本、JSON 还是图片。 - 构建模型图数据:由
ModelGraph(modelviz.py)负责遍历 app、模型、字段与关系,生成结构化图数据。 - 模板渲染:通过 Django 模板加载器加载
django_extensions/graph_models/<theme>/digraph.dot等三份模板,渲染成最终 DOT 代码(modelviz.py)。 - 输出:写文件、打印到 stdout,或交给 pygraphviz/pydot 渲染成图片。
整个流程既有文档与源码双重支撑,也被测试覆盖:test_graph_models_no_output_options 验证了无任何输出选项时默认输出 DOT 文本,test_graph_models_json_option_to_file 等用例则验证了 JSON 输出(见 test_graph_models.py)。
二、选择渲染库:pygraphviz 与 pydot
生成图片需要选择一个图形渲染库,通过命令行参数指定:
--pygraphviz:使用 PyGraphViz 渲染。--pydot:使用 PyDot(或 PyDotPlus)渲染。
当两者都未指定时,默认按 pygraphviz → pydot 的顺序尝试加载可用库。源码中两个库都是可选的导入(graph_models.py):
HAS_PYGRAPHVIZ:尝试import pygraphviz;HAS_PYDOT:先尝试import pydotplus,失败则回退import pydot。
安装方式
安装 pygraphviz 通常一条命令即可:
$ pip install pygraphviz
但 pygraphviz 需要编译 C 扩展,某些环境下可能安装失败。此时可以改用 PyDot:
$ pip install pyparsing pydot
注意:文档特别强调要安装这个精确版本的 pyparsing,否则可能出现如下错误:
Couldn't import dot_parser, loading of dot files will not be possible.
输出格式的自动决策逻辑
handle 方法中的决策顺序值得细读(graph_models.py):
- 若
--pydot / --pygraphviz / --json / --dot中多于一个被设置,直接报错(Only one of ... can be set)。 - 设置了某个格式选项时,以该选项为准。
- 未设置格式选项且没有
-o文件时,出于向后兼容默认输出 DOT 文本到 stdout。 - 有
-o文件时按扩展名推断:.dot→ DOT、.json→ JSON;其他扩展名先看 pygraphviz 是否可用,再看 pydot,两者都没有则报错并提示改用--json或--dot输出文本。 - 一致性检查:设置
--pygraphviz或--pydot但未提供-o文件时,会报错要求必须指定输出文件(2.1.4 之前此场景会静默退化为 stdout 输出 dot 文本)。测试test_graph_models_pydot_without_file与test_graph_models_pygraphviz_without_file明确断言了这一行为。
三、默认设置:settings.GRAPH_MODELS
如果不希望每次都在命令行敲参数,可以在 Django 设置文件中通过 GRAPH_MODELS = {} 字典指定默认选项,例如:
GRAPH_MODELS = {
'all_applications': True,
'group_models': True,
}
命名规则:与命令行长选项同名,去掉开头的两个短横线(--),其余 - 替换为 _。例如 --disable-fields 对应键名 disable_fields。实现见 graph_models.py:handle 构造时遍历 self.arguments,将每个长选项名转换为设置键名,命中则覆盖该参数的默认值。
要指定一组默认的 app,使用 app_labels 键:
GRAPH_MODELS = {
'app_labels': ["myapp1", "myapp2", "auth"],
}
这个键是特殊处理的:当命令行未给 app 且未开 --all-applications 时,会回退读取 GRAPH_MODELS<a href="https://link.gitcode.com/i/513e5c3c1c0635483268db0d981baae0" target="_blank">'app_labels'] 作为默认 app 列表([graph_models.py)。
四、模板机制:用 Django 模板生成 DOT
文档明确指出:DOT 代码由 Django 模板生成,再由 pygraphviz/pydot 等库绘制成图片;你可以按需扩展或覆盖模板。命令使用的三份模板是:
django_extensions/graph_models/digraph.dotdjango_extensions/graph_models/label.dotdjango_extensions/graph_models/relation.dot
当前仓库在 templates/django_extensions/graph_models 下提供了三套主题:
| 主题目录 | 特点 |
|---|---|
original/ |
默认字体 Helvetica,经典样式 |
django2018/ |
默认主题(--theme 缺省值),字体 Roboto,HTML 表格节点 |
django2018style/ |
django2018 的样式变体 |
--theme/-t 参数选择主题,默认 django2018;帮助信息说明可自行创建 django_extensions/graph_models/themename/ 模板目录来定制新主题(graph_models.py)。
渲染时模板上下文包含 created_at、cli_options、rankdir、ordering、use_subgraph、graphs 等图数据字段。以默认主题 digraph.dot 为例,它通过 {% block digraph_options %} 设置 rankdir、ordering,再分别 {% include %} label.dot(模型节点,以 HTML <TABLE> 呈现字段名与类型)和 relation.dot(关系边)。
模板渲染的注意事项
修改 Django 默认的模板加载行为可能破坏 graph_models!
- 任何改变模板渲染方式的
template_loaders或扩展都可能导致graph_models失败。 - 典型反例是 Django 应用
django-template-minifier:它会自动删除模板标签前后的换行,即便对非 HTML 模板也如此,最终产生格式损坏的 dot 文件。
此外,generate_dot 还会校验模板确实由默认 Django 模板加载器渲染(要求是 Template 实例),否则抛出异常,提示检查设置(modelviz.py)。
五、按 App 着色(App-based Styling)
当多个 app 的模型相互关联时,可以按 app 分别着色以直观区分模型归属。两种提供样式文件的方式:
- 在项目根目录放置
.app-style.json文件(默认文件名,源码常量DEFAULT_APP_STYLE_NAME); - 用
--app-style命令行选项指定 JSON 文件路径:
$ ./manage.py graph_models -a --app-style path/to/style.json -o styled_output.png
JSON 文件将 app label 映射到样式字典。app label 可以精确匹配,也可以使用通配符(如 django.*),多个匹配时最后一条生效。示例:
{
"app1": {"bg": "#341b56"},
"app2": {"bg": "#1b3956"},
"django.*": {"bg": "#561b4c"},
"django.contrib.auth": {"bg": "#c41e3a"}
}
目前支持的样式键只有 bg(背景色),但设计上已为未来扩展(font、shape、border 等)预留了空间。
源码级实现
retheme()(graph_models.py)读取 JSON(用object_pairs_hook=OrderedDict保持顺序),遍历每个 graph 的每个模型,用fnmatch.fnmatchcase(app_name, pattern)做通配符匹配,将命中 pattern 的样式写入模型style字典——由于按 JSON 键顺序迭代,后写入的覆盖先写入的,这正是"最后一条生效"的实现来源。- 样式文件的查找顺序:先看
--app-style指定的路径;若未指定,则尝试项目根目录settings.BASE_DIR下的.app-style.json(graph_models.py)。 - 文件不存在会抛异常:命令行指定且文件不存在时,直接
CommandError;默认文件也不存在则跳过着色。 - 样式的应用点:模板中模型表头背景
BGCOLOR="{{ model.style.bg|default:"#1b563f" }}"(label.dot),说明bg实际控制节点表头栏的背景色。
这一特性让你能在单张图中同时高亮各 app 的模型分组、又不切断跨 app 的关系。
六、完整命令行用法示例
基础:生成 dot 文件或图片
# 创建 dot 文件(输出到 stdout,重定向到文件)
$ ./manage.py graph_models -a > my_project.dot
# 生成 PNG 图片并启用 app 分组
$ ./manage.py graph_models -a -g -o my_project_visualized.png
使用 -a(--all-applications)会自动纳入 INSTALLED_APPS 中的全部应用(modelviz.py),即 apps.get_app_configs() 的每个 app.label。
带 app 分组的输出效果参见下图:
按 app 着色生成 PNG
$ ./manage.py graph_models -a --app-style path/to/style.json -o my_styled_project.png
效果示意:
指定渲染后端
$ ./manage.py graph_models --pygraphviz -a -g -o my_project_visualized.png
$ ./manage.py graph_models --pydot -a -g -o my_project_visualized.png
只绘制指定的 app
$ ./manage.py graph_models foo bar > my_project.dot
只包含特定模型(支持通配符)
$ ./manage.py graph_models -a -I Foo,Bar -o my_project_subsystem.png
-I/--include-models 将图限制为指定模型,* 通配符可用。匹配逻辑见 ModelGraph.use_model(modelviz.py):通配符 * 被替换为 .* 并包裹成 ^...$ 正则,对模型名做匹配。只含 Foo/Bar 的效果:
排除特定模型
$ ./manage.py graph_models -a -X Foo,Bar -o my_project_sans_foo_bar.png
组合:先包含后排除
# 先按模式选中包含的模型,再过滤掉需要排除的
$ ./manage.py graph_models -a -I Product* -X *Meta -o my_project_products_sans_meta.png
隐藏关系标签
$ ./manage.py graph_models -a --hide-edge-labels -o my_project_sans_foo_bar.png
源码中 hide_edge_labels 会同时清空模型节点字段的关系标签与继承标签(modelviz.py),测试 test_hide_edge_labels 断言输出中不再出现 [label="..."]。
改变关系箭头形状
$ ./manage.py graph_models -a --arrow-shape normal -o my_project_sans_foo_bar.png
--arrow-shape 默认值为 dot,合法取值:box, crow, curve, icurve, diamond, dot, inv, none, normal, tee, vee。它会作为 ForeignKey / ManyToMany 边的 arrowhead/arrowtail 渲染(modelviz.py)。
按 on_delete 给关系边着色
$ ./manage.py graph_models -a --color-code-deletions -o my_project_colored.png
--color-code-deletions 依据关系字段的 on_delete 设置给边着色,颜色映射定义在 modelviz.py:
| on_delete 值 | 颜色 |
|---|---|
CASCADE |
red |
PROTECT |
blue |
SET_NULL |
orange |
SET_DEFAULT |
green |
SET |
yellow |
DO_NOTHING |
grey |
RESTRICT |
purple |
仅对 ForeignKey 与 OneToOneField 生效(modelviz.py)。
改变布局方向
# 支持的方向: "TB", "LR", "BT", "RL"
$ ./manage.py graph_models -a --rankdir BT -o my_project_sans_foo_bar.png
--rankdir 默认 TB(自上而下),可选 TB/LR/BT/RL,对应 GraphViz 中 top-to-bottom、left-to-right、bottom-to-top、right-to-left。注意:rankdir 只有在输出为 pydot/pygraphviz/dot 时可用,选择 JSON 输出会报错(graph_models.py)。渲染为图片时 layout 引擎由 --layout/-l 指定,默认 dot,可选 circo dot fdp neato nop nop1 nop2 twopi。
改变关系边排列顺序
# 支持的顺序: "in", "out"
$ ./manage.py graph_models -a --ordering in -o my_project_sans_foo_bar.png
--ordering 控制边如何排列:in(先排入边/入站关系)、out(先排出边/出站关系),默认 None;同样仅在 pydot/pygraphviz/dot 输出下可用(graph_models.py)。
七、常用选项速查表
以下参数均来自命令定义(graph_models.py),均可通过 GRAPH_MODELS 设置同名默认值:
| 选项 | 作用 |
|---|---|
--app-style |
按 app 着色的 JSON 样式文件路径 |
--pygraphviz / --pydot |
指定图片渲染后端 |
--dot / --json |
输出 DOT 文本 / JSON 数据(而非图片) |
--disable-fields -d |
不显示模型类成员字段 |
--disable-abstract-fields |
不显示继承自抽象基类的字段 |
--display-field-choices |
显示字段 choices 而非字段类型 |
--group-models -g |
按 app 将模型分组(subgraph 聚类) |
--all-applications -a |
自动纳入 INSTALLED_APPS 全部 app |
--output -o |
渲染输出文件,扩展名决定类型(如 png/jpg) |
--layout -l |
GraphViz 布局引擎,默认 dot |
--theme -t |
模板主题,默认 django2018 |
--verbose-names -n |
使用模型与字段的 verbose_name |
--language -L |
verbose_name 本地化语言 |
--exclude-columns -x |
排除指定列(也支持从文件读取列表) |
--exclude-models -X |
排除指定模型(支持 * 通配符,可从文件读取) |
--include-models -I |
只保留指定模型(支持 * 通配符) |
--inheritance -e / --no-inheritance -E |
是否绘制继承箭头(默认包含) |
--hide-relations-from-fields -R |
不将关系显示为字段 |
--relation-fields-only |
只显示与关系相关的字段 |
--disable-sort-fields -S |
不对字段排序 |
--hide-edge-labels |
不显示关系标签 |
--arrow-shape |
关系箭头形状,默认 dot |
--color-code-deletions |
按 on_delete 给关系边着色 |
--rankdir |
布局方向,默认 TB |
--ordering |
边排列顺序:in / out |
两点源码细节值得留意:
- 列表类参数支持从文件读取:
parse_file_or_list(modelviz.py)对--exclude-columns/-x、--exclude-models/-X、--include-models/-I做解析——若参数值不是逗号分隔且指向一个存在的文件,则按行读取作为列表。 --relation-fields-only:skip_field会过滤掉所有非关系字段(保留 ForeignKey、ManyToMany、OneToOne、RelatedField、反向关系字段),测试test_graph_models_relation_fields_only验证了它等价于手工删除全部非关系字段后的输出(test_graph_models.py)。
八、底层模型图数据与继承处理
ModelGraph(modelviz.py)是图数据的核心构造器,几点实现细节有助于理解输出:
- 节点与边:每个模型生成一个节点(含字段列表),
local_fields(含主键、外键等)与local_many_to_many生成关系边;OneToOneField使用无箭头的双向边,ForeignKey使用arrowhead=none、arrowtail=<arrow-shape>的双向边,ManyToManyField两侧均为arrow-shape,GenericRelation使用虚线样式(modelviz.py)。 - 继承:开启
--inheritance(默认)时,为每个父类添加继承边,标签区分abstract/multi-table/proxy三种类型,并使用arrowhead=empty, dir=both的空心箭头(modelviz.py)。 - 抽象模型:抽象基类会被收集并展现在子类字段上(
get_bases_abstract_fields),配合--disable-abstract-fields可隐藏这些继承字段;test_disable_abstract_fields_active与test_disable_abstract_fields_not_active两个测试分别验证了开启与不开启时的字段可见性(test_graph_models.py)。 - 字段排序:默认按"主键优先、关系字段次之、其余按 label 字母序"排序(modelviz.py),
-S可关闭。 - JSON 输出:
get_graph_data(as_json=True)会剥离不可序列化的model/field对象,输出created_at、cli_options、graphs等结构化数据(modelviz.py),便于二次程序化处理。 - 缺失模型的关系处理:
generate_graph_data会为每个关系打上needs_node标记,仅当目标模型确实出现在图中时才为其生成节点,避免孤立节点(modelviz.py);test_exclude_models_hides_relationships则回归验证了被排除模型不会残留关系边。
九、写在最后
graph_models 是把"代码中的模型关系"转化为"可读的架构图"的轻量工具:不引入额外 ORM、不修改项目代码,只需一条 manage.py 命令即可在文档、评审、新人入职讲解中复用。日常使用建议:
- 全量架构图用
-a -g -o xxx.png; - 关注局部子系统用
-I/-X结合通配符精确圈定; - 多 app 协作项目用
--app-style区分归属; - 需要程序化分析时用
--json输出结构化数据; - 把高频参数沉淀进
settings.GRAPH_MODELS,让命令更简洁。
对于更深度的定制(如新主题、新样式键),可从 templates/django_extensions/graph_models 目录出发,参考 modelviz.py 中模板上下文的结构自行扩展。


