跳到主要内容

SQL 脚本模式

脚本模式通过编写 SQL 定义接口，适合复杂查询、动态条件、批量写入与存储过程。平台使用 MyBatis 风格的参数绑定与动态标签。

创建接口​

  1. 进入【工作台】。
  2. 点击「脚本模式」。
  3. 选择数据源与 Schema。
  4. 编写 SQL，点击【解析】提取参数与返回字段。
  5. 在右侧面板完善基本信息、请求参数与返回参数。
  6. 测试通过后保存并发布。

支持的语句​

语句说明
SELECT查询，支持分页
INSERT插入，可结合 <foreach> 批量写入
UPDATE更新
DELETE删除
CALL调用存储过程（依数据源支持情况）

写操作建议在基本信息中开启 事务，确保多脚本操作的一致性。

参数占位符​

写法说明
#{name}预编译参数，按类型绑定，推荐使用

示例：

SELECT id, order_no, amount
FROM orders
WHERE order_no = #{orderNo}
  AND status = #{status}

参数类型支持 String、Array、Int、Float、Object。数组参数在 SQL 中通常配合 <foreach> 使用。

动态标签​

支持 MyBatis 标准标签：

标签用途
<if>条件拼接
<where>自动处理 WHERE 与前导 AND/OR
<set>自动处理 SET 与尾逗号
<foreach>遍历集合，用于 IN 查询或批量插入
<choose> / <when> / <otherwise>多分支选择
<trim>自定义前后缀裁剪

if + where​

SELECT id, order_no, amount, status
FROM orders
<where>
  <if test="status != null and status != ''">
    AND status = #{status}
  </if>
  <if test="startTime != null">
    AND created_at &gt;= #{startTime}
  </if>
</where>
ORDER BY created_at DESC

foreach 查询​

SELECT id, user_name
FROM sys_user
WHERE id IN
<foreach collection="userIds" item="id" open="(" separator="," close=")">
  #{id}
</foreach>

foreach 批量插入​

INSERT INTO orders (order_no, amount, status)
VALUES
<foreach collection="orders" item="item" separator=",">
  (#{item.orderNo}, #{item.amount}, #{item.status})
</foreach>

大于小于符号​

当 SQL 同时使用 >、< 与 <if> 等标签时，XML 解析会冲突，需要转义：

<if test="amount != null">
  AND amount &lt; #{amount}
</if>

也可以使用 CDATA：

<![CDATA[
AND amount < #{amount}
]]>

只使用 >、< 而没有使用动态标签时，通常不需要转义。

参数解析​

点击【解析】后，平台会扫描 SQL 中的 #{} 参数并生成请求参数草稿，同时尝试解析 SELECT 返回字段。

  • INSERT、UPDATE、DELETE 不支持自动解析返回字段，需要手动添加。
  • 解析结果需要人工确认类型、必填与描述。
  • 自定义参数可直接点击【+】添加。
  • 表格模式与代理模式的参数来源不同，不要混用。

分页​

在请求参数中勾选分页后，调用方必须传 pageNum、pageSize；缺失返回 41010。

  • pageSize 上限为 1000。
  • 分页参数由平台统一处理，不要在 SQL 中重复写 LIMIT。
  • 如果业务 SQL 自带分页，请关闭平台分页，避免双重分页。

事务​

多脚本写操作建议开启事务：

  • 同一接口内的多条 SQL 在事务中执行，任一失败回滚。
  • 代理与编排模式的事务语义不同，不要假设跨服务事务。
  • 存储过程内部事务由数据库控制。

非关系型数据源​

ElasticSearch、Hive 等数据源的限制：

  • 不支持完整标准 SQL，平台只做常见语法转换。
  • 不支持 <if> 等动态标签。
  • 表名/字段名包含 - 等特殊字符时使用英文双引号，例如 "test-a"。
  • 分页、聚合与函数支持范围以驱动实现为准。

常见错误​

错误码原因
40011SQL 执行失败，检查语法与表字段
40014特殊字符未加双引号
41010开启分页但未传分页参数
41011参数名使用了运行态保留字
41012使用了不允许的 SQL 插值参数

相关阅读​