自定义 API 执行（MagicApiController）

MagicApi 自定义 API 模块入口：按应用名称（appName）查找软件 id，再按请求方法 + URL 模板匹配 ApiConfig，执行其响应脚本（responseScript），按 responseType（json / xml / binary / 其他）输出结果。支持路径变量注入 ParamsTable。

• 接口类型：REST 资源（@Component 继承 AbstractRuntimeController，方法返回 void，由控制器直接写回 HttpServletResponse 输出流；响应内容由 ApiConfig.responseType 决定——json 写 JSON 文本、xml 写 XML 文本、binary 写文件下载流、其他写纯文本）
• 基址：${myapps.context-path.runtime:}（仅 runtime context-path，方法级路径 /magic-api/{appName}/** 不带 /api 前缀）
• Tag：MagicApi

公共说明

• 鉴权（据源码）：基址不在 /api/runtime/**，不在 RestSecurityHandlerInterceptor 覆盖范围。鉴权由全局过滤器 RuntimeSecurityFilter（/*）执行登录态校验，未登录返回 401（或 SSO 模式重定向到 /signon）。控制器内 getUser() 允许返回 null——此时若 ApiConfig.status 不为 public 则响应 401 Not Permission，为 public 时允许匿名执行。
• 响应结构：非统一 Resource。响应内容由 ApiConfig.responseType 决定：
• json：Content-Type: application/json; charset=utf-8，正文为脚本返回值经 Jackson 序列化后的 JSON（null 字段统一序列化为空字符串 ""）；集合/数组则走 JSONArray，否则走 JSONObject；
• xml：Content-Type: application/xml; charset=utf-8，正文为 <{类名}>{json 转 xml}</{类名}>；
• binary 或脚本返回 File：触发文件下载（application/x-download; charset=utf-8，Content-Disposition: attachment;filename="<编码文件名>"）；
• 其他：直接 out.append((String) result)，正文为脚本返回的字符串。
• 路径变量提取：使用 AntPathMatcher.extractUriTemplateVariables(apiConfig.getRequestUrl(), requestUrl) 将 URL 模板变量（如 /{id}）提取后 params.putAll(pathParams) 注入 ParamsTable。
• 错误处理：异常时若响应未提交，则将 e.getMessage() 写入响应正文。

---

1. 执行自定义 API

按 appName 解析软件 id；按请求方法（GET/POST/...）+ 解析后的 URL 在该软件的 ApiConfig 集合中匹配；命中后执行 responseScript，按 responseType 输出。

• 接口类型：REST 资源（直接写回 HttpServletResponse 输出流）
• 请求方式：@RequestMapping（未限定 method，支持 GET / POST / PUT / DELETE 等；具体允许的方法由匹配到的 ApiConfig 决定）
• 请求路径：/magic-api/{appName}/**（完整：{runtime-context}/magic-api/{appName}/**）
• 鉴权：是（需 accessToken，据源码：过滤器校验登录态；ApiConfig.status != "public" 时控制器再次校验 getUser() 非空，否则返回 401）
• Tag：MagicApi

请求参数

参数名	位置	类型	必填	说明
appName	path	string	是	应用名称（解析为 application id）
**	path	string	否	URL 模板 /** 匹配后续路径片段；路径变量按 ApiConfig.requestUrl 模板提取
content	body	string	否	请求体原样字符串，通过 params.setParameter("_content", content) 注入 ParamsTable

请求示例

POST /magic-api/myapp/orders/12345 HTTP/1.1
Content-Type: application/json
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

{ "remark": "hello" }

响应

结构：由 ApiConfig.responseType 决定（详见「公共说明 · 响应结构」）。

成功示例（responseType=json）：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "orderId": "12345", "status": "PAID" }

成功示例（responseType=binary 或脚本返回 File）：

HTTP/1.1 200 OK
Content-Type: application/x-download; charset=utf-8
Content-Disposition: attachment;filename="report.pdf"

<二进制字节流>

失败示例（未找到 API）：

HTTP/1.1 404 Not Found

失败示例（未授权且非 public API）：

HTTP/1.1 401 Unauthorized

---