20260823210241
This commit is contained in:
oneao committed
1 parent
5ff4583aeb
commit
f4c7413dc6
2766 files changed
+1836409
-94689
No files matched your search
@@ -0,0 +1,373 @@
|
||||
# 调试排错
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [FpsMonitor.vue](file://fms-vue/src/components/FpsMonitor.vue)
|
||||
- [application.yaml](file://fms-api/src/main/resources/application.yaml)
|
||||
- [FmsApiApplication.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java)
|
||||
- [measure.mjs](file://.fps-probe/measure.mjs)
|
||||
- [debug-edit.mjs](file://.fps-probe/debug-edit.mjs)
|
||||
- [debug-login.mjs](file://.playwright-cli/debug-login.mjs)
|
||||
- [inspect-vue-root.mjs](file://.playwright-cli/inspect-vue-root.mjs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能注意事项](#性能注意事项)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本指南面向 FMS 项目的开发与测试人员，提供前后端联调、前端与后端调试方法、常见问题定位、性能优化与瓶颈定位、以及基于 Playwright 的自动化脚本使用建议。内容结合项目内已有的 FPS 监控组件、Playwright 探针脚本、API 配置与启动入口，帮助快速定位网络、数据库、权限验证等问题，并给出可操作的步骤与可视化流程图。
|
||||
|
||||
## 项目结构
|
||||
FMS 包含前端 Vue 应用、后端 Spring Boot API、以及用于性能测量与页面交互的 Playwright 脚本集：
|
||||
- 前端（fms-vue）：提供 UI 与 FPS 监控组件，便于在浏览器中观察渲染性能。
|
||||
- 后端（fms-api）：Spring Boot 服务，提供数据接口与鉴权能力，配置文件集中管理端口、上下文路径、数据库连接池等。
|
||||
- 探针与脚本（.fps-probe、.playwright-cli）：通过 Playwright 驱动浏览器进行滚动、编辑、登录等场景的性能测量与状态检查。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端"
|
||||
FE["Vue 应用<br/>含 FPS 监控组件"]
|
||||
end
|
||||
subgraph "后端"
|
||||
BE["Spring Boot API<br/>端口 8088 /api"]
|
||||
end
|
||||
subgraph "自动化与探针"
|
||||
PW["Playwright 脚本<br/>测量/调试/巡检"]
|
||||
end
|
||||
FE --> BE
|
||||
PW --> FE
|
||||
PW --> BE
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
|
||||
**章节来源**
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
|
||||
## 核心组件
|
||||
- 前端 FPS 监控组件：以 requestAnimationFrame 采样当前帧率、平均帧率与最低帧率，并提供历史柱状图与拖拽复位功能，适合在开发阶段直观观察页面卡顿。
|
||||
- 后端启动与配置：Spring Boot 应用入口初始化雪花 ID 生成器；application.yaml 定义服务端口、上下文路径、JWT 密钥、数据库连接池参数与文件存储策略。
|
||||
- Playwright 探针脚本：
|
||||
- measure.mjs：在真实表格容器上执行滚动、隐藏绘制等场景，统计 FPS、帧间隔、渲染行数与编辑器数量。
|
||||
- debug-edit.mjs：注入登录态后进入表格页，定位单元格并模拟点击，输出点击命中元素与编辑器挂载情况。
|
||||
- debug-login.mjs：注入会话到登录页，跳转路由并截图，辅助排查路由与鉴权流程。
|
||||
- inspect-vue-root.mjs：注入会话并拦截 API 返回，检查 Vue 根实例与特定组件实例属性，便于定位组件状态问题。
|
||||
|
||||
**章节来源**
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
|
||||
## 架构总览
|
||||
下图展示前端、后端与自动化脚本之间的交互关系，包括登录态注入、API 请求、表格渲染与性能测量。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as "开发者"
|
||||
participant PW as "Playwright 脚本"
|
||||
participant FE as "Vue 前端"
|
||||
participant BE as "Spring Boot API"
|
||||
participant DB as "数据库"
|
||||
Dev->>PW : 运行测量/调试脚本
|
||||
PW->>FE : 打开页面并注入登录态
|
||||
FE->>BE : 发起数据加载/分页请求
|
||||
BE->>DB : 查询业务数据
|
||||
DB-->>BE : 返回数据集
|
||||
BE-->>FE : 返回 JSON 响应
|
||||
FE->>FE : 渲染表格/编辑器
|
||||
FE->>FE : FPS 监控采样
|
||||
PW->>FE : 执行滚动/点击/截图
|
||||
PW-->>Dev : 输出 FPS/帧间隔/状态
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
|
||||
- [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)
|
||||
- [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 前端 FPS 监控组件
|
||||
该组件通过高频 rAF 循环统计当前 FPS、平均值与最小值，并以柱状图展示历史趋势。支持拖拽移动与重置统计，避免后台暂停导致均值失真。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["组件挂载"]) --> Init["初始化采样窗口"]
|
||||
Init --> RAF["requestAnimationFrame 循环"]
|
||||
RAF --> Tick{"达到采样间隔?"}
|
||||
Tick --> |否| RAF
|
||||
Tick --> |是| Calc["计算当前/平均/最低 FPS"]
|
||||
Calc --> Update["更新历史柱状图"]
|
||||
Update --> RAF
|
||||
RAF --> Visibility{"页面可见性变化?"}
|
||||
Visibility --> |切回前台| ResetWin["重置采样窗口"]
|
||||
Visibility --> |保持后台| RAF
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [FpsMonitor.vue:36-75](file://fms-vue/src/components/FpsMonitor.vue#L36-L75)
|
||||
- [FpsMonitor.vue:77-95](file://fms-vue/src/components/FpsMonitor.vue#L77-L95)
|
||||
- [FpsMonitor.vue:136-146](file://fms-vue/src/components/FpsMonitor.vue#L136-L146)
|
||||
|
||||
**章节来源**
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
|
||||
### 后端启动与配置
|
||||
后端启动时设置雪花 ID 生成器选项，并通过 application.yaml 暴露服务端口与上下文路径，同时配置 JWT 与数据库连接池参数。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class FmsApiApplication {
|
||||
+main(args)
|
||||
}
|
||||
class Config {
|
||||
+server.port
|
||||
+server.servlet.context-path
|
||||
+spring.application.name
|
||||
+fms.auth.jwt-secret
|
||||
+fms.database.pool.*
|
||||
}
|
||||
FmsApiApplication --> Config : "读取配置"
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [FmsApiApplication.java:13-18](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L13-L18)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
**章节来源**
|
||||
- [FmsApiApplication.java:1-22](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L1-L22)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
### Playwright 性能测量脚本
|
||||
脚本在表格容器中执行滚动或编辑场景，统计 FPS、帧间隔、渲染行数与编辑器数量，支持多轮测量与汇总。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant PW as "measure.mjs"
|
||||
participant Page as "浏览器页面"
|
||||
participant Table as ".fms-table"
|
||||
PW->>Page : 打开页面并等待表格就绪
|
||||
PW->>Table : 选择滚动容器
|
||||
loop 每帧
|
||||
PW->>Table : 滚动 scrollTop += step
|
||||
PW->>Page : 记录帧间隔与计数
|
||||
end
|
||||
PW-->>PW : 计算 FPS/avgFrame/minGap/maxGap
|
||||
PW-->>PW : 输出渲染行数/编辑器数/展示格数
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
|
||||
- [measure.mjs:168-215](file://.fps-probe/measure.mjs#L168-L215)
|
||||
|
||||
**章节来源**
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
|
||||
### Playwright 登录与路由调试脚本
|
||||
脚本注入登录态到 sessionStorage，导航至目标路由并截图，便于验证鉴权与路由跳转逻辑。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant PW as "debug-login.mjs"
|
||||
participant Page as "浏览器页面"
|
||||
PW->>Page : 打开登录页
|
||||
PW->>Page : 注入 fms-login 会话
|
||||
PW->>Page : 跳转到 /file-demo
|
||||
PW->>Page : 等待 DOM 稳定
|
||||
PW-->>PW : 截图并输出树节点信息
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)
|
||||
|
||||
**章节来源**
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
|
||||
### Playwright Vue 根实例检查脚本
|
||||
脚本注入会话并拦截 API 返回，检查 Vue 根实例与特定组件实例属性，辅助定位组件状态与数据绑定问题。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant PW as "inspect-vue-root.mjs"
|
||||
participant Page as "浏览器页面"
|
||||
PW->>Page : 添加 initScript 注入会话
|
||||
PW->>Page : 拦截 /api/** 请求并返回模拟数据
|
||||
PW->>Page : 打开 /file-demo
|
||||
PW->>Page : 评估 #app 与 __vue_app__ 属性
|
||||
PW-->>PW : 输出根实例类型与 Splitter 实例信息
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [inspect-vue-root.mjs:10-35](file://.playwright-cli/inspect-vue-root.mjs#L10-L35)
|
||||
- [inspect-vue-root.mjs:38-59](file://.playwright-cli/inspect-vue-root.mjs#L38-L59)
|
||||
|
||||
**章节来源**
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
|
||||
## 依赖关系分析
|
||||
- 前端依赖 Vue 运行时与组件库，FPS 监控组件依赖 requestAnimationFrame 与浏览器事件。
|
||||
- 后端依赖 Spring Boot、数据库连接池与 JWT 鉴权；配置集中在 application.yaml。
|
||||
- Playwright 脚本依赖 chromium 内核，通过注入会话与拦截 API 实现无头环境下的调试与测量。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
FE["Vue 前端"] --> |"HTTP /api/*"| BE["Spring Boot API"]
|
||||
BE --> |"JDBC/连接池"| DB["数据库"]
|
||||
PW["Playwright 脚本"] --> |"控制浏览器"| FE
|
||||
PW --> |"可选拦截/注入"| BE
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
|
||||
**章节来源**
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
|
||||
## 性能注意事项
|
||||
- 前端 FPS 监控：
|
||||
- 使用内置 FPS 监控组件观察当前/平均/最低帧率与历史趋势，拖拽位置避免遮挡操作区。
|
||||
- 关注低帧率时段对应的用户操作（如滚动、编辑），并结合表格渲染行数与编辑器数量定位热点。
|
||||
- 后端性能：
|
||||
- 调整数据库连接池参数（初始大小、最大活跃数、空闲检测等）以匹配负载。
|
||||
- 开启日志与慢查询追踪，结合接口耗时与数据库执行计划定位瓶颈。
|
||||
- 自动化测量：
|
||||
- 使用 measure.mjs 在不同场景（静止、滚动、隐藏绘制、编辑中滚动）下采集 FPS 与帧间隔，识别渲染与 JS 开销。
|
||||
- 通过多轮测量与页面重载减少状态污染，确保结果可比性。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
|
||||
### 网络连接问题
|
||||
- 现象：前端无法加载数据或报跨域错误。
|
||||
- 排查步骤：
|
||||
- 确认后端服务端口与上下文路径（application.yaml 中的 server.port 与 context-path）。
|
||||
- 使用 Playwright 脚本打开页面并检查控制台错误与网络面板。
|
||||
- 在 inspect-vue-root.mjs 中拦截 /api/** 请求，验证返回结构与状态码。
|
||||
- 参考脚本与配置：
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)
|
||||
|
||||
**章节来源**
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
|
||||
### 数据库连接问题
|
||||
- 现象：接口返回错误或数据为空。
|
||||
- 排查步骤：
|
||||
- 检查 application.yaml 中数据库连接池配置（initial-size、max-active、validation-query 等）。
|
||||
- 启动后端并查看日志，确认连接池初始化成功。
|
||||
- 使用简单查询验证数据库连通性。
|
||||
- 参考配置：
|
||||
- [application.yaml:10-26](file://fms-api/src/main/resources/application.yaml#L10-L26)
|
||||
|
||||
**章节来源**
|
||||
- [application.yaml:10-26](file://fms-api/src/main/resources/application.yaml#L10-L26)
|
||||
|
||||
### 权限验证问题
|
||||
- 现象：登录后仍无法访问受保护页面或数据。
|
||||
- 排查步骤：
|
||||
- 使用 debug-login.mjs 注入 fms-login 会话并跳转目标路由，验证路由守卫与权限校验。
|
||||
- 检查 sessionStorage 与 localStorage 中的键值是否正确设置。
|
||||
- 在后端检查 JWT 密钥与过期时间配置。
|
||||
- 参考脚本与配置：
|
||||
- [debug-login.mjs:10-47](file://.playwright-cli/debug-login.mjs#L10-L47)
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
|
||||
**章节来源**
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
|
||||
### 表格滚动与编辑卡顿
|
||||
- 现象：滚动或编辑时 FPS 下降明显。
|
||||
- 排查步骤：
|
||||
- 使用 FPS 监控组件观察卡顿时段。
|
||||
- 使用 measure.mjs 在“滚动”和“编辑中滚动”场景下采集 FPS、帧间隔与渲染行数。
|
||||
- 使用 debug-edit.mjs 定位点击命中元素与编辑器挂载情况，确认是否出现多余重绘。
|
||||
- 参考脚本：
|
||||
- [FpsMonitor.vue:36-75](file://fms-vue/src/components/FpsMonitor.vue#L36-L75)
|
||||
- [measure.mjs:23-124](file://.fps-probe/measure.mjs#L23-L124)
|
||||
- [debug-edit.mjs:31-93](file://.fps-probe/debug-edit.mjs#L31-L93)
|
||||
|
||||
**章节来源**
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)
|
||||
|
||||
### 内存泄漏检测
|
||||
- 现象：长时间使用后页面变慢或崩溃。
|
||||
- 排查步骤：
|
||||
- 在浏览器性能面板录制内存快照，对比不同时间点的使用量。
|
||||
- 使用 Playwright 脚本重复操作（滚动/编辑）并截图，观察内存增长。
|
||||
- 检查是否有未清理的事件监听器或定时器。
|
||||
- 参考工具：
|
||||
- 浏览器开发者工具（内存面板）
|
||||
- Playwright 脚本（可复用 measure.mjs 的场景循环）
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
### 错误日志分析与诊断流程
|
||||
- 前端：
|
||||
- 打开控制台查看报错堆栈与网络请求失败原因。
|
||||
- 使用 inspect-vue-root.mjs 拦截 API 并打印请求/响应，定位数据格式问题。
|
||||
- 后端：
|
||||
- 查看启动日志与异常堆栈，确认服务端口与上下文路径。
|
||||
- 检查数据库连接池与 JWT 配置，必要时调整超时与重试策略。
|
||||
- 参考：
|
||||
- [inspect-vue-root.mjs:14-35](file://.playwright-cli/inspect-vue-root.mjs#L14-L35)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
**章节来源**
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
## 结论
|
||||
通过内置 FPS 监控组件与 Playwright 探针脚本，FMS 项目提供了完善的前端性能观测与自动化调试能力。结合后端配置与启动入口，可以快速定位网络、数据库与权限验证问题。建议在开发阶段持续使用 FPS 监控与自动化测量，结合日志与内存分析，形成闭环的性能优化与故障排查流程。
|
||||
|
||||
[本节为总结，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 常用调试命令与步骤
|
||||
- 启动后端服务：
|
||||
- 检查 application.yaml 中的端口与上下文路径，确保服务可用。
|
||||
- 参考启动入口类与配置扫描注解。
|
||||
- 运行前端 FPS 监控：
|
||||
- 在页面中启用 FPS 监控组件，观察实时帧率与历史趋势。
|
||||
- 执行 Playwright 测量：
|
||||
- 使用 measure.mjs 在指定场景下采集 FPS 与帧间隔。
|
||||
- 使用 debug-edit.mjs 验证表格编辑与点击命中。
|
||||
- 使用 debug-login.mjs 注入会话并截图验证路由。
|
||||
- 使用 inspect-vue-root.mjs 检查 Vue 根实例与组件状态。
|
||||
|
||||
**章节来源**
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
|
||||
- [measure.mjs:1-218](file://.fps-probe/measure.mjs#L1-L218)
|
||||
- [debug-edit.mjs:1-97](file://.fps-probe/debug-edit.mjs#L1-L97)
|
||||
- [debug-login.mjs:1-48](file://.playwright-cli/debug-login.mjs#L1-L48)
|
||||
- [inspect-vue-root.mjs:1-60](file://.playwright-cli/inspect-vue-root.mjs#L1-L60)
|
||||
Reference in new issue
Block a user