.api / .apigroup 文件 Schema¶

位置：/{软件名}.application/api/　|　XML 根：Api / ApiGroup　|　与技能对齐：generate-api-file 机制背景见 [[design/table-schema/overview]]。

1. 用途与落盘¶

API 中心 = **入站**自定义 REST 接口：外部/前台按 {context}/magic-api/{软件名}{requestUrl} 调用，平台执行 responseScript 并按 responseType 写出。分组为物理目录容器，无路由字段。

/{软件名}.application/api/{分组名}.apigroup/{分组名}.apigroup   # 分组元数据（目录型推荐）
/{软件名}.application/api/{分组名}.apigroup/{API名}.api        # API（单文件）
# 历史形态：扁平分组文件 / 无分组 API 直接在 api/ 下，仍可被后缀递归扫描载入

运行匹配靠 HTTP 方法 + Ant 路径模板（不靠文件路径）；requestType 小写写入，匹配忽略大小写。

2. Api（.api）属性表¶

属性	XML 形态	类型	默认	说明
`id`	根属性	string	须生成	`__` + 短 UUID
`name`	子元素	string	—	必填；文件名；同软件不重名
`parentId` / `apiGroup`	子元素	string	—	= 分组 id（无分组历史样例=软件 id）
`status`	子元素	string	published	生命周期；仅 `public` 免登录，其余（published/development/test/abnormal/maintain/abandoned）都要登录；状态不会禁用路由，想下线须删接口或改 URL
`requestType`	子元素	string	get	get/post/put/delete
`requestUrl`	子元素	string	—	必填；以 `/` 开头；可含 `{pathVar}`；不含软件名前缀
`responseType`	子元素	string	json	json/xml/raw/binary
`responseScript`	CDATA	string	—	响应 iScript（接口正文）
`encode`	子元素	string	UTF-8	仅此选项；运行端固定 UTF-8
`tags`	子元素	string	可空	`;` 分隔多标签

responseType 与脚本返回值¶

值	responseScript 应 return	写出
json	Map/Bean/Collection 等对象	application/json
xml	对象	application/xml（JSON→Staxon 转换）
raw	字符串	原文
binary	`java.io.File`	附件下载

3. ApiGroup（.apigroup）¶

极简：id（根属性）、name、parentId（=软件 id）。目录型时目录名 = 元数据文件名。

4. 运行时流程¶

{METHOD} {context}/magic-api/{软件名}{requestUrl}
  → MagicApiController.execute
  → findByRequestUrl(method, path)（AntPathMatcher 抽 {pathVar} 入 params）
  → status≠public 且无登录用户 → 401
  → 执行 responseScript（body 已注入 params._content）
  → 按 responseType 序列化写出

区分：.extinterface 是**出站**外部接口定义；平台内置 /api/runtime/*、/api/designtime/* 不是 workspace 文件。

5. XML 骨架¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Api id="__API_UUID">
  <name>根据id获取部门</name>
  <parentId>__GROUP_UUID</parentId>
  <status>published</status>
  <apiGroup>__GROUP_UUID</apiGroup>
  <encode>UTF-8</encode>
  <requestType>get</requestType>
  <requestUrl>/departments/{departmentId}</requestUrl>
  <tags></tags>
  <responseType>json</responseType>
  <responseScript><![CDATA[(function(){
    var departmentId = getParameter("departmentId");
    // …查库/调工具类…
    return resultMap;
})()]]></responseScript>
</Api>

6. 相关¶

资源	文档
所属软件	[[application-file]]
脚本写法	`agent-skills-usage/skills/iscript-usage/SKILL.md`
生成操作指南	`agent-skills-usage/skills/generate-api-file/SKILL.md`（含全状态表、匹配算法、POST/raw 示例）