354 lines
7.9 KiB
Markdown
354 lines
7.9 KiB
Markdown
# 常见问题与解决方案
|
||
|
||
## 错误:map is null
|
||
|
||
### 原因
|
||
数据操作API期望格式 `{"data": "<json字符串>"}`,但传入格式不正确。
|
||
|
||
### 解决方案
|
||
AIBridge的`execute`方法已内置处理:
|
||
```python
|
||
result = di.execute(di_id, {"param": "value"})
|
||
```
|
||
|
||
## 预览时NPE (NullPointerException)
|
||
|
||
### 原因
|
||
`isPostPosition` 设置为 1,导致 `handlePostVariate` 方法中拆箱异常。
|
||
|
||
### 解决方案
|
||
创建接口时确保 `isPostPosition = 0`
|
||
|
||
```python
|
||
payload = DataInterfaceAPI.build_payload(
|
||
...
|
||
# 不要设置 isPostPosition
|
||
)
|
||
# AIBridge 已强制设为 0
|
||
```
|
||
|
||
## execute() 返回空列表
|
||
|
||
### 原因
|
||
`execute()` 方法内部使用 `sourceType=1`,如果 DI 配置了 `defaultValue`,会使用默认值而非传入值。
|
||
|
||
### 解决方案
|
||
AIBridge 已修复此问题,`execute()` 现在内部使用 `sourceType=3`,参数值直接传递:
|
||
|
||
```python
|
||
# 现在正常返回数据
|
||
result = di.execute(di_id, {"parentId": "0"})
|
||
```
|
||
|
||
## SQL中{}被解析为占位符
|
||
|
||
### 原因
|
||
SQL字面量中包含 `{}` 会被当作参数占位符解析。
|
||
|
||
### 错误示例
|
||
```sql
|
||
SELECT * FROM table WHERE json = '{}'
|
||
```
|
||
|
||
### 正确示例
|
||
```sql
|
||
SELECT * FROM table WHERE json = '''{}'''
|
||
-- 或
|
||
SELECT * FROM table WHERE json = '"{}"'
|
||
```
|
||
|
||
## 预览返回空数据
|
||
|
||
### 可能原因
|
||
1. 参数值不正确
|
||
2. SQL条件无匹配数据
|
||
3. 多租户环境下dbLinkId配置错误
|
||
4. **sourceType=1 使用了 DI 中的 defaultValue**,导致实际参数与预期不符
|
||
|
||
### 排查步骤
|
||
```python
|
||
# 1. 使用 sourceType=3 直接传递参数值
|
||
result = di.preview(di_id, {
|
||
"paramList": [
|
||
{"field": "paramName", "defaultValue": "test", "dataType": "varchar", "sourceType": 3}
|
||
]
|
||
})
|
||
|
||
# 2. 使用 execute() 方法(内部自动用 sourceType=3)
|
||
result = di.execute(di_id, {"paramName": "test"})
|
||
|
||
# 3. 检查dbLinkId
|
||
# 主库: "0"
|
||
# 业务库: 查看数据连接ID
|
||
```
|
||
|
||
### sourceType=1 vs sourceType=3
|
||
|
||
| sourceType | 行为 | 受 defaultValue 影响 |
|
||
|------------|------|---------------------|
|
||
| 1 | 使用 DI 中配置的 defaultValue | ✅ 是 |
|
||
| 3 | 直接使用传入的参数值 | ❌ 否 |
|
||
|
||
```python
|
||
# 示例:DI 配置 defaultValue="-1"
|
||
# sourceType=1: 使用 -1(忽略传入的值)
|
||
# sourceType=3: 使用传入的值
|
||
```
|
||
|
||
## 敏感词校验失败
|
||
|
||
### 原因
|
||
接口名或SQL包含敏感词。
|
||
|
||
### 错误信息
|
||
```
|
||
MsgCode.SYS006.get(containsSensitive)
|
||
```
|
||
|
||
### 解决方案
|
||
修改接口名称或SQL,避免敏感词。
|
||
|
||
## 增删改不返回数据
|
||
|
||
### 正常行为
|
||
action=1(增)/2(改)/4(删) 执行后返回空列表,不返回数据。
|
||
|
||
### 验证方式
|
||
```python
|
||
result = di.preview(di_id, {})
|
||
print(result.code) # 200 表示成功
|
||
```
|
||
|
||
## 分页不生效
|
||
|
||
### 可能原因
|
||
1. hasPage 未设为 1
|
||
2. 数量统计SQL未配置
|
||
3. 分页变量使用错误
|
||
|
||
### 正确配置
|
||
```json
|
||
{
|
||
"dataConfigJson": {
|
||
"sqlData": {"sql": "SELECT * FROM table LIMIT @offsetSize, @pageSize"}
|
||
},
|
||
"dataCountJson": {
|
||
"sqlData": {"sql": "SELECT COUNT(*) FROM table"}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 接口未找到
|
||
|
||
### 可能原因
|
||
1. 接口ID错误
|
||
2. 接口已被删除
|
||
3. 多租户数据隔离
|
||
|
||
### 解决方案
|
||
```python
|
||
# 重新获取接口列表
|
||
resp = di.get_selector()
|
||
for item in resp.data:
|
||
print(item.get('id'), item.get('fullName'))
|
||
```
|
||
|
||
## 参数类型验证失败
|
||
|
||
### 原因
|
||
传入的参数值与定义的dataType不匹配。
|
||
|
||
### 错误示例
|
||
```python
|
||
# 定义为int,传入了字符串
|
||
{"field": "age", "dataType": "int", "defaultValue": "abc"}
|
||
```
|
||
|
||
### 正确示例
|
||
```python
|
||
{"field": "age", "dataType": "int", "defaultValue": "25"}
|
||
```
|
||
|
||
## DI预览无法访问业务表
|
||
|
||
### 原因
|
||
多租户环境下,`dbLinkId=0` 连接主库,部分业务表仅在租户库中。
|
||
|
||
### 解决方案
|
||
使用业务数据库连接ID而非"0"。
|
||
|
||
## 执行时间过长
|
||
|
||
### 可能原因
|
||
1. 查询数据量过大
|
||
2. 缺少索引
|
||
3. 网络延迟
|
||
|
||
### 优化建议
|
||
1. 添加分页限制
|
||
2. 添加查询条件减少数据量
|
||
3. 使用explain分析SQL性能
|
||
|
||
## 接口验证失败(dataExceptionJson返回false)
|
||
|
||
### 原因
|
||
API接口的异常验证脚本返回了 `false`,触发重试机制(最多3次)。
|
||
|
||
### 错误码说明
|
||
| 错误码 | 含义 |
|
||
|--------|------|
|
||
| SYS121 | HTTP调用失败(连接超时、响应错误等) |
|
||
| SYS122 | API返回结果为空 |
|
||
| SYS123 | JS脚本执行异常 |
|
||
|
||
### 排查步骤
|
||
1. 检查API是否可正常访问
|
||
2. 检查dataExceptionJson脚本逻辑是否正确
|
||
3. 查看后端日志中的错误码信息
|
||
4. 确认API返回的数据格式是否符合脚本预期
|
||
|
||
### 示例排查
|
||
|
||
```javascript
|
||
// dataExceptionJson 脚本示例
|
||
var result = responseObj;
|
||
if (result && result.code === 200 && result.data) {
|
||
return true;
|
||
}
|
||
return false; // 失败重试
|
||
```
|
||
|
||
如果持续失败,检查:
|
||
- API服务是否正常运行
|
||
- 网络连接是否稳定
|
||
- 返回数据格式是否与脚本预期一致
|
||
|
||
## JS脚本异常(SYS123)
|
||
|
||
### 原因
|
||
dataExceptionJson或dataJsJson脚本执行出错。
|
||
|
||
### 常见错误
|
||
1. 变量名与返回结果不匹配
|
||
2. 数组越界访问
|
||
3. 语法错误
|
||
4. 使用了不支持的JS语法
|
||
|
||
### 排查步骤
|
||
1. 检查JS语法是否正确
|
||
2. 确认脚本中的变量名与返回结果字段匹配
|
||
3. 使用try-catch包装可能出错的代码
|
||
|
||
### 安全写法示例
|
||
|
||
```javascript
|
||
try {
|
||
var list = data;
|
||
if (!list || !Array.isArray(list)) {
|
||
return data;
|
||
}
|
||
for (var i = 0; i < list.length; i++) {
|
||
if (list[i].f_real_name) {
|
||
list[i].fullName = list[i].f_real_name;
|
||
}
|
||
}
|
||
return list;
|
||
} catch (e) {
|
||
return data; // 出错时返回原始数据
|
||
}
|
||
```
|
||
|
||
## POST 接口必填参数校验失败
|
||
|
||
### 原因
|
||
API 接口的必填参数(`required=1`)在 DI 中没有配置 `defaultValue`,且传入的 `defaultValue` 为 `null` 时校验失败。
|
||
|
||
### 错误信息
|
||
```
|
||
text不能为空
|
||
```
|
||
|
||
### 解决方案
|
||
|
||
1. **创建 DI 时设置 defaultValue**:
|
||
```json
|
||
{
|
||
"field": "text",
|
||
"dataType": "varchar",
|
||
"required": 1,
|
||
"defaultValue": "默认值"
|
||
}
|
||
```
|
||
|
||
2. **调用时使用 sourceType=3**:
|
||
```python
|
||
result = di.preview(di_id, {
|
||
'paramList': [
|
||
{'field': 'text', 'defaultValue': '标题', 'dataType': 'varchar', 'sourceType': 3},
|
||
{'field': 'body', 'defaultValue': '内容', 'dataType': 'varchar', 'sourceType': 3},
|
||
]
|
||
})
|
||
```
|
||
|
||
## DI执行失败 "Interface request failed"
|
||
|
||
### 原因
|
||
SQL查询的表字段名与实际数据库不符。
|
||
|
||
### 错误日志
|
||
```
|
||
Unknown column 'f_enterprise_name' in 'field list'
|
||
```
|
||
|
||
### 排查方法
|
||
1. 查看后端日志 `log/jnpf-java-boot/log_error.log`
|
||
2. 使用 `SELECT * FROM table LIMIT 1` 获取实际字段名
|
||
3. 注意JNPF业务表字段可能是大写(如 `F_Company_Name`)而非小写(`f_company_name`)
|
||
|
||
### 解决方案
|
||
确认实际字段名后更新DI的SQL配置:
|
||
```python
|
||
# 错误:使用小写下划线
|
||
sql = "SELECT f_enterprise_name FROM opportunity_mgmt"
|
||
|
||
# 正确:使用实际字段名(大写)
|
||
sql = "SELECT F_Company_Name FROM opportunity_mgmt"
|
||
```
|
||
|
||
### 常见JNPF表字段命名规律
|
||
| 表类型 | 字段命名 | 示例 |
|
||
|--------|----------|------|
|
||
| JNPF系统表 | snake_case | f_id, f_full_name |
|
||
| 业务表(VisualDev) | PascalCase | F_Id, F_Company_Name |
|
||
|
||
可通过 `SELECT * FROM table LIMIT 1` 查看实际命名。
|
||
|
||
## dbLinkId 配置错误导致查询失败
|
||
|
||
### 原因
|
||
业务库的表不在主库(0)中,配置错误导致找不到表。
|
||
|
||
### 解决方案
|
||
配置正确的业务库 db_link_id:
|
||
```python
|
||
# 获取业务库的 db_link_id(不是 "0")
|
||
db_link_id = config.db_link_id # 如 "2042386207729803264"
|
||
|
||
update_data = {
|
||
"id": di_id,
|
||
"dbLinkId": db_link_id, # 不是 "0"
|
||
"dataConfigJson": json.dumps({
|
||
"sqlData": {
|
||
"dbLinkId": db_link_id, # 放在 sqlData 中
|
||
"sql": "SELECT * FROM business_table"
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
### dbLinkId 层级关系
|
||
```
|
||
顶层 dbLinkId: 用于接口列表查询筛选
|
||
└── dataConfigJson.sqlData.dbLinkId: 用于实际SQL执行(必须正确)
|
||
```
|