普元数据资产管理平台

# 数据服务-接口开发问题排查指南

# 排查指南详细说明

通用前置检查：

# 场景一：服务发布/提交失败

  • 问题现象：
    1. 点击“发布”按钮后无响应或报错。
    2. 服务发布时提示“服务编码已存在”或校验失败。
    3. 结果集服务发布时，SQL验证不通过。
    4. 发布到ESB失败或接口返回已发布。
  • 排查步骤：
    1. 第一步：排除产品BUG。
      • 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 发布、提交、服务生成。
      • 相关补丁：
        • DAMP 7.3.1: DAMP_7.3.1_DATAENGINE_20250730_P1 (解决达梦数据源text字段测试报错)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250411_P1 (解决设置必填参数不生效)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250424_P1 (解决接口测试报错)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250425_P1 (解决count接口数据为空时报错)
      • 解决方案：若找到描述匹配的补丁，则申请并应用。
    2. 第二步：检查SQL语句规范（结果集服务）。
      • 操作：检查自定义SQL语句。
      • 排查项：
        • SQL结尾是否包含分号;。结果集服务会在自定义SQL外拼装SQL，因此自定义SQL结尾不能有分号。
        • SQL中是否包含数据库特定的语法，如Oracle的rownum、sysdate等。
      • 解决方案：
        • 删除SQL结尾的分号。
        • 在数据库客户端（如PL/SQL Developer、DBeaver）中先验证SQL执行是否正常。
    3. 第三步：检查数据源配置。
      • 操作：确认服务绑定的数据源配置是否正确。
      • 排查项：
        • 数据源URL、用户名、密码是否正确。
        • 对于达梦数据库，注意用户名与Schema的对应关系。如果用户名不是Schema的所有者，需要在URL中指定Schema。
        • 数据源连接测试是否通过。
      • 解决方案：
        • 在“系统管理”中找到对应的数据源，点击“连接测试”。
        • 修正数据源配置后，重新发布服务。
    4. 第四步：检查服务编码唯一性。
      • 操作：确认服务编码是否唯一。
      • 排查项：服务编码只能包含英文/数字，且在平台内唯一。
      • 解决方案：修改服务编码，使用未被占用的编码。
    5. 第五步：检查ESB发布问题。
      • 操作：如果发布到ESB失败。
      • 排查项：服务创建新版本后，调用ESB接口返回“接口已发布”。
      • 解决方案：
        • 这是产品设计，避免存在ESB手动删除的情况。接口存在则默认不需要再推送，不影响平台正常使用。
        • 如果确实需要重新推送，可以手动在ESB端删除原接口后，在DAMP中重新发布。

# 场景二：接口测试报错

  • 问题现象：

    1. 测试接口返回500内部错误。
    2. 测试接口报空指针异常。
    3. 测试接口报SQL执行错误。
    4. 测试接口超时或连接失败。
    5. 分页查询无效（pageNumber参数不生效）。

  • 排查步骤：

    1. 第一步：排除产品BUG。

      • 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 测试、500、空指针、分页。
      • 相关补丁：
        • DAMP 7.3.1: DAMP_7.3.1_DATAENGINE_20250324_C1 (解决星环大数据hive分页参数不好使)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250424_P1 (解决接口测试报错)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250425_P1 (解决count接口数据为空时报错)
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250728_C1 (解决pg版本问题导致分页查询错)
      • 解决方案：若找到描述匹配的补丁，则申请并应用。

    2. 第二步：检查服务引擎状态。

      • 操作：当测试接口报500错误时。
      • 排查项：
        • 服务引擎（dataEngine）是否正常启动。
        • 服务引擎日志（logs/api.log）中是否有详细错误信息。
        • 服务引擎与DAMP后端的网络连接是否正常。
      • 解决方案：
        • 重启服务引擎服务。
        • 检查服务引擎配置文件中的端口和地址配置。

    3. 第三步：检查SQL语法兼容性。

      • 操作：当测试接口报SQL执行错误时。
      • 排查项：根据数据库类型检查SQL语法兼容性。

      达梦数据库：

      • 大小写敏感问题：如果表名或字段名在数据库中是大写，而SQL中使用小写，会导致“表或视图不存在”错误。
      • 解决方案：
        • 在数据源URL中添加参数 ?columnNameUpperCase=false。
        • 统一使用大写表名和字段名。
        • 申请补丁 DAMP_7.3.1_SERVER_20250821_P1（解决数据库名包含中划线问题）。

      PostgreSQL：

      • PostgreSQL是大小写敏感数据库，未加双引号的标识符会被自动转换为小写。
      • 解决方案：
        • 如果数据库中是大写表名/字段名，SQL中必须使用双引号括起来。
        • 修改数据库配置为大小写不敏感（不建议在生产环境操作）。
        • 数据服务不支持在大小写敏感数据源中发布服务，建议项目修改数据库配置。

      Oracle：

      • 日期格式问题：如果入参字段为DATE类型，可能提示 ORA-01861: literal does not match format string。
      • 解决方案：检查传入的日期格式与数据库要求的格式是否一致。

    4. 第四步：检查网络和防火墙。

      • 操作：当测试接口报连接超时时。
      • 排查项：
        • DAMP服务器与数据源服务器之间的网络连通性。
        • 防火墙是否开放了数据库端口。
        • 数据库连接池配置是否合理。
      • 解决方案：
        • 使用telnet命令测试端口连通性：telnet 数据库IP 端口。
        • 检查数据库服务器防火墙设置。

    5. 第五步：检查输入参数完整性。

      • 操作：当测试接口报空指针异常时。
      • 排查项：
        • 接口调用时是否传入了所有必填参数。
        • 必填参数值是否为空。
      • 解决方案：补充必填参数后重新测试。

    6. 第六步：检查分页参数。

      • 操作：当分页查询无效时。
      • 排查项：
        • 对于Hive/星环等数据源，分页语法可能与MySQL不同。
        • pageNumber参数从0开始还是从1开始。
      • 解决方案：
        • 申请补丁 DAMP_7.3.1_DATAENGINE_20250324_C1（适配星环大数据分页）。
        • 检查SQL中是否包含rownum、limit等分页关键字。

# 场景三：参数/字段异常

  • 问题现象：
    1. 返回字段名大小写被篡改（如ENERGY_SECTOR变成energy_sector）。
    2. 返回字段缺失或顺序错乱。
    3. 参数说明不显示或字段类型不显示。
    4. 日期类型字段格式错误。
    5. SQL API服务输入参数页面显示错误。
  • 排查步骤：
    1. 第一步：排除产品BUG。
      • 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 字段、参数、大小写、日期。
      • 相关补丁：
        • DAMP 7.3.1: DAMP_7.5.0_UI_20251231_P2 (解决DATE类型入参格式错误)
        • DAMP 7.3 GA: DAMP_7.3_UI_20250911_P1 (解决字段类型不显示)
      • 解决方案：若找到描述匹配的补丁，则申请并应用。
    2. 第二步：检查数据库大小写敏感（字段名被篡改）。
      • 操作：当返回字段名大小写与预期不一致时。
      • 排查项：
        • 数据库是否为大小写敏感模式。
        • 数据库驱动是否强制转换了字段名。
      • 解决方案：
        • PostgreSQL：数据库会强制将未加双引号的标识符转为小写。可以在发布服务时，在输出参数配置中手动修改字段别名。
        • 达梦数据库：在JDBC URL中添加 ?columnNameUpperCase=false 参数。
        • 如果项目有数据服务后端源码，可以自行修改入参出参别名统一大小写。
    3. 第三步：检查输出参数配置。
      • 操作：当返回字段缺失时。
      • 排查项：
        • 在服务配置的输出参数页面，是否勾选了所有需要返回的字段。
        • 是否有字段被错误地设置为不返回。
      • 解决方案：
        • 进入服务编辑页面，重新选择输出参数字段。
        • 确认后重新发布服务。
    4. 第四步：检查参数说明配置。
      • 操作：当参数说明不显示时。
      • 排查项：
        • 参数说明需要在输入参数界面中手动添加，系统不会自动生成。
      • 解决方案：
        • 进入服务编辑页面，在输入参数配置中，为每个参数填写“参数说明”。
        • 提交后重新发布服务。
    5. 第五步：检查日期格式。
      • 操作：当日期类型字段测试报错时。
      • 排查项：
        • 前端传入的日期格式是否与数据库要求的格式一致。
        • 时区设置是否正确。
      • 解决方案：
        • 统一使用 YYYY-MM-DD HH:MM:SS 格式。
        • 检查数据库的日期格式设置。
        • 申请补丁 DAMP_7.5.0_UI_20251231_P2（修复DATE类型入参格式错误）。
    6. 第六步：理解7.3GA版本设计特性。
      • 操作：如果7.3GA版本中结果集服务不显示表名。
      • 排查项：7.3GA版本结果集服务默认不显示表名，乃产品设计。
      • 解决方案：
        • 如需显示SQL语句，需升级到7.3.1版本。
        • 升级后需要重新发布服务，但同样不支持修改SQL。

# 场景四：服务授权/权限问题

  • 问题现象：
    1. 服务授权后，调用接口返回无权限。
    2. 行权限配置不生效，无法过滤数据。
    3. 脱敏设置不生效，返回明文数据。
    4. 授权修改时无法修改行权限配置。
    5. 授权页面看不到入参/出参字段。
  • 排查步骤：
    1. 第一步：排除产品BUG。
      • 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 授权、行权限、脱敏、token。
      • 相关补丁：
        • DAMP 7.3 GA: DAMP_7.3_DATAENGINE_20250411_P1 (解决设置必填参数不生效)
      • 解决方案：若找到描述匹配的补丁，则申请并应用。
    2. 第二步：检查授权配置。
      • 操作：确认服务已正确授权。
      • 排查项：
        • 在“服务授权”列表中，是否有对应的授权记录。
        • 授权记录的状态是否为“启用”。
        • 授权账号和密钥是否正确。
      • 解决方案：
        • 如果授权记录不存在，重新进行服务授权。
        • 如果授权记录已停用，点击“启用”。
    3. 第三步：检查token有效性。
      • 操作：确认调用接口时携带了正确的token。
      • 排查项：
        • 调用接口时是否在header中携带了Authorization: Bearer {token}。
        • token是否在有效期内。
        • 服务验证是否已开启。
      • 解决方案：
        • 重新获取token（通过授权账号和密钥调用token接口）。
        • 确保服务验证已开启（在服务引擎配置中）。
    4. 第四步：检查行权限配置（7.3版本限制）。
      • 操作：当行权限配置不生效时。
      • 排查项：
        • 行权限配置中，过滤字段是否在输出参数中。
        • 7.3版本产品设计：行权限配置只能获取到输出参数的字段，无法获取输入参数。
      • 解决方案：
        • 确保用作数据过滤的字段必须在输出参数中。
        • 如果需要在输入参数层面过滤，这是产品设计限制，需项目自行定制开发。
    5. 第五步：检查脱敏配置。
      • 操作：当脱敏设置不生效时。
      • 排查项：
        • 服务授权时是否勾选了脱敏规则。
        • 服务验证是否已开启（脱敏需要token验证）。
        • 是否通过ESB调用，ESB端的配置是否正确。
      • 解决方案：
        • 确认服务验证已开启，调用接口时携带token。
        • 如果是通过ESB调用，检查ESB端的服务验证配置，确保token能传递到DAMP。
    6. 第六步：检查授权页面字段显示。
      • 操作：当授权页面入参/出参没有数据时。
      • 排查项：前端介质版本问题。
      • 解决方案：
        • 申请补丁 DAMP_7.5.0_UI_202500725_P1（7.5版本补丁，7.3版本可参考）。
        • 检查前端介质是否为最新版本。

# 场景五：服务调用统计/监控异常

  • 问题现象：
    1. 服务调用统计页面打开报错500。
    2. 调用统计数据不显示或显示不全。
    3. 服务引擎监控页面无数据。
    4. 各部门调用分布情况显示异常。
  • 排查步骤：
    1. 第一步：排除产品BUG。
      • 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 统计、监控、调用。
      • 相关补丁：
        • DAMP 7.3.1: DAMP_7.3.1_SERVER_20241018_P1 (解决服务调用统计页面500错误)
        • DAMP 7.3 GA: DAMP_7.3_SERVER_20250508_P1 (解决模型核检定任务不能正常执行)
      • 解决方案：若找到描述匹配的补丁，则申请并应用。
    2. 第二步：检查监控组件配置。
      • 操作：确认filebeat+logstash+elasticsearch链路是否正常。
      • 排查项：
        • filebeat是否安装在服务引擎所在服务器。
        • filebeat配置中，paths路径是否正确指向服务引擎的api.log文件。
        • logstash配置中，beats端口（默认5044）是否正确。
        • elasticsearch是否正常启动，DAMP配置的ES地址是否正确。
      • 解决方案：
        • 参考操作手册中的filebeat和logstash配置模板。
        • 检查各组件日志，确认日志是否正常采集和传输。
    3. 第三步：检查ES连接状态。
      • 操作：当统计页面报500错误时。
      • 排查项：
        • 平台参数配置中，searchEngine.engineUrl配置的ES地址是否正确。
        • 如果ES启用了SSL，证书是否已导入JDK信任库。
        • ES服务是否正常，可通过浏览器访问http://es_ip:9200/_cat/indices验证。
      • 解决方案：
        • 修正ES地址配置。
        • 如果ES启用了HTTPS，需要将SSL证书导入DAMP所在服务器的JDK信任库。
        • 重启DAMP服务后重试。
    4. 第四步：检查日志采集。
      • 操作：确认服务调用日志是否被正确采集。
      • 排查项：
        • 查看服务引擎的logs/api.log文件，确认是否有调用记录。
        • 查看elasticsearch中是否有api-log-*索引。
        • 使用Kibana或curl查询ES中的数据：curl -XGET 'http://es_ip:9200/api-log-*/_search?pretty'
      • 解决方案：
        • 如果ES中没有索引，手动触发一次服务调用，然后检查日志采集。
        • 如果日志没有被采集，检查filebeat和logstash配置。
    5. 第五步：检查数据库适配（特定数据库）。
      • 操作：如果使用GaussDB等特定数据库。
      • 排查项：数据库方言兼容性问题。
      • 解决方案：
        • 申请适配GaussDB的补丁：DAMP_7.5.0_SERVER_20251016_P1（7.5版本补丁，7.3版本可联系技术支持）。
    6. 第六步：重启相关服务。
      • 操作：如果以上步骤都正常，但统计仍异常。
      • 解决方案：
        • 重启elasticsearch服务。
        • 重启logstash服务。
        • 重启filebeat服务。
        • 在DAMP“系统工具”中，执行“ES索引重建”相关工具。
上次更新: 2026/3/12下午1:52:20

← 数据服务统计监控相关问题 →