# 参数配置 ## 参数定义 (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} ```