9.7 自定义 DBDoc 模型报告模板

MySQL 工作台 / 第9章数据库设计与建模 / 9.7 自定义 DBDoc 模型报告模板

9.7 自定义 DBDoc 模型报告模板

9.7.1 支持的模板标记
9.7.2 创建自定义模板

本节概述了创建和修改 MySQL Workbench 使用的 DBDoc 模型报告模板。

MySQL Workbench DBDoc 模型报告系统基于 Google 模板系统。本讨论并不试图详细解释 Google 模板系统。有关 Google 模板系统工作原理的有用概述，请参阅 Google 文档，如何使用 Google 模板系统。

DBDoc 模型报告系统使用的模板是包含标记的文本文件。这些文本文件由 MySQL Workbench 内置的模板系统处理，标记由实际数据替换。然后生成输出文件。用户随后查看的正是这些输出文件，通常是 HTML 或文本。

标记可以是以下任何类型：

模板包含
评论
设置分隔符
语用
多变的
节开始和节结束

最后两个是 MySQL Workbench 模板中最常用的，这些重要的标记将在以下部分中进行简要描述。

变量

在生成输出文件之前，模板文件中由标记表示的变量将被替换为相应的数据。变量及其对应数据之间的映射由 MySQL Workbench 存储在数据字典中。在数据字典中，变量名是键，变量对应的数据是值。MySQL Workbench 构建数据字典并用已处理模型中包含的数据填充它。

例如，以下代码片段显示了模板文件的一部分：
```
Total number of Schemas: {{SCHEMA_COUNT}}
```
在生成的输出文件中，变量 {{SCHEMA_COUNT}}被替换为模型中模式的数量：
```
Total number of Schemas: 2
```
一个变量可以在模板文件中出现多次。
部分

部分用于在模板中执行迭代。当 MySQL Workbench 为数据交换一个部分中的变量时，它会迭代地这样做，使用定义变量的数据字典中的所有数据。MySQL Workbench 根据当前正在处理的模型构建数据字典。

考虑以下代码片段：
```
{{#SCHEMATA}}
Schema: {{SCHEMA_NAME}}
{{/SCHEMATA}}
```
在前面的代码片段中，部分的开始和结束由{{#SCHEMATA}}和 {{/SCHEMATA}}标记指示。MySQL Workbench 在处理模板时，会记录该部分并对其进行迭代，直到{{SCHEMA_NAME}} 耗尽相应数据字典中的变量数据。例如，如果正在处理的模型包含两个模式，则该部分的输出可能类似于以下内容：
```
Schema: Airlines
Schema: Airports
```

数据字典

更详细地了解节和数据字典之间的关系很重要。在数据字典中，变量的键是变量名，即标记。变量值是变量的数据。数据字典中某个部分的条目不同。对于数据字典中的节条目，键是节名称，即标记。但是，与键关联的值是数据字典列表。在 MySQL Workbench 中，每个部分通常都与一个数据字典相关联。您可以将一个部分视为激活其关联的词典（或多个词典）。

处理模板时，数据字典以分层模式加载，形成数据字典树。下表说明了这一点。

表 9.2 数据字典树

数据字典	加载数据字典
主要的	图式
图式	TABLES、COLUMNS（详细为真）、FOREIGN_KEYS（详细为真）、INDICES（详细为真）
桌子	REL_LISTING、INDICES_LISTING、COLUMNS_LISTING、TABLE_COMMENT_LISTING、DDL_LISTING
COLUMNS_LISTING 列	列（详细为假）
REL_LISTING	REL（详细为假）
INDICES_LISTING	指数（详细为假）

树的根是主字典。从根部加载额外的词典以形成词典树。

笔记

如果模板没有部分，则在主字典中查找模板中使用的任何变量。如果在主字典中找不到变量（可以认为与默认或主要部分相关联），则不会在该标记的输出文件中生成任何数据。

变量评估

数据字典的树结构对于变量评估很重要。由于变量是在数据字典中定义的，因此它们的关联值仅在特定数据字典处于活动状态时才有意义，这意味着与该数据字典关联的部分处于活动状态时。当发生变量查找时，系统会检查与当前部分关联的数据字典。如果可以在那里找到变量值，则进行替换。但是，如果在当前数据字典中找不到变量的值，则会检查父数据字典中的变量值，依此类推直到到达主数据字典或根。

假设我们要显示模型中所有列的名称。将以下模板视为实现此目的的尝试：

Report
------
Column Name: {{COLUMN_NAME}}

此模板不产生任何输出，即使对于包含一列或多列的模型也是如此。在此示例中，唯一活动的数据字典是主字典。但是，COLUMN_NAME存储在COLUMNS与节关联的数据字典中COLUMNS。

有了这些知识，模板可以改进如下：

Report
------
{{#COLUMNS}}
Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}

这仍然不会产生输出。要了解原因，请参阅表 9.2，“数据字典树”。数据字典有 COLUMNS父字典 COLUMNS_LISTING。 COLUMNS_LISTING有 parent TABLES，它有 parent SCHEMATA，其 parent 是主字典。请记住，要使字典参与变量查找，其关联部分当前必须处于活动状态。

要获得所需的输出，模板必须类似于以下内容：

Report
------

{{#SCHEMATA}}
{{#TABLES}}
{{#COLUMNS_LISTING}}
{{#COLUMNS}}
Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

以下模板相同，但添加了解释性注释：

Report
------

{{! Main dictionary active}}
{{#SCHEMATA}}  {{! SCHEMATA dictionary active}}
{{#TABLES}}  {{! TABLES dictionary active}}
{{#COLUMNS_LISTING}} {{! COLUMNS_LISTING dictionary active}}
{{#COLUMNS}}  {{! COLUMNS dictionary active}}
Column Name: {{COLUMN_NAME}} {{! COLUMN_NAME variable is looked-up,
and found, in COLUMNS data dictionary}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

现在想象一下，对于显示的每个列名，您还想显示其对应的架构名称，模板将如下所示：

Report
------

{{#SCHEMATA}}
{{#TABLES}}
{{#COLUMNS_LISTING}}
{{#COLUMNS}}
Schema Name: {{SCHEMA_NAME}} Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}
{{/COLUMNS_LISTING}}
{{/TABLES}}
{{/SCHEMATA}}

当为执行变量查找时 SCHEMA_NAME，COLUMNS 会检查字典。由于在那里找不到变量，将检查父字典COLUMNS_LISTING，等等，直到最终在SCHEMATA字典中找到变量所在的位置。

如果模型中有多个模式，外部部分将迭代匹配的次数， SCHEMA_NAME因此每次迭代都有正确的值。

重要的是要始终考虑哪个字典必须处于活动状态（以及哪个父字典）才能正确评估变量。以下部分有一个表格，可帮助您确定部分要求。