接口管理 ★
一句话：把一条 SQL、一份静态 JSON 或一个第三方 HTTP 接口登记成平台统一的「数据接口」，之后表单取数、门户组件、AI 工具、报表统计都按「接口编码」引用它；每次修改自动存版本可回滚，含写操作的接口在列表、测试、删除三处都有醒目拦截。
功能在哪
- 菜单路径：基础设施 → 数据管理 → 接口管理
- 地址栏路由：
/infra/data-manage/data-interface - 主要权限：
infra:data-interface:query（列表/详情）、:create（新增）、:update（配置）、:delete（删除）
界面认识
查询条件：
| 条件 | 说明 |
|---|---|
| 接口名称 / 接口编码 | 模糊匹配 |
| 来源 | 字典「表单类型」：内部（本系统的库/接口）/ 外部（第三方系统） |
| 标签 | 字典「接口标签」：表单取数 / 门户组件 / AI 工具 / 报表统计 / 外部集成 / 通用 |
| 类型 | SQL 查询 / 静态 JSON / HTTP 转发 |
| 含写操作 | 只看会改数据的接口 |
| 动作类型 | 查询 / 新增 / 修改 / 删除 |
列表列：序号、接口名称、接口编码、责任人、来源、标签、类型、动作类型、版本、状态（开关，切换提示「已启用」/「已停用」）、更新时间、更新者、操作。
行内操作：配置、测试、版本，超过四个按钮折进「更多」（日志、删除）；工具栏另有全局「调用日志」。
为什么「动作类型」要手选、不由程序猜
一个接口允许写多条 SQL（如「插主表 + 插子表」），程序无法可靠判断这一组语句整体算什么动作，所以由配置人显式声明。程序解析结果降级为校验依据：选「查询」但 SQL 里有写语句时直接拒绝保存。
常用操作
新建一个 SQL 接口
- 「新增」→ 弹窗标题「新建接口」；
- 填「接口名称」「接口编码」「责任人」，选「类型 = SQL 查询」「来源」「标签」；
- 在「配置」区写 SQL——右侧是表结构树（可按表名/字段/说明搜索，顶部显示「共 N 张表」），点节点即插入；下方「点击插入」提供内置变量标签；
- 需要分页就在「分页设置」里打开「是否分页」（旁注：开启后返回 {total, list} 格式，自动执行 COUNT SQL）；「COUNT SQL」留空即可（旁注：留空时自动生成（推荐））；
- 按需补「入参定义」「后处理脚本」「备注」→「确定」。
编辑已有接口时弹窗标题是「配置接口」，此时「接口编码」禁用（它是所有调用方的引用键），并多出一个「变更说明」输入框，旁注记入版本历史，便于日后追溯。
内置变量（「点击插入」标签，SQL 里直接用）：
| 变量 | 含义 |
|---|---|
#{_userId} | 当前登录用户编号 |
#{_tenantId} | 当前租户编号 |
#{_deptId} | 当前用户部门编号 |
#{pageNo} / #{pageSize} | 当前页码 / 分页大小 |
#{offsetSize} | 偏移量，配合 LIMIT #{offsetSize},#{pageSize} 手写分页 |
业务入参写成 #{参数名}，与「入参定义」里的参数名一一对应；入参每行可填参数名、显示名、类型（STRING / INT / LONG / DECIMAL / BOOLEAN / DATE / DATETIME）、必填、默认值、说明。
在线测试
行内「测试」打开「在线测试 - {接口名称}」面板：填参数 →「执行」，结果区分三块——实际执行的 SQL（变量已替换，排查最有用）、执行结果、条数与耗时；查询类会标注「测试最多返回 100 条」，写操作类显示「影响 N 行」，无返回时显示「（无返回内容）」。
测试不是干跑
含写操作的接口，面板顶部会红字提示：「该接口含写操作，点「执行」会真的改动数据，不是干跑。执行成功即提交，不会回滚；HTTP 类型的请求发出去更收不回来。」 点「执行」还要再过一道「写操作确认」弹窗（接口「{名称}」含写操作，执行后会真实改动数据且不可回滚。确认执行？，按钮「确认执行」/「取消」）。
版本历史与回滚
行内「版本」→「版本历史 - {接口名称}」，列为版本（vN）、变更说明（未填显示「未填写」）、操作人、时间、操作（预览 / 回滚）。页面顶部说明原文：
每次修改前会自动存一份「修改前的配置」，单个接口最多保留 100 个版本（超出自动清理最旧的）。回滚会把该版本的配置写回，回滚本身也会产生新版本，操作全程可追溯。
回滚会二次确认：「确认回滚到版本 v{N} 的配置吗？当前配置会先被存为一个新版本，不会丢失。」，成功提示「回滚成功」。从没改过的接口这里显示「还没有版本记录（首次修改后才会产生）」。
调用日志
两处入口：行内「更多 → 日志」看单个接口（标题「调用日志 - {接口名称}」），工具栏「调用日志」看全局（标题「接口调用日志」，多一个「接口编码」查询项）。
- 调用时间必填，默认近 7 天；不选提示「请选择调用时间区间」，跨度超限提示「调用时间区间不能大于 3 个月，请缩小范围」；
- 其他条件：方式（在线预览 / 接口调用）、结果（成功 / 失败）；
- 列：编号、接口编码、方式（预览 / 调用）、结果、报错原因、条数、耗时、调用人、IP、时间；展开行可看请求参数、实际执行的 SQL、报错原因。
「记录日志」默认是关的
表单里「记录日志」开关默认关闭，旁注写明：默认关闭，防止高频接口写日志影响性能；需要追溯时手动开启。所以新接口查不到调用日志是正常的——先打开这个开关。
停用与删除
- 停用：列表「状态」开关直接切，接口保留但调用方拿不到数据，可随时再启用；
- 删除：确认文案 「确认删除接口「{名称}」吗？版本历史会一并删除，此操作不可恢复。」；若该接口含写操作，会追加一句 「该接口含写操作，删除后依赖它的调用方会立即失败。」
优先停用，别删
接口编码被表单、门户、AI 工具引用，删掉就是让所有引用方立即报错，且版本历史一并消失、无法回滚。确定不再使用时改状态为「停用」。
字段说明
| 字段 | 必填 | 说明与校验提示 |
|---|---|---|
| 接口名称 | 是 | 「接口名称不能为空」 |
| 接口编码 | 是 | 「接口编码不能为空」；格式提示「只允许字母、数字、下划线，且以字母或下划线开头」；编辑态禁用 |
| 责任人 | 否 | 出问题时找谁，建议填 |
| 类型 | 是 | 「类型不能为空」；SQL 查询 / 静态 JSON / HTTP 转发 |
| 来源 | 否 | 内部 / 外部（字典「表单类型」） |
| 标签 | 是 | 「标签不能为空」；决定它在取数场景里怎么被检索 |
| 记录日志 | 否 | 默认关闭 |
| 动作类型 | 是 | 「请选择动作类型」；单选 查询（SELECT）/ 新增（INSERT）/ 修改（UPDATE）/ 删除（DELETE）。旁注：「一个接口可写多条 SQL，请按实际意图选择动作类型。」「非查询动作只返回影响行数，且不能开启分页。」结构变更（DDL）已被策略禁止，不出现在选项里 |
| 配置 | 是 | 「配置不能为空」；随类型切换：SQL 文本 / 静态 JSON 数据 / HTTP 转发配置 |
| 入参定义 | 否 | 参数名、显示名、类型、必填、默认值、说明 |
| 后处理脚本 | 否 | JavaScript；data 为执行结果，return 返回加工后的数据。下方「填入示例」可一键插入把结果转成 { label, value } 下拉结构的样例 |
| 备注 | 否 | 自由说明 |
| 变更说明 | 否 | 仅编辑态，写入版本历史 |
动作类型与 SQL 的双向校验（保存前就会拦住）：
| 情形 | 提示 |
|---|---|
| 选了「查询」但 SQL 里有写语句 | 报错：SQL 中检测到 {INSERT/UPDATE/DELETE} 语句，动作类型不能选「查询」，请改选对应的动作类型。 |
| 选了写动作但 SQL 里没检测到写语句 | 黄色告警：SQL 中未检测到写操作语句，请确认动作类型「{动作}」是否选对。若 SQL 用了存储过程等特殊写法，可忽略此提示。 |
| 选了写动作 | 需勾选风险确认：请勾选「我知晓此接口会{新增/修改/删除}数据」 |
HTTP 转发类型另有地址校验：HTTP 地址不合法：{地址}、禁止访问内网地址({地址})（默认拒绝内网，需显式打开「允许内网地址」），响应超限报 HTTP 响应内容过大。
视角对照
| 视角 | 看到什么 |
|---|---|
超管 admin / 租户管理员 docadmin | 全部接口，可增删改配、回滚、看日志 |
| 只授「查询」的角色 | 只能看列表与配置详情，测试/版本/删除按钮不显示 |
| 套餐未含此菜单的租户 | 侧边栏「数据管理」下没有本页，接口由平台方统一维护 |
| 普通员工 | 无此菜单；接口以「表单取数」「门户组件」等形式间接被使用 |
进阶
- 给 AI 工具当数据源：标签选「AI 工具」的接口可被 Agent 侧当作只读数据能力引用；这类接口务必把动作类型定为「查询」并关闭写操作，避免模型误改数据；
- 手写分页与自动分页：打开「是否分页」后平台自动拼 COUNT 与 LIMIT；若 SQL 本身已含
LIMIT #{offsetSize},#{pageSize}，保持「COUNT SQL」留空让平台自动生成更省事； - 多租户安全：SQL 里显式带上
#{_tenantId}或用平台的租户隔离表，别把跨租户查询写成无条件 SELECT； - 上线节奏：新接口先「停用」状态建好 → 在线测试跑通（只读接口可反复执行）→ 启用 → 补「记录日志」观察一段调用情况；
- 改坏了怎么救：版本 → 预览确认目标版本内容 → 回滚（当前配置也会先存一版，不会丢）。
常见问题
Q：保存时报「SQL 中检测到 UPDATE 语句，动作类型不能选「查询」」？ A：这是刻意拦截，不是误报。把动作类型改成对应动作并勾选风险确认；若你本意只是查询，说明 SQL 写错了。
Q：新建的接口在「调用日志」里查不到记录？ A：「记录日志」默认关闭。到配置里打开后再调用才会记录；另外调用时间区间必填且不超过 3 个月。
Q：在线测试能返回，但表单里取不到数？ A：先确认接口「状态」是启用；再看测试面板「实际执行的 SQL」与表单实际传参是否一致——测试最多返回 100 条，正式调用受分页参数影响。
Q：动作类型选了写操作，为什么返回只有「影响 N 行」？ A：设计如此：非查询动作只返回影响行数，且不能开启分页。需要返回数据请拆成两个接口（一个写、一个查）。
Q：接口编码能改吗？ A：编辑态该字段禁用。它是所有调用方的引用键，改了等于换接口——请新建一个。
Q：HTTP 转发填内网地址报「禁止访问内网地址」？ A：默认策略拒绝内网以防 SSRF。确有内网服务需要转发，在 HTTP 配置里显式打开「允许内网地址」。