单表模式

单表模式用二维表格勾选字段与条件，平台自动生成 SQL。适合不熟悉 SQL 的业务人员快速开发标准查询接口。

创建步骤

1. 进入【工作台】，点击「单表模式」。
2. 选择数据源与 Schema。
3. 选择数据表，平台自动加载字段名、类型、描述。
4. 在字段表格中勾选：

勾选类型	作用
条件参数	生成请求参数，用于 WHERE 过滤
返回参数	生成 SELECT 字段与响应字段
排序字段	进入排序列表，可选择升序/降序

5. 在右侧面板确认参数类型、必填、示例与描述。
6. 测试通过后保存并发布。

生成逻辑

页面勾选会转换为 SQL：

SELECT id, order_no, amount, status
FROM orders
WHERE status = #{status}
  AND created_at >= #{startTime}
ORDER BY created_at DESC

• 条件参数自动填充到右侧请求参数面板，不支持自定义新增。
• 返回参数与右侧返回参数面板联动。
• 字段描述来自数据库注释。
• 排序字段支持多字段，按页面顺序生成 ORDER BY。
• 条件参数的操作符默认 =；需要 like、范围比较或 in 多值时，在「过滤条件配置」中调整，见下文。

过滤条件可视化配置

勾选「条件参数」只会生成等值条件。要配置 like、>=、in 等过滤方式，使用「过滤条件配置」弹窗。

打开方式

1. 选择数据表后，在「选择参数」卡片头部点击「过滤条件配置」。
2. 弹窗中增删改条件，点击「确定」后写回请求参数列表；点击「取消」不保留任何改动。

入口禁用条件

未选择数据表，或接口类型不是查询（insert / delete）时入口置灰——只有查询接口才生成 WHERE，其他类型配了也不会生效。

可配置项

列	说明
过滤字段	从当前表字段中选择，支持搜索；下拉项展示「字段名 备注」
参数名	默认由字段名驼峰化生成，可手动修改
操作符	=、!=、>、>=、<、<=、like、not like、in、not in
参数类型	String、Int、Float、Date、Array、Boolean，选字段时按列类型自动映射
必填	默认关闭，生成 <if> 条件，不传即忽略；开启后为硬条件，必须传参
默认值	参数默认值，可为空
示例值	仅用于文档与测试填充；in 多值用英文逗号分隔
删除	移除该过滤条件，同时移除对应请求参数

操作符与生成规则

操作符	生成的 WHERE 片段
= / != / > / >= / < / <=	col>=#{param} 等比较表达式
like / not like	col like concat('%', concat(#{param}, '%'))
in / not in	col in <foreach collection="param" item="item" open="(" separator="," close=")">#{item}</foreach>

• 参数值一律以 #{} 预编译，只有字段名来自表元数据，不会拼接用户输入。
• 多条条件按列表顺序以 and 连接；首条为可选条件且未传参时，由 <where> 自动剥离前导 and。
• 数值类型（Int / Float / Double / Boolean）的非必填条件只判断 null，传 0 不会被丢弃。

联动与校验规则

• 与请求参数抽屉联动：弹窗与抽屉编辑同一批参数。弹窗改参数名、类型、必填、默认值后抽屉同步；抽屉改参数名后弹窗同步显示。
• 操作符只在弹窗维护：请求参数抽屉中操作符为只读展示，避免两处编辑冲突。
• 参数名规则：仅支持中文、英文、数字、下划线，且不能以数字开头；同一接口内不能重名；pageNum / pageSize 为分页保留名，未开启分页时不可占用。
• in / not in 与 Array 强绑定：选 in / not in 时参数类型自动切为 Array；Array 类型只能配 =、in、not in，切回标量类型时操作符自动回落 =。
• 行内校验：参数名为空、非法或重名，未选过滤字段，in 配非 Array 时对应行标红，且「确定」禁用并给出原因。
• 分页参数不参与：pageNum / pageSize 不出现在过滤条件列表中。
• 非关系型数据源：MongoDB、Elasticsearch 等数据源操作符锁定 =，其余操作符在保存时会被拒绝。

与结果预览的关系

「结果预览」只执行「表结构 + 数据抽样」，不包含过滤条件，因此预览数据不受过滤条件影响。验证过滤效果请点击【测试】，在 Query 中填写参数后调用。

生成示例

条件：status =（必填）、amount >=、order_no like、tenant_id in：

SELECT id, order_no, amount, status
FROM orders
<where>
  status = #{status}
  and amount >= #{minAmount}
  and order_no like concat('%', concat(#{orderNo}, '%'))
  and tenant_id in
  <foreach collection="tenantId" item="item" open="(" separator="," close=")">
    #{item}
  </foreach>
</where>

参数与分页

单表模式的请求参数来自勾选的条件字段：

• 参数位置默认 Query，可按需调整。
• 类型由字段类型推断，需人工确认。
• 勾选分页后，调用方必须传 pageNum、pageSize。
• pageSize 上限 1000。

能力边界

项目	限制
操作类型	仅支持查询；插入/修改/删除不在单表模式提供
请求方式	不提供 PUT / PATCH / DELETE
表数量	仅支持单表，不支持 JOIN
自定义 SQL	不支持；复杂查询请使用脚本模式
ElasticSearch	请求方式与操作类型进一步收窄，以页面可选项为准
过滤操作符	仅查询接口可配置；MongoDB / Elasticsearch 等非关系型数据源仅支持 =
条件组合	多个条件固定以 and 连接，不支持 or 与括号分组
参数	不能自定义新增，只能来自勾选字段

何时改用脚本模式

需要多表关联、聚合、子查询、动态条件、批量写入或存储过程时，请使用 SQL 脚本模式。

测试与发布

单表接口同样支持：

• 在线测试：按参数位置填写 Query / Body / Header。
• 测试用例：保存请求快照并回归。
• Mock：无真实数据时模拟响应。
• 发布到环境、版本管理与同步。

发布流程与脚本模式一致，详见 工作台概览。

常见问题

现象	原因	处理
字段没有描述	数据库未维护注释	在返回参数中手动补充描述
查询结果为空	条件参数未传或类型不匹配	检查必填与参数类型
无法选择插入/修改	单表模式仅支持查询	改用脚本模式
排序不生效	未勾选排序字段或方向未设置	在排序列表中确认
参数无法新增	单表模式参数与字段联动	使用脚本模式或调整表字段
「过滤条件配置」按钮置灰	未选择数据表，或接口类型不是查询	先选择数据表；插入/删除接口请用脚本模式
配了 like / >= 不生效	数据源为非关系型，或接口不是查询类型	非关系型仅支持 =；确认接口类型为查询
预览里看不到过滤效果	结果预览不执行 WHERE	用【测试】填写参数验证
保存时提示参数名非法	参数名含空格、点号、横线或以数字开头	改为中文、英文、数字、下划线组合
保存时提示参数名重复	与已有请求参数或分页参数同名	修改参数名或在弹窗中删除重复条件

相关阅读

• SQL 脚本模式
• 接口定义
• 数据插件