模型元数据管理

本文档介绍了 Yao 框架中模型元数据的管理方法。模型元数据管理分为三个主要部分：单个模型实例的操作、全局模型管理和快照管理。

1. 模型实例管理

每个模型实例都提供了一系列操作方法，通过 models.MODEL_ID 进行访问，其中 MODEL_ID 为模型的唯一标识符。

1.1 模型实例基本操作

models.MODEL_ID.migrate

功能描述：将模型配置同步到数据库（创建或更新表结构）

参数说明：

参数	类型	说明	必填	默认值
force	boolean	是否强制删除表数据	否	false

返回值：

• 类型：object
• 说明：迁移结果对象

示例代码：

// 基本用法 - 同步表结构
Process('models.pet.migrate');

// 强制重置表结构和数据
Process('models.pet.migrate', true);

命令行用法：

# 基本用法
yao run models.pet.migrate

# 强制重置
yao run models.pet.migrate true

models.MODEL_ID.load

功能描述：从文件或源代码加载模型配置

参数说明：

参数	类型	说明	必填	默认值
file	string	文件名	是	-
source	string	源代码（如果提供，优先加载源代码）	否	-

返回值：

• 类型：null 或 Error
• 说明：成功返回 null，失败返回错误对象

示例代码：

// 从文件加载
Process('models.pet.load', '/models/pet.mod.json');

// 从源代码加载
Process('models.pet.load', '', {
  name: '宠物信息',
  table: { name: 'pet', comment: '宠物信息表' },
  columns: [
    { name: 'id', type: 'ID' },
    { name: 'name', type: 'string', comment: '宠物名称' },
    { name: 'type', type: 'string', comment: '宠物类型' }
  ]
});

models.MODEL_ID.reload

功能描述：重新加载模型配置

参数：无

返回值：

• 类型：object
• 说明：加载结果对象

示例代码：

// 重新加载模型配置
Process('models.pet.reload');

models.MODEL_ID.read

功能描述：读取模型元信息

参数：无

返回值：

• 类型：object
• 说明：模型配置信息对象

示例代码：

// 读取模型配置
const modelInfo = Process('models.pet.read');
console.log(modelInfo);

models.MODEL_ID.exists

功能描述：检查模型是否存在

参数：无

返回值：

• 类型：boolean
• 说明：true 表示存在，false 表示不存在

示例代码：

// 检查模型是否存在
const exists = Process('models.pet.exists');
if (exists) {
  console.log('模型已存在');
} else {
  console.log('模型不存在');
}

2. 快照管理

快照功能允许您保存和恢复模型的数据状态，这对于数据备份和恢复非常有用。

2.1 快照基本操作

models.MODEL_ID.takesnapshot

功能描述：创建模型的数据快照

参数说明：

参数	类型	说明	必填	默认值
inMemory	boolean	是否仅在内存中存储快照	否	false

返回值：

• 类型：string
• 说明：快照名称

示例代码：

// 创建快照
const snapshot = Process('models.pet.takesnapshot', false);
console.log('创建的快照名称:', snapshot);

models.MODEL_ID.restoresnapshot

功能描述：从快照恢复模型数据

参数说明：

参数	类型	说明	必填	默认值
name	string	快照名称	是	-

示例代码：

// 从快照恢复
Process('models.pet.restoresnapshot', 'pet_snapshot_20230101');

models.MODEL_ID.restoresnapshotbyrename

功能描述：通过重命名表的方式从快照恢复数据

参数说明：

参数	类型	说明	必填	默认值
name	string	快照名称	是	-

示例代码：

// 通过重命名恢复快照
Process('models.pet.restoresnapshotbyrename', 'pet_snapshot_20230101');

models.MODEL_ID.dropsnapshot

功能描述：删除指定的快照

参数说明：

参数	类型	说明	必填	默认值
name	string	快照名称	是	-

示例代码：

// 删除快照
Process('models.pet.dropsnapshot', 'pet_snapshot_20230101');

models.MODEL_ID.snapshotexists

功能描述：检查指定的快照是否存在

参数说明：

参数	类型	说明	必填	默认值
name	string	快照名称	是	-

返回值：

• 类型：boolean
• 说明：true 表示存在，false 表示不存在

示例代码：

// 检查快照是否存在
const exists = Process('models.pet.snapshotexists', 'pet_snapshot_20230101');
if (exists) {
  console.log('快照存在');
} else {
  console.log('快照不存在');
}

3. 全局模型管理

3.1 模型列表和查询

model.list

功能描述：列出所有模型的信息

参数说明：

参数	类型	说明	必填	默认值
metadata	boolean	是否返回模型完整元信息，包含用户在模型中定义的所有信息	否	false
columns	boolean	是否返回列信息字典，包括列名、类型、注释等	否	false

返回值：

• 类型：array
• 说明：模型信息对象数组

需要注意的是：在每一个模型中的columns对象是一个字典对象，而metadata中的columns对象是一个数组。

返回值示例：

[
  {
    "file": "/models/app/blog/site.mod.yao",
    "table": {
      "name": "app_blog_site",
      "collation": "",
      "charset": "",
      "primarykeys": null
    },
    "primary": "id",
    "metadata": {
      "name": "博客",
      "columns": [...],
      "relations": {...},
      "option": {}
    },
    "columns": {...},
    "id": "app.blog.site",
    "name": "博客",
    "description": ""
  }
]

示例代码：

yao run -s model.list "::{\"metadata\":true,\"columns\":true}" > models_list.json

js 示例：

// 基本用法
const models = Process('model.list');
console.log('所有模型列表:', models);

// 获取详细信息
const modelsWithDetails = Process('model.list', {
  metadata: true,
  columns: true
});

// 处理返回结果
modelsWithDetails.forEach((model) => {
  console.log(`模型ID: ${model.id}`);
  console.log(`表名: ${model.table.name}`);
  if (model.columns) {
    console.log('列信息:', model.columns);
  }
});

model.read

功能描述：获取指定模型的源代码 参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-

返回值：

• 类型：string
• 说明：模型源代码字符串

示例代码：

// 基本用法
const modelSource = Process('model.read', 'admin.user');
console.log('管理用户的源代码:', modelSource);

model.dsl

功能描述：获取指定模型的元数据信息

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-
options	object	可选参数	否	{}

options 参数说明：

参数	类型	说明	默认值
metadata	boolean	是否返回模型完整元信息	false
columns	boolean	是否返回列信息字典	false

返回值：

• 类型：object
• 说明：模型元数据信息对象

示例代码：

yao run model.dsl pet '::{\"metadata\":true,\"columns\":true}' > pet_model_dsl.json

// 基本用法
const petModel = Process('model.dsl', 'pet');
console.log('宠物模型信息:', petModel);

// 获取完整信息
const petModelDetails = Process('model.dsl', 'pet', {
  metadata: true,
  columns: true
});

// 处理模型信息
if (petModelDetails) {
  console.log(`模型名称: ${petModelDetails.name}`);
  console.log(`表名: ${petModelDetails.table.name}`);

  if (petModelDetails.columns) {
    console.log('列信息:');
    Object.entries(petModelDetails.columns).forEach(([name, info]) => {
      console.log(`- ${name} (${info.type}): ${info.comment}`);
    });
  }
}

2.2 模型生命周期管理

model.exists

功能描述：检查指定模型是否存在

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-

返回值：

• 类型：boolean
• 说明：true 表示存在，false 表示不存在

示例代码：

// 检查模型是否存在
const exists = Process('model.exists', 'pet');
if (exists) {
  console.log('宠物模型已存在');
} else {
  console.log('宠物模型不存在');
}

model.reload

功能描述：重新从本地文件加载模型

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-

返回值：

• 类型：null 或 Error
• 说明：成功返回 null，失败返回错误对象

示例代码：

// 重新加载模型
Process('model.reload', 'pet');
console.log('宠物模型已重新加载');

model.migrate

功能描述：迁移指定模型

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-
force	boolean	是否强制删除表数据	否	false

返回值：

• 类型：object
• 说明：迁移结果对象

示例代码：

// 基本迁移
Process('model.migrate', 'pet');

// 强制重置迁移
Process('model.migrate', 'pet', true);

model.load

功能描述：从文件或源代码加载模型

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-
source	string	模型配置	是	-

返回值：

• 类型：null 或 Error
• 说明：成功返回 null，失败返回错误对象

示例代码：

// 从源代码加载模型
const modelSource = {
  name: '宠物信息',
  table: { name: 'pet', comment: '宠物信息表' },
  columns: [
    { name: 'id', type: 'ID' },
    { name: 'name', type: 'string', comment: '宠物名称' }
  ]
};

Process('model.load', 'pet', JSON.stringify(modelSource));

model.unload

功能描述：从内存中卸载模型

参数说明：

参数	类型	说明	必填	默认值
modelID	string	模型ID	是	-

返回值：

• 类型：null 或 Error
• 说明：成功返回 null，失败返回错误对象

示例代码：

// 卸载模型
Process('model.unload', 'pet');
console.log('宠物模型已卸载');