Files
aibridge/docs/datainterface/06-parameters.md
T
2026-05-18 09:28:15 +08:00

4.9 KiB
Raw Blame History

参数配置

参数定义 (parameterJson)

参数结构

[
  {
    "field": "参数名",
    "fieldName": "中文名",
    "dataType": "varchar",
    "required": 0,
    "sourceType": 1,
    "defaultValue": "默认值"
  }
]

字段说明

字段 类型 说明
field string 参数名称,用于SQL占位符{field}
fieldName string 参数中文名
dataType string 数据类型: varchar/int/datetime/decimal
required int 是否必填: 0=否, 1=是
sourceType int 来源类型
defaultValue string 默认值

sourceType 类型

值 名称 说明 行为
1 字段 使用defaultValue 直接使用 DI 中配置的默认值
2 自定义 使用relationField 从其他接口获取
3 空值 推荐使用:参数值直接替换,最可靠 直接使用传入的值,忽略默认值
4 系统参数 使用系统变量 从系统获取

重要区别:

  • sourceType=1:受 DI 中配置的 defaultValue 影响,如果 DI 没配默认值则可能不生效
  • sourceType=3:直接使用传入的参数值,不受 defaultValue 影响
  • AIBridge execute() 内部使用 sourceType=3,适合需要覆盖默认行为的场景

dataType 类型

值 说明 验证规则
varchar 字符串 无
int 整数 必须为整数
datetime 日期时间 yyyy-MM-dd HH:mm:ss
decimal 浮点数 必须为数字

参数验证

后端自动验证:

  1. 必填检查:required=1时,参数值不能为空
  2. 类型检查:根据dataType验证格式

SQL中使用参数

-- 简单参数(自定义参数)
SELECT * FROM table WHERE field = {paramName}

-- IN查询
SELECT * FROM table WHERE field IN ({paramName})
-- 参数值应为逗号分隔: "1,2,3"

-- 模糊查询
SELECT * FROM table WHERE name LIKE CONCAT('%', {name}, '%')

SQL占位符格式说明

⚠️ 重要发现:官方DI中存在两种参数格式:

-- 格式1: 自定义参数 {paramName}
-- 用于前端传递的参数

-- 格式2: 系统变量 {@userId}, {@organizeId}
-- 用于自动获取当前用户/组织信息

-- 格式3: 分页变量 {@pageSize}, {@offsetSize}, {@currentPage}
SELECT * FROM table LIMIT {@offsetSize}, {@pageSize}

系统变量参数

-- 用户ID
SELECT * FROM base_user WHERE f_id = {@userId}

-- 组织ID
SELECT * FROM base_organize WHERE f_id = {@organizeId}

-- 雪花ID
INSERT INTO table (f_id) VALUES ({@snowFlakeID})

-- 批量雪花ID (用于批量插入)
INSERT INTO table (f_id, f_name) VALUES ({@lotSnowID}, 'name1')

参数传递示例

AIBridge execute方法

# 执行带参数的接口(内部使用 sourceType=3)
result = di.execute(di_id, {
    "userId": "123",
    "name": "张三"
})

Preview直接传递

# sourceType=1: 使用 DI 中配置的 defaultValue
result = di.preview(di_id, {
    "paramList": [
        {
            "field": "userId",
            "defaultValue": "123",
            "dataType": "varchar",
            "sourceType": 1  # 受 defaultValue 影响
        }
    ]
})

# sourceType=3: 直接使用传入的值,忽略 defaultValue
result = di.preview(di_id, {
    "paramList": [
        {
            "field": "userId",
            "defaultValue": "123",  # 会被忽略
            "dataType": "varchar",
            "sourceType": 3  # 直接用传入的值
        }
    ]
})

execute() vs preview() 区别

特性 execute() preview()
参数格式 {"key": "value"} {"paramList": [...]}
sourceType 固定为 3 可手动指定
defaultValue 被忽略 sourceType=1 时生效
适用场景 需要覆盖默认行为 需要使用 DI 默认值

参考示例

ID 名称 参数
420587863533428357 行政区划 parentId
469493539378625157 下拉多参_字段列表 name, gender
469493805800815237 区域下拉补全_字段列表 name

行政区划参数示例

[
  {
    "field": "parentId",
    "fieldName": "上级",
    "dataType": "varchar",
    "required": 0,
    "sourceType": 1,
    "defaultValue": "0"
  }
]

下拉多参示例

[
  {
    "field": "name",
    "fieldName": "姓名",
    "dataType": "varchar",
    "required": 0,
    "sourceType": 1,
    "defaultValue": ""
  },
  {
    "field": "gender",
    "fieldName": "性别",
    "dataType": "int",
    "required": 0,
    "sourceType": 1,
    "defaultValue": ""
  }
]

特殊参数

searchSqlStr - 高级搜索

-- 使用searchSqlStr进行动态条件拼接
SELECT * FROM base_user WHERE 1=1 {searchSqlStr}
-- searchSqlStr 格式: "f_name='张三' AND f_status=1"
-- values格式: ["张三"]

showKey/showValue - 回显参数

用于表单详情回显:

SELECT * FROM table WHERE f_id = {showValue}