设计时外部接口管理（ExtInterfaceController）

外部接口（ExtInterface）设计时资源管理：外部接口的增删改查、批量删除，自定义 jar 包文件上传，以及保存时自动生成调用示例代码。

• 接口类型：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}、{extId} 均为**明文设计时 ID**（与 designer 其他控制器一致，非 runtime 的 DES 加密密文）。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500，errmsg 为异常信息；保存校验失败（API Path 为空、名称重名）捕获 OBPMValidateException 返回 errcode=40001；上传文件类型不合法返回 errcode=4001。
• HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
• 请求体约定：POST/PUT 接收原始 JSON 字符串（@RequestBody String content），由服务端用 JSONObject.fromObject 解析；DELETE 接收 JSON 数组字符串（@RequestBody String content），由 JsonPath 解析为 List<String>。
• 接口类型常量（来自 ExtInterface，对应 type）：RESTFULTYPE（REST）、WEBSERVICETYPE（WebService）、JARTYPE（Jar）。buildExampleCode 据此生成调用示例。

---

1. 获取外部接口列表

分页获取指定应用下的外部接口列表，可按名称查询。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
name	query	string	否	按名称查询关键字
pageNo	query	int	否	页码（缺省 1）
linesPerPage	query	int	否	每页条数（缺省 10）

请求示例

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

响应

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

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "pageNo": 1,
    "pageCount": 1,
    "rowCount": 2,
    "datas": [
      { "id": "...", "name": "...", "type": "RESTful", "requestUrl": "...", "requestType": "GET", "...": "..." }
    ]
  },
  "errors": null
}

失败示例：

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

---

2. 获取外部接口详情

按外部接口Id获取完整外部接口对象。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
extId	path	string	是	外部接口Id

响应

data：ExtInterface 完整对象。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "type": "RESTful", "requestUrl": "...", "exampleCode": "...", "...": "..." }, "errors": null }

失败示例：

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

---

3. 新建外部接口

在指定应用下新建外部接口。保存前做 API Path 非空与名称重名校验，并按 type 生成 exampleCode。

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

请求参数

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

请求体

对应 ExtInterface 对象 JSON（name、type、requestUrl、requestType、requestParams、encode、jarPath、wsdl、definitions 等）。

响应

data：JSONObject，仅含 id（新建外部接口Id）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<外部接口Id>" }, "errors": null }

失败示例（校验失败，errcode=40001）：

{ "errcode": 40001, "errmsg": "名称已经存在！", "data": null, "errors": null }

失败示例（其他异常）：

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

---

4. 更新外部接口

按外部接口Id更新外部接口。先取现有对象克隆，再以入参覆盖白名单字段（name、requestType、requestUrl、encode、jarPath、requestParams、requestScheme、wsdl、type、exampleCode、definitions），并清空 uri，保存前同样做校验与示例代码生成。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
extId	path	string	是	外部接口Id
content	body	string(JSON)	是	外部接口对象 JSON

响应

data：null（成功）。

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

失败示例（校验失败，errcode=40001）：

{ "errcode": 40001, "errmsg": "<校验信息>", "data": null, "errors": null }

失败示例（其他异常）：

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

---

5. 删除外部接口（可批量）

按 id 集合批量删除外部接口。请求体为 JSON 数组字符串，由 JsonPath 解析为 List<String>（含逐条路径信息收集）。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	id 集合（JSON 数组字符串，由 JsonPath 解析为 List<String>）

请求体

["<extId1>", "<extId2>"]

响应

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

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

失败示例：

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

---

6. 上传 jar 文件

向指定外部接口上传一个或多个 jar 文件，保存至 <storageRoot>/workspace<path> 目录。文件名含 / 或 \ 抛出 OBPMValidateException("上传的文件名称不合法！")（方法本身未 try-catch，异常向上抛出）；扩展名不在合法白名单时直接返回 errcode=4001。

• 接口类型：REST 资源（multipart 上传）
• 请求方式：POST
• 请求路径：/{applicationId}/extinterfaces/{extId}/uploads
• 鉴权：是（需 designerToken）
• Tag：设计时-外部接口模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
extId	path	string	是	外部接口Id（决定上传目录 path）
file	body(form)	file[]	是	multipart 文件数组，表单字段名 file

请求体

multipart/form-data，字段名 file，可重复多次。

响应

data：JSONArray，每项 {fileName, filePath}（filePath 形如 /<fileName>）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "fileName": "xxx.jar", "filePath": "/xxx.jar" }
  ],
  "errors": null
}

失败示例（文件类型不合法，直接返回）：

{ "errcode": 4001, "errmsg": "上传的文件类型不合法！", "data": null, "errors": null }

失败示例（文件名不合法，OBPMValidateException 向上抛出，由全局异常处理）：

{ "errcode": 500, "errmsg": "上传的文件名称不合法！", "data": null, "errors": null }

---