创建 API（Template + Create）

该文档补充 modules/database_meta/API.md，专注于新添加的创建相关接口：

POST /metadata/create/template — 返回用于前端渲染创建表单的模板
POST /metadata/object/create — 接收表单数据以生成预览 SQL 或执行创建

POST /metadata/create/template

描述：返回用于前端渲染创建表单的模板（字段定义、枚举选项、示例等）。前端使用该模板生成表单，用户填完后调用 /metadata/object/create 进行预览或执行。

请求体（JSON）：

{
  "objectType": "table",   // 必需：要创建的对象类型，例如 table/database/index
  "parentName": "mydb"     // 可选：父上下文（例如创建表时为数据库名）
}

响应（成功示例）：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "objectType": "table",
    "operation": "create",
    "parentHint": "parentName should be the database name",
    "fields": [
      {"name":"tableName","label":"Table Name","type":"string","required":true},
      {"name":"engine","label":"Engine","type":"enum","enumOptions":["InnoDB","MyISAM"],"default":"InnoDB"},
      {"name":"charset","label":"Charset","type":"enum","enumOptions":["utf8mb4","utf8","latin1","ascii","ucs2","utf16","utf32","big5","gbk"],"default":"utf8mb4"},
      {"name":"columns","label":"Columns","type":"list","nestedFields":[{"name":"name","type":"string"},{"name":"type","type":"string"}]}
    ],
    "example": {"tableName":"users","columns":"[{\"name\":\"id\",\"type\":\"INT\"}]","engine":"InnoDB"}
  }
}

备注：模板中会包含枚举选项（例如 charset 的常用字符集），驱动层已将常用字符集手动列出，前端应根据返回的 enumOptions 渲染下拉选择，而不是硬编码字符集列表。

说明（关于 operation 与 current 字段）

返回的模板为 meta.ObjectTemplate。为了统一模板格式，ObjectTemplate 包含一个可选字段 operation，值示例为 "create"|"update"|"delete"。 -- 对于创建（create）场景，operation 的值为 "create"。通常 ObjectTemplate.Current（对象级当前值）在创建场景不带值或为空；前端无需依赖 current 来填充创建表单。 -- 当调用更新（update）或删除（delete）模板端点时，服务端会在 ObjectTemplate.Current（map[string]string）以及每个 TemplateField.Current（string）中填充当前值，便于前端渲染默认值或展示影响预览。有关 current 的详细使用示例和前端优先级，请参阅 API.md 中的“关于当前值 (current) 的获取与使用”章节。

POST /metadata/object/create

描述：接收前端渲染并提交的创建表单数据。支持两种模式：preview（execute=false，仅返回生成的 SQL）和 execute（execute=true，驱动尝试执行生成的 SQL，需慎用）。

请求体（JSON）：

{
  "objectType": "table",          // 必需
  "parentName": "mydb",           // 可选，若为表则通常为数据库名
  "properties": {                  // 必需，表单字段和值
    "tableName": "users",
    "columns": [{"name":"id","type":"INT","nullable":false}],
    "engine": "InnoDB",
    "charset": "utf8mb4"
  },
  "execute": false                  // 可选，false=preview（默认），true=execute（执行 SQL）
}

响应（preview 成功示例）：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "success": true,
    "generatedSQL": ["CREATE TABLE `mydb`.`users` ( `id` INT NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;"],
    
  }
}

响应（execute 路径注意）：

若 execute==true，驱动会尝试执行生成的 SQL；请注意 DDL 操作在不同数据库/引擎下可能不可回滚，务必在有足够权限和审计的前提下使用。
当前实现对 execute 路径可能仍处于未全部实现或受限状态，客户端应以返回的 message/success 为准，并在开启执行前要求用户二次确认。

常见字段映射说明

驱动层将 CreateTemplate 中的字段作为前端渲染的契约，典型字段含义：
- type=="enum"：请使用 enumOptions 渲染下拉菜单；不要在客户端硬编码 charset，而应使用驱动返回的 enumOptions。
- type=="list"：表示可重复的子项（如 columns），nestedFields 描述每个子项的字段。

安全与权限建议

execute==true 操作应仅对受信任用户开启，并做好审计日志。建议在 handler 层或 API 网关对执行创建/删除的请求进行额外权限校验并记录调用者信息（用户、时间、请求体、生成的 SQL）。

向前不兼容（Breaking changes）提醒

本模块近期进行了若干向前不兼容的接口与行为调整：

不再接受 dotted ID（点号拼接）的 objectID/parentID；请改为使用结构化字段 objectName / parentName。
GetRootObjects/GetChildObjects/GetObjectDetails 新增 fetch 参数以支持“仅返回类型/计数”或“展开详细数据”的两种模式。

如果你希望我把这份文档合并回 API.md 的特定位置、生成 OpenAPI/Swagger，或为 /metadata/object/create 添加单元测试（覆盖 preview 路径），请告诉我下一步要做什么。

CREATE_API.md 5.2 KB Permalink History Raw