iPaaS文档库
00 概述
06 接口服务说明
10 iPaaS上线指南

# 问题排查手册：Portal页面菜单点击无数据或报错

# 问题现象

在Portal门户页面中，点击左侧或顶部导航菜单时，出现以下两种情况之一：

  1. 无数据：页面内容区域空白。
  2. 接口报错：浏览器页面弹出错误提示（如“内部错误”），或者通过浏览器开发者工具（F12）的 Network 标签页观察到请求接口返回 HTTP 4xx/5xx 错误码或后端异常信息。

# 分析思路

该问题通常发生在前端向后端请求数据的过程中。可能的原因包括：

  • 后端数据查询异常：SQL 查询某个条件不能满足，导致未能查出数据。
  • 参数传递错误：前端传递的参数（如ID、时间范围）与数据库中的数据不匹配。
  • 数据库连接或执行异常：SQL 执行报错（如字段不存在、语法错误）导致接口报错。

最有效的排查手段是捕获后端执行的 SQL 语句，通过模拟执行 SQL 来定位数据层面或语法层面的问题。

# 解决方案：启用 SQL 日志并逐步排查

# 步骤一：开启 Hibernate SQL 日志

在 Portal 后端服务的配置文件（application.properties）中添加或修改以下配置，以打印实际执行的 SQL 语句及参数。

配置内容 (application.properties):

# 控制台打印 SQL 语句
spring.jpa.show-sql=true
# 格式化 SQL，便于阅读
spring.jpa.properties.hibernate.format_sql=true
# 打印 SQL 语句的日志 (更详细的级别)
logging.level.org.hibernate.SQL=DEBUG
# 打印 SQL 语句中的参数值 (如 ID, 名称等)
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

# 步骤二：复现问题并捕获 SQL

  1. 重启 Portal 后端服务。
  2. 在浏览器中再次点击出现问题的菜单，复现“无数据”或“报错”的场景。
  3. 立即查看后端控制台日志。你会看到类似如下的日志输出：
    • DEBUG 级别的 SQL 语句：select user0_.id as id1_0_, user0_.name as name2_0_ from t_user user0_ where user0_.deleted=0 and user0_.org_id=?
    • TRACE 级别的参数绑定：binding parameter [1] as [BIGINT] - [1001]

# 步骤三：数据库模拟执行与逆向排查

拿到完整的 SQL 语句和参数值后，进入数据库客户端进行排查。

  1. 直接执行 SQL： 将日志中的 SQL（包括参数占位符替换为实际值）复制出来，在数据库中完整执行一次。

    • 执行无数据或报错 (Empty Set)** -> 进入下一步排查。
    • 如果有数据，页面不显示，可以排查配置的数据库方言是否正确。

  2. 逆向排查条件： 如果是“无数据”，说明 SQL 的存在查询条件不满足。此时，采取逆向排除法，逐步放宽条件，以定位具体是哪个条件导致了数据缺失。

    • 第一步：去掉所有 WHERE 条件。 执行 select * from table_name; (不包含任何过滤条件)。

      • 结果：如果此时查出了数据，说明表中确实有数据，问题出在过滤条件上。
      • 结果：如果依然查不出数据，说明该表本身就没有数据，问题在于数据初始化、同步、连接的数据库是否正确。

    • 第二步：逐个增加条件。 从完整的 SQL 中，按照业务可能性从低到高的顺序，将 WHERE 条件逐个加回去，每次加一个条件后执行一次 SQL。

      • 例如，SQL 条件为：deleted=0 AND org_id=1001 AND status='ACTIVE' AND name='张三'
      • 排查过程：
        1. 执行 ... WHERE deleted=0 (有数据)
        2. 执行 ... WHERE deleted=0 AND org_id=1001 (有数据)
        3. 执行 ... WHERE deleted=0 AND org_id=1001 AND status='ACTIVE' (有数据)
        4. 执行 ... WHERE deleted=0 AND org_id=1001 AND status='ACTIVE' AND name='张三' (无数据)

    • 定位问题条件： 通过上述步骤，可以定位到是哪一个条件（如 name='张三'）导致数据查不出来。此时，应检查：

      • 前端传递的参数 name 是否正确？
      • 数据库中的数据该字段值是否为 张三？是否存在大小写、空格等问题？
      • 如果条件是 org_id=1001，确认当前登录用户是否属于该组织，以及该组织下是否有数据。

# 总结

步骤 操作 目的
1. 配置 开启 spring.jpa.show-sql 和 logging.level 相关日志。 捕获后端执行的真实 SQL 语句和参数。
2. 捕获 复现问题，从日志中拿到完整的 SQL。 获取排查的“原材料”。
3. 执行 在数据库客户端执行该 SQL。 验证是否是数据查询本身的问题。
4. 逆向 若执行无数据，逐步去掉 WHERE 条件，逐个排查。 精准定位是哪个过滤条件导致了数据无法查出。
5. 定位 根据定位到的“问题条件”，分析是前端传参错误、数据错误还是业务逻辑（如权限过滤）不当。 找到根本原因，为开发人员提供修复依据。

通过以上“开启日志 -> 捕获 SQL -> 逆向排查”的方案，可以系统性地解决 Portal 页面菜单点击后无数据或报错的问题，快速区分问题是出在前端参数、后端逻辑还是数据层面。

← OnlineToken相关问题排查 →