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

217 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 参数配置
## 参数定义 (parameterJson)
### 参数结构
```json
[
{
"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中使用参数
```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中存在两种参数格式:
```sql
-- 格式1: 自定义参数 {paramName}
-- 用于前端传递的参数
-- 格式2: 系统变量 {@userId}, {@organizeId}
-- 用于自动获取当前用户/组织信息
-- 格式3: 分页变量 {@pageSize}, {@offsetSize}, {@currentPage}
SELECT * FROM table LIMIT {@offsetSize}, {@pageSize}
```
## 系统变量参数
```sql
-- 用户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方法
```python
# 执行带参数的接口(内部使用 sourceType=3)
result = di.execute(di_id, {
"userId": "123",
"name": "张三"
})
```
### Preview直接传递
```python
# 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 |
### 行政区划参数示例
```json
[
{
"field": "parentId",
"fieldName": "上级",
"dataType": "varchar",
"required": 0,
"sourceType": 1,
"defaultValue": "0"
}
]
```
### 下拉多参示例
```json
[
{
"field": "name",
"fieldName": "姓名",
"dataType": "varchar",
"required": 0,
"sourceType": 1,
"defaultValue": ""
},
{
"field": "gender",
"fieldName": "性别",
"dataType": "int",
"required": 0,
"sourceType": 1,
"defaultValue": ""
}
]
```
## 特殊参数
### searchSqlStr - 高级搜索
```sql
-- 使用searchSqlStr进行动态条件拼接
SELECT * FROM base_user WHERE 1=1 {searchSqlStr}
-- searchSqlStr 格式: "f_name='张三' AND f_status=1"
-- values格式: ["张三"]
```
### showKey/showValue - 回显参数
用于表单详情回显:
```sql
SELECT * FROM table WHERE f_id = {showValue}
```