Django Extensions graph_models 命令完全指南:从 Django 模型生成 GraphViz 架构图

原创2026-10-05 10:31:531,934 阅读
文章标签:后端开发工具

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 方法):

  1. 确定 app 列表:读取位置参数 app_label;若为空且未开启 --all-applications,则回退到 settings.GRAPH_MODELS['app_labels'],否则抛出 CommandError: need one or more arguments for appname。
  2. 确定输出格式:根据 --pydot / --pygraphviz / --json / --dot 选项、-o 文件扩展名以及库可用性,自动决策输出为 dot 文本、JSON 还是图片。
  3. 构建模型图数据:由 ModelGraph(modelviz.py)负责遍历 app、模型、字段与关系,生成结构化图数据。
  4. 模板渲染:通过 Django 模板加载器加载 django_extensions/graph_models/<theme>/digraph.dot 等三份模板,渲染成最终 DOT 代码(modelviz.py)。
  5. 输出:写文件、打印到 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.dot
  • django_extensions/graph_models/label.dot
  • django_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 分别着色以直观区分模型归属。两种提供样式文件的方式:

  1. 在项目根目录放置 .app-style.json 文件(默认文件名,源码常量 DEFAULT_APP_STYLE_NAME);
  2. 用 --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 分组的输出效果参见下图:

Grouped application model diagram

按 app 着色生成 PNG

$ ./manage.py graph_models -a --app-style path/to/style.json -o my_styled_project.png

效果示意:

Styled application model diagram

指定渲染后端

$ ./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 的效果:

Sample Foo and Bar models diagram

排除特定模型

$ ./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 中模板上下文的结构自行扩展。

登录后查看全文
django-extensions