217 lines
4.9 KiB
Markdown
217 lines
4.9 KiB
Markdown
# 参数配置
|
||
|
||
## 参数定义 (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}
|
||
```
|