MySQL Workbench 发行说明
本节概述了创建和修改 DBDoc 模型报告模板，这些模板由 MySQL Workbench 使用。
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 数据字典树
| 数据字典 | 加载数据字典 |
|---|---|
| MAIN | SCHEMATA |
| SCHEMATA | TABLES, COLUMNS (Detailed 为真), FOREIGN_KEYS (Detailed 为真), INDICES (Detailed 为真) |
| TABLES | REL_LISTING, INDICES_LISTING, COLUMNS_LISTING, TABLE_COMMENT_LISTING, DDL_LISTING |
| COLUMNS_LISTING | COLUMNS (Detailed 为假) |
| REL_LISTING | REL (Detailed 为假) |
| INDICES_LISTING | INDICES (Detailed 为假) |
树的根是 主 字典。其他字典从根加载以形成字典树。
注意
如果模板没有节，则模板中使用的任何变量都在主字典中查找。如果在主字典中找不到变量（可以将其视为与默认节或主节关联），则在输出文件中不会为该标记生成任何数据。
变量的评估
数据字典的树状结构对于变量评估很重要。由于变量是在数据字典中定义的，因此它们关联的值只有在特定数据字典处于活动状态时才有意义，这意味着与该数据字典关联的节处于活动状态。当进行变量查找时，系统会检查与当前节关联的数据字典。如果可以在那里找到变量值，则会进行替换。但是，如果在当前数据字典中找不到变量的值，则会检查父数据字典以查找变量的值，依此类推，直到到达主数据字典或根节点。
假设我们要显示模型中所有列的名称。请考虑以下模板，它试图实现这一点
Report
------
Column Name: {{COLUMN_NAME}}此模板不生成任何输出，即使对于包含一个或多个列的模型也是如此。在本例中，唯一处于活动状态的数据字典是主字典。但是，COLUMN_NAME 存储在 COLUMNS 数据字典中，该字典与 COLUMNS 节关联。
有了这些知识，可以改进模板，如下所示
Report
------
{{#COLUMNS}}
Column Name: {{COLUMN_NAME}}
{{/COLUMNS}}这仍然不会生成输出。要了解原因，请参阅 表 9.2，“数据字典树”。COLUMNS 数据字典的父字典是 COLUMNS_LISTING。COLUMNS_LISTING 的父字典是 TABLES，其父字典是 SCHEMATA，其父字典是主字典。请记住，要使字典参与变量查找，其关联的节必须当前处于活动状态。
要实现所需的输出，模板必须类似于以下内容
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 在每次迭代中都会有正确的值。
始终要考虑哪个字典必须处于活动状态（以及哪些父字典）才能正确评估变量。下一节包含一个表，可以帮助您识别节要求。