Files
2026-05-18 09:28:15 +08:00

7.9 KiB
Raw Permalink Blame History

常见问题与解决方案

错误:map is null

原因

数据操作API期望格式 {"data": "<json字符串>"},但传入格式不正确。

解决方案

AIBridge的execute方法已内置处理:

result = di.execute(di_id, {"param": "value"})

预览时NPE (NullPointerException)

原因

isPostPosition 设置为 1,导致 handlePostVariate 方法中拆箱异常。

解决方案

创建接口时确保 isPostPosition = 0

payload = DataInterfaceAPI.build_payload(
    ...
    # 不要设置 isPostPosition
)
# AIBridge 已强制设为 0

execute() 返回空列表

原因

execute() 方法内部使用 sourceType=1,如果 DI 配置了 defaultValue,会使用默认值而非传入值。

解决方案

AIBridge 已修复此问题,execute() 现在内部使用 sourceType=3,参数值直接传递:

# 现在正常返回数据
result = di.execute(di_id, {"parentId": "0"})

SQL中{}被解析为占位符

原因

SQL字面量中包含 {} 会被当作参数占位符解析。

错误示例

SELECT * FROM table WHERE json = '{}'

正确示例

SELECT * FROM table WHERE json = '''{}'''
-- 或
SELECT * FROM table WHERE json = '"{}"'

预览返回空数据

可能原因

  1. 参数值不正确
  2. SQL条件无匹配数据
  3. 多租户环境下dbLinkId配置错误
  4. sourceType=1 使用了 DI 中的 defaultValue,导致实际参数与预期不符

排查步骤

# 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 直接使用传入的参数值 ❌ 否
# 示例:DI 配置 defaultValue="-1"
# sourceType=1: 使用 -1(忽略传入的值)
# sourceType=3: 使用传入的值

敏感词校验失败

原因

接口名或SQL包含敏感词。

错误信息

MsgCode.SYS006.get(containsSensitive)

解决方案

修改接口名称或SQL,避免敏感词。

增删改不返回数据

正常行为

action=1(增)/2(改)/4(删) 执行后返回空列表,不返回数据。

验证方式

result = di.preview(di_id, {})
print(result.code)  # 200 表示成功

分页不生效

可能原因

  1. hasPage 未设为 1
  2. 数量统计SQL未配置
  3. 分页变量使用错误

正确配置

{
  "dataConfigJson": {
    "sqlData": {"sql": "SELECT * FROM table LIMIT @offsetSize, @pageSize"}
  },
  "dataCountJson": {
    "sqlData": {"sql": "SELECT COUNT(*) FROM table"}
  }
}

接口未找到

可能原因

  1. 接口ID错误
  2. 接口已被删除
  3. 多租户数据隔离

解决方案

# 重新获取接口列表
resp = di.get_selector()
for item in resp.data:
    print(item.get('id'), item.get('fullName'))

参数类型验证失败

原因

传入的参数值与定义的dataType不匹配。

错误示例

# 定义为int,传入了字符串
{"field": "age", "dataType": "int", "defaultValue": "abc"}

正确示例

{"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返回的数据格式是否符合脚本预期

示例排查

// 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包装可能出错的代码

安全写法示例

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:
{
  "field": "text",
  "dataType": "varchar",
  "required": 1,
  "defaultValue": "默认值"
}
  1. 调用时使用 sourceType=3:
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配置:

# 错误:使用小写下划线
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:

# 获取业务库的 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执行(必须正确)