设计时数据源管理（DataSourceController）

数据源设计时资源管理：数据源的增删改查、设为默认、连接测试，数据源元数据（树形）查询，数据库备份/恢复/备份列表，索引信息查询与优化，以及表信息查询和表单字段同步。

• 接口类型：REST 资源
• 基址：${myapps.context-path.designer:}/api/designtime/applications（类级 @RequestMapping，produces = APPLICATION_JSON_VALUE）
• Tag：设计时-数据源模块

公共说明

• 鉴权：是（需 designerToken）。所有端点继承自 AbstractDesignTimeController（基类为 @RestController），通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
• 路径变量：{applicationId}、{dataSourceId}/{datasourceId} 均为**明文设计时 ID**（与 designer 其他控制器一致，非 runtime 的 DES 加密密文）。注意源码中存在 dataSourceId 与 datasourceId 两种大小写写法（分别用于不同端点），实际为同一概念。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500，errmsg 为异常信息。本控制器对所有异常（含 doSaveValidate 抛出的重名校验 OBPMValidateException）统一按 errcode=500 返回；setDefaultDataSource 在数据源不存在时返回 errcode=404；doIndexOptimization 在未配置默认数据源时返回 errcode=400。
• HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
• 请求体约定：多数 POST/PUT/DELETE 接收原始 JSON 字符串（@RequestBody String content）或 JSON 字符串数组（@RequestBody String[]），由服务端用 JSONObject.fromObject 解析。
• 环境变量占位：testDataSources 中的 url/username/password 支持 ${ENV_VAR} 形式的环境变量占位（由 SimpleExpression.process 解析）。

---

1. 获取数据源列表

分页获取指定应用下的数据源列表，可按名称查询。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources（完整：{designer-context}/api/designtime/applications/{applicationId}/datasources）
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
name	query	string	否	数据源名称关键字（未标注 @RequestParam，按请求参数绑定，可缺省）
pageNo	query	string	否	页码（缺省 1）
linesPerPage	query	string	否	每页条数（缺省 10）

说明：@Parameter 将 pageNo/linesPerPage/name 标记为 required=true，但实现做了缺省兜底（pageNo 缺省 1、linesPerPage 缺省 10）。

请求示例

GET /api/designtime/applications/{applicationId}/datasources?name=&pageNo=1&linesPerPage=10 HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<DataSource>（含分页字段与 datas）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "rowCount": 2,
    "pageNo": 1,
    "pageCount": 1,
    "datas": [
      { "id": "...", "name": "数据源名称", "dbTypeName": "...", "...": "..." }
    ]
  },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

2. 获取数据源详情

按数据源Id获取完整数据源对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/{dataSourceId}
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
dataSourceId	path	string	是	数据源Id

响应

data：DataSource 完整对象（含连接配置、DbType、是否默认等）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "dbTypeName": "...", "...": "..." }, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

3. 新建数据源

在指定应用下新建数据源。先做重名保存前校验，再持久化。新建时若未带 id 则由 Sequence.getDesignTimeSequence() 生成。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/datasources
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	数据源对象 JSON

请求体

对应 DataSource 对象 JSON（name、dbTypeName、连接配置等）。

{ "name": "<数据源名称>", "dbTypeName": "mysql", "...": "..." }

响应

data：保存后的 DataSource 对象。重名时 errcode=500，errmsg 形如 [<名称>]{*[core.form.exist]*}（OBPMValidateException 被通用 Exception 捕获）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<新数据源Id>", "name": "...", "...": "..." }, "errors": null }

失败示例（重名等）：

{ "errcode": 500, "errmsg": "[<名称>]{*[core.form.exist]*}", "data": null, "errors": null }

---

4. 更新数据源

按数据源Id更新数据源对象。更新时会清空 uri、强制以路径参数 dataSourceId 覆盖 id，并在保存成功后通过 RuntimeFeignService.clearDataSourceCache 异步通知运行时清理数据源缓存（Feign 调用失败被忽略）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/datasources/{dataSourceId}
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
dataSourceId	path	string	是	数据源Id（覆盖 body 中的 id）
content	body	string(JSON)	是	数据源对象 JSON

请求体

对应 DataSource 对象 JSON（uri 字段将被服务端置空）。

响应

data：更新后的 DataSource 对象。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "...": "..." }, "errors": null }

失败示例（重名等）：

{ "errcode": 500, "errmsg": "<异常信息或重名提示>", "data": null, "errors": null }

---

5. 设置为默认数据源

将指定数据源设为当前应用的默认数据源（defaultDataSource=true），并刷新 DbTypeUtil._dbTypes 缓存与运行时数据源缓存。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/datasources/{dataSourceId}/default
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
dataSourceId	path	string	是	数据源Id

响应

data：更新后的 DataSource 对象。数据源不存在时 errcode=404。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "defaultDataSource": true, "...": "..." }, "errors": null }

失败示例（不存在）：

{ "errcode": 404, "errmsg": "数据源不存在", "data": null, "errors": null }

---

6. 删除数据源（可批量）

按数据源Id数组批量删除数据源（含路径信息收集与删除日志记录）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/datasources
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
ids	body	string	是	数据源Id字符串数组（JSON 数组反序列化为 String[]）

请求体

["<dataSourceId1>", "<dataSourceId2>"]

响应

data：String，固定为 "删除成功"。

{ "errcode": 0, "errmsg": "ok", "data": "删除成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

7. 测试数据源

测试数据源连接是否可用。从 body 读取 driverClass/url/username/password，对其中的 ${ENV_VAR} 占位用环境变量解析后，调用 DataSourceEnv.testDb 实际建立一次连接。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/testdatasources
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（路径段，未绑定到方法参数）
content	body	string(JSON)	是	数据源连接信息 JSON

请求体

{
  "driverClass": "com.mysql.cj.jdbc.Driver",
  "url": "jdbc:mysql://host:3306/db",
  "username": "dbuser",
  "password": "dbpass"
}

响应

data：String，成功时为国际化文案 {*[cn.myapps.core.deploy.application.connect_success]*}!；失败时 errcode=500，errmsg 提示地址或用户名密码错误。

{ "errcode": 0, "errmsg": "ok", "data": "{*[cn.myapps.core.deploy.application.connect_success]*}!", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "{*[cn.myapps.core.deploy.application.connect_error]*}! \n原因:地址或用户名称,密码填写错误!", "data": null, "errors": null }

---

8. 获取源数据

返回数据源的元数据树形节点。subNodes 缺省时返回应用下所有数据源节点（一级）；subNodes=isTables 时返回指定数据源下的全部物理表节点（二级，有对应表单时附带 formId）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/metadatas
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	query	string	否	数据源Id（subNodes=isTables 时必填）
subNodes	query	string	否	子节点类型：缺省=列数据源节点；isTables=列指定数据源下的物理表

请求示例

GET /api/designtime/applications/{applicationId}/datasources/metadatas HTTP/1.1
GET /api/designtime/applications/{applicationId}/datasources/metadatas?datasourceId=<id>&subNodes=isTables HTTP/1.1

响应

data：Collection<Node>（视图树节点）。

• 一级（数据源）节点属性：name、appication、datasourceId、curNode=isDts、rel=db/db_selected（默认数据源为 db_selected）、subNodes=isTables，状态为 STATE_CLOSED。
• 二级（物理表）节点属性：name(=表名)、datasourceId、curNode=isTable、rel=table、subNodes=none；若该表有对应表单，则附带 formId、appication（表单应用Id），节点 id 为表单Id，否则 id 为表名。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "id": "...", "data": "数据源名称", "attr": { "name": "...", "datasourceId": "...", "curNode": "isDts", "rel": "db", "subNodes": "isTables" }, "state": "closed" }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

9. 备份数据库生成SQL

按数据源Id将该数据源对应的数据库备份为 SQL 文件，落盘到 <workspace>/<应用路径>/database/<数据源名><yyyyMMddHHmmss>.sql。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/datasources/{datasourceId}/backup
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id

响应

data：String，成功时为提示文案 数据库[<url>]成功备份到<path>！。

{ "errcode": 0, "errmsg": "ok", "data": "数据库[<url>]成功备份到<path>！", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

10. 恢复数据库

按数据源Id从指定 SQL 备份文件恢复数据库，文件从 <workspace>/<应用路径>/database/<filename> 读取。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/datasources/{datasourceId}/restore
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id
filename	query	string	是	备份文件名（位于应用 database/ 目录下）

请求示例

POST /api/designtime/applications/{applicationId}/datasources/{datasourceId}/restore?filename=<备份文件名>.sql HTTP/1.1

响应

data：String，成功时为提示文案 数据库[<url>]成功从<path>恢复！。

{ "errcode": 0, "errmsg": "ok", "data": "数据库[<url>]成功从<path>恢复！", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

11. 获取备份数据库SQL列表

返回指定数据源对应的应用 database/ 目录下、以 <数据源名> 为前缀且后缀为 .sql 的备份文件清单。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/{datasourceId}/backup-list
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id

响应

data：JSONArray，每项 {name, size, lastModified}。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "name": "<数据源名>20260804120000.sql", "size": 1048576, "lastModified": 1780000000000 }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

12. 获取索引信息

按数据源Id读取该数据源下所有表的索引信息（由 MetadataProcess.getAllTables 返回）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/{datasourceId}/indexs
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id

响应

data：Collection<ITable>（含表名、列、索引等元信息）。

{ "errcode": 0, "errmsg": "ok", "data": [ { "name": "...", "...": "..." } ], "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

13. 优化索引

对应用的默认数据源执行索引优化（MetadataProcess.doIndexOptimization）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationid}/datasources/optimization
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	应用Id（源码形参命名为 applicationid，全小写）

请求示例

GET /api/designtime/applications/{applicationid}/datasources/optimization HTTP/1.1

响应

data：String，成功时为 "优化完成"；未配置默认数据源时 errcode=400。

注意：实现中异常分支仅 e.printStackTrace() 后 return null，即异常时响应体为 null（非 Resource 结构）。

{ "errcode": 0, "errmsg": "ok", "data": "优化完成", "errors": null }

失败示例（未配置默认数据源）：

{ "errcode": 400, "errmsg": "未配置默认数据源", "data": null, "errors": null }

---

14. 获取表信息

按 formId（表单Id或物理表名）获取表元数据。formId 能匹配到表单时附带表单对象；可通过 tableName 显式指定不同的物理表名（此时以 tableName 为准）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/{datasourceId}/forms/{formId}/info
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id
formId	path	string	是	表单Id 或物理表名
tableName	query	string	否	物理表名（指定时覆盖 formId 推断的表名）

请求示例

GET /api/designtime/applications/{applicationId}/datasources/{datasourceId}/forms/{formId}/info HTTP/1.1
GET /api/designtime/applications/{applicationId}/datasources/{datasourceId}/forms/{formId}/info?tableName=<物理表名> HTTP/1.1

响应

data：TableMetadata（含 datasource、form（命中时）、table）。

{ "errcode": 0, "errmsg": "ok", "data": { "datasource": { "...": "..." }, "form": { "...": "..." }, "table": "<表名>" }, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

15. 同步表单字段

按 formId 同步表单字段到指定数据源的物理表：加载该表单及其所有父表单，逐个比对物理表已有列，仅保留表中存在的字段，再通过 FormTableProcessBean.synDynaTable 同步动态表结构。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/datasources/{datasourceId}/forms/{formId}/synformfiels
• 鉴权：是（需 designerToken）
• Tag：设计时-数据源模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
datasourceId	path	string	是	数据源Id
formId	path	string	是	表单Id

请求示例

GET /api/designtime/applications/{applicationId}/datasources/{datasourceId}/forms/{formId}/synformfiels HTTP/1.1

响应

data：String，固定为 "同步完成"。

{ "errcode": 0, "errmsg": "ok", "data": "同步完成", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---