496 lines
13 KiB
Markdown
496 lines
13 KiB
Markdown
# React 最佳实践优化计划
|
|
|
|
本文档基于 `$vercel-react-best-practices` 对当前项目 React 渲染层的审查结果整理而成，目标不是立刻重写页面，而是按“先收敛数据流，再拆重型组件，最后做体验与性能微调”的顺序，逐步降低渲染层维护成本。
|
|
|
|
## 1. 审查背景
|
|
|
|
当前项目的 React 层已经具备一些不错的基础：
|
|
|
|
- 页面与 Electron 主进程通过 preload facade 通信
|
|
- 关键业务已经逐步抽到 hook 和 service
|
|
- `Cleaner` 相关逻辑已经做过第一轮拆分
|
|
- 更新、认证、日志、校验等流程已有一定模块意识
|
|
|
|
但从 `$vercel-react-best-practices` 的角度看，当前主要问题仍集中在：
|
|
|
|
- 页面容器组件承担过多状态与副作用
|
|
- 大 hook 同时管理初始化、交互状态、远程请求、持久化
|
|
- effect 数量偏多，且存在“启动时拉很多东西、认证后再拉一遍”的流程
|
|
- 重型 UI 区块还没有进一步拆成可稳定复用的小边界
|
|
- 某些异步请求与 UI 更新仍可进一步并行化、延后 await 或降低重渲染范围
|
|
|
|
## 2. Skill 视角下的主要问题
|
|
|
|
### 2.1 高优先级: `App.tsx` 仍是重型入口容器
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/App.tsx`
|
|
|
|
问题表现：
|
|
|
|
- 认证初始化、更新订阅、页面导航、顶部壳层、登录/选人/更新弹窗都集中在一个组件里
|
|
- `initializeAuth()` 同时负责获取机器名、silent login、admin 用户分流、错误兜底
|
|
- `useEffect` 和回调之间仍有较强耦合，后续继续扩展容易变成新的“前端编排中心”
|
|
|
|
与 skill 对应：
|
|
|
|
- `rerender-split-combined-hooks`
|
|
- `rerender-move-effect-to-event`
|
|
- `advanced-init-once`
|
|
|
|
建议方向：
|
|
|
|
- 抽出 `useAppBootstrap`
|
|
- 抽出 `useUpdateController`
|
|
- 把顶部壳层拆成 `AppShell`
|
|
- 把未认证态与已认证态拆成两条渲染分支组件
|
|
|
|
### 2.2 高优先级: `CleanerPage` + `useCleaner` 仍然是“大页面 + 大 hook”模式
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
|
- `src/renderer/src/hooks/useCleaner.ts`
|
|
|
|
问题表现：
|
|
|
|
- `CleanerPage` 同时渲染左侧筛选区、顶部工具栏、结果表格、底部执行区和多个弹窗
|
|
- `useCleaner` 同时承担权限初始化、sessionStorage 同步、配置加载、进度订阅、校验请求、导出、执行删除、内联编辑、确认弹窗状态
|
|
- hook 返回面非常大，页面对 hook 的内部结构有明显耦合
|
|
|
|
与 skill 对应：
|
|
|
|
- `rerender-split-combined-hooks`
|
|
- `rerender-derived-state-no-effect`
|
|
- `rerender-no-inline-components`
|
|
- `rendering-content-visibility`
|
|
|
|
建议方向：
|
|
|
|
- `useCleanerPageState`
|
|
- `useCleanerExecution`
|
|
- `useCleanerSelection`
|
|
- `CleanerSidebar`
|
|
- `CleanerToolbar`
|
|
- `CleanerResultsTable`
|
|
- `CleanerExecutionBar`
|
|
|
|
### 2.3 中优先级: `ExtractorPage` 里存在“输入变化即触发跨模块副作用”的同步路径
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/pages/ExtractorPage.tsx`
|
|
|
|
问题表现：
|
|
|
|
- `orderNumbers` 每次变化都会写 `sessionStorage`
|
|
- 同时每次变化都会调用 `window.electron.validation.setSharedProductionIds()` 或 `clearSharedProductionIds()`
|
|
- 这条路径把“输入态”和“共享业务态”绑得很紧，后续如果输入组件更复杂，容易造成高频桥接调用
|
|
|
|
与 skill 对应：
|
|
|
|
- `rerender-move-effect-to-event`
|
|
- `client-localstorage-schema`
|
|
- `js-cache-storage`
|
|
|
|
建议方向：
|
|
|
|
- 只在“格式化完成 / 用户提交 / debounce 稳定后”同步共享订单号
|
|
- 把 sessionStorage 读写抽到专门 persistence helper
|
|
- 为共享 Production ID 增加单独同步入口，而不是输入 effect 隐式触发
|
|
|
|
### 2.4 中优先级: 更新对话框的异步拉取和状态切换还可以再收敛
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/components/UpdateDialog.tsx`
|
|
- `src/renderer/src/App.tsx`
|
|
|
|
问题表现：
|
|
|
|
- `App` 负责状态订阅和 catalog/status 刷新
|
|
- `UpdateDialog` 内部再负责根据选中版本拉 changelog
|
|
- 当前实现是可工作的，但状态来源分散，后续容易出现 “catalog 变了 / changelog 还在旧请求中” 的边界问题
|
|
|
|
与 skill 对应：
|
|
|
|
- `async-defer-await`
|
|
- `async-parallel`
|
|
- `rerender-dependencies`
|
|
- `rendering-usetransition-loading`
|
|
|
|
建议方向：
|
|
|
|
- 建立 `useUpdateDialogState`
|
|
- catalog/status/changelog 分层管理
|
|
- 选版本后的 changelog 拉取用请求标识或最新值保护
|
|
- 对切换版本时的 UI 更新引入 `startTransition`
|
|
|
|
### 2.5 中优先级: 页面级异步初始化还缺少统一“启动编排 hook”
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/App.tsx`
|
|
- `src/renderer/src/hooks/useCleaner.ts`
|
|
- `src/renderer/src/pages/ExtractorPage.tsx`
|
|
|
|
问题表现：
|
|
|
|
- 认证初始化、Cleaner 初始化、配置加载、进度订阅分别散在多个组件和 hook 的 `useEffect` 中
|
|
- 目前逻辑可读，但入口分散，出现启动问题时需要在多个位置来回追
|
|
|
|
与 skill 对应：
|
|
|
|
- `advanced-init-once`
|
|
- `async-parallel`
|
|
- `rerender-split-combined-hooks`
|
|
|
|
建议方向：
|
|
|
|
- `useAppBootstrap`
|
|
- `useCleanerBootstrap`
|
|
- 把“初始加载”“事件订阅”“持久化恢复”拆成更小的 effect 组
|
|
|
|
### 2.6 中优先级: 组件树里还有一些可延迟加载的重型弹窗
|
|
|
|
涉及文件：
|
|
|
|
- `src/renderer/src/App.tsx`
|
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
|
- `src/renderer/src/components/UpdateDialog.tsx`
|
|
- `src/renderer/src/components/ReportViewerDialog.tsx`
|
|
- `src/renderer/src/components/ExecutionReportDialog.tsx`
|
|
- `src/renderer/src/components/MaterialTypeManagementDialog.tsx`
|
|
|
|
问题表现：
|
|
|
|
- 多个重型弹窗在页面初始渲染时就参与静态导入
|
|
- 像 `ReportViewerDialog`、Markdown 渲染、报告浏览、类型管理这类功能明显不是首屏关键路径
|
|
|
|
与 skill 对应：
|
|
|
|
- `bundle-dynamic-imports`
|
|
- `bundle-conditional`
|
|
- `bundle-defer-third-party`
|
|
|
|
建议方向：
|
|
|
|
- 对非首屏弹窗引入 `React.lazy`
|
|
- 在用户点击前后再加载重型内容
|
|
- 优先收敛 `ReportViewerDialog` 与 `UpdateDialog`
|
|
|
|
## 3. 当前问题总览
|
|
|
|
```mermaid
|
|
graph TD
|
|
App[App.tsx]
|
|
CleanerPage[CleanerPage.tsx]
|
|
UseCleaner[useCleaner.ts]
|
|
ExtractorPage[ExtractorPage.tsx]
|
|
UpdateDialog[UpdateDialog.tsx]
|
|
Dialogs[Heavy Dialogs]
|
|
|
|
App -->|认证 更新 导航混合| Maintainability[维护成本上升]
|
|
CleanerPage -->|页面职责过大| Maintainability
|
|
UseCleaner -->|状态 请求 持久化混合| Maintainability
|
|
ExtractorPage -->|输入驱动副作用| Maintainability
|
|
UpdateDialog -->|异步状态来源分散| Maintainability
|
|
Dialogs -->|非首屏静态导入| Bundle[首屏与包体压力]
|
|
```
|
|
|
|
## 4. 优化目标
|
|
|
|
本轮 React 向优化聚焦以下目标：
|
|
|
|
- 让页面容器组件回归“组装层”
|
|
- 让 hook 边界按职责拆清，不再兼做状态、初始化、请求和交互编排
|
|
- 让跨模块副作用从输入/渲染 effect 中收敛到更稳定的事件或 bootstrap 层
|
|
- 让重型弹窗按需加载，减少首屏包体负担
|
|
- 让异步加载流程更并行、更可追踪、更容易测试
|
|
|
|
## 5. 分阶段执行计划
|
|
|
|
### Phase 1: 收敛应用入口与认证启动流
|
|
|
|
目标：
|
|
|
|
- 把 `App.tsx` 从“大容器”拆成更清晰的组装层
|
|
- 明确认证、更新、壳层 UI 的职责边界
|
|
|
|
建议涉及文件：
|
|
|
|
- `src/renderer/src/App.tsx`
|
|
- `src/renderer/src/hooks/useAuth.ts`
|
|
- `src/renderer/src/hooks/useLogger.ts`
|
|
- 新增 `src/renderer/src/hooks/useAppBootstrap.ts`
|
|
- 新增 `src/renderer/src/components/app/`
|
|
|
|
建议拆分方向：
|
|
|
|
- `useAppBootstrap()`
|
|
- `AuthenticatedApp`
|
|
- `UnauthenticatedApp`
|
|
- `AppShell`
|
|
- `UpdateEntryButton`
|
|
|
|
预期收益：
|
|
|
|
- 减少 `App.tsx` 的状态面
|
|
- 降低启动 effect 的复杂度
|
|
- 让认证与更新逻辑更容易测试
|
|
|
|
风险等级：
|
|
|
|
- 中
|
|
|
|
验证方式：
|
|
|
|
- silent login / 登录 / 管理员选人流程回归正常
|
|
- 更新状态订阅正常
|
|
- `npm run typecheck` 与相关测试通过
|
|
|
|
### Phase 2: 拆分 `CleanerPage` 与 `useCleaner`
|
|
|
|
目标：
|
|
|
|
- 进一步拆解 Cleaner 的页面结构和 hook 职责
|
|
- 降低单个 hook / 页面承载的状态数量
|
|
|
|
建议涉及文件：
|
|
|
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
|
- `src/renderer/src/hooks/useCleaner.ts`
|
|
- `src/renderer/src/hooks/cleaner/`
|
|
- 新增 `src/renderer/src/components/cleaner/`
|
|
|
|
建议拆分方向：
|
|
|
|
- `useCleanerBootstrap`
|
|
- `useCleanerSelection`
|
|
- `useCleanerExecution`
|
|
- `CleanerSidebar`
|
|
- `CleanerToolbar`
|
|
- `CleanerResultsTable`
|
|
- `CleanerExecutionFooter`
|
|
|
|
预期收益：
|
|
|
|
- 降低重渲染范围
|
|
- 提高 Cleaner 页面可读性
|
|
- 为表格和执行区单独补测试创造条件
|
|
|
|
风险等级：
|
|
|
|
- 中到高
|
|
|
|
验证方式：
|
|
|
|
- 校验、筛选、勾选、编辑负责人、执行删除、导出流程手工验证
|
|
- `cleaner` 相关单测通过
|
|
|
|
### Phase 3: 收敛 Extractor 与共享 Production ID 同步
|
|
|
|
目标：
|
|
|
|
- 把输入态和共享业务态解耦
|
|
- 降低输入变化带来的高频副作用
|
|
|
|
建议涉及文件：
|
|
|
|
- `src/renderer/src/pages/ExtractorPage.tsx`
|
|
- `src/renderer/src/hooks/useExtractor.ts`
|
|
- 新增 `src/renderer/src/hooks/useSharedProductionIds.ts`
|
|
- 新增 `src/renderer/src/lib/session-storage/`
|
|
|
|
建议拆分方向：
|
|
|
|
- 仅在提交或 debounce 后同步共享 ID
|
|
- 抽出 `usePersistentTextState`
|
|
- 把 sessionStorage 与 Electron bridge 副作用集中管理
|
|
|
|
预期收益：
|
|
|
|
- 提高输入响应稳定性
|
|
- 降低桥接调用频率
|
|
- 更符合“interaction in event handlers, not passive effects”的原则
|
|
|
|
风险等级：
|
|
|
|
- 低到中
|
|
|
|
验证方式：
|
|
|
|
- 提取页输入、重置、共享订单号联动正常
|
|
- Cleaner 过滤模式仍能读取共享订单号
|
|
|
|
### Phase 4: 收敛更新弹窗与异步加载路径
|
|
|
|
目标：
|
|
|
|
- 把 `UpdateDialog` 的异步状态切换和版本详情拉取独立出来
|
|
- 降低 `App` 与弹窗之间的状态耦合
|
|
|
|
建议涉及文件：
|
|
|
|
- `src/renderer/src/components/UpdateDialog.tsx`
|
|
- `src/renderer/src/App.tsx`
|
|
- 新增 `src/renderer/src/hooks/useUpdateDialogState.ts`
|
|
|
|
建议拆分方向：
|
|
|
|
- `useUpdateCatalog`
|
|
- `useReleaseChangelog`
|
|
- 版本切换时用 `startTransition`
|
|
- changelog 拉取加最新请求保护
|
|
|
|
预期收益：
|
|
|
|
- 更新弹窗行为更稳定
|
|
- 降低状态竞争和旧请求覆盖新状态的风险
|
|
- 提升大型 Markdown 内容切换时的交互流畅度
|
|
|
|
风险等级：
|
|
|
|
- 中
|
|
|
|
验证方式：
|
|
|
|
- User/Admin 更新流程验证
|
|
- 版本切换与 changelog 展示正常
|
|
|
|
### Phase 5: 做弹窗与重型模块按需加载
|
|
|
|
目标：
|
|
|
|
- 把非首屏关键弹窗改成按需加载
|
|
- 降低 renderer 初始包体
|
|
|
|
建议涉及文件：
|
|
|
|
- `src/renderer/src/App.tsx`
|
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
|
- `src/renderer/src/components/ReportViewerDialog.tsx`
|
|
- `src/renderer/src/components/MaterialTypeManagementDialog.tsx`
|
|
- `src/renderer/src/components/ExecutionReportDialog.tsx`
|
|
- `src/renderer/src/components/UpdateDialog.tsx`
|
|
|
|
建议拆分方向：
|
|
|
|
- `React.lazy`
|
|
- 懒加载弹窗容器
|
|
- 打开前预加载关键模块
|
|
|
|
预期收益：
|
|
|
|
- 降低首屏 JS 负担
|
|
- 让常用流程优先加载
|
|
|
|
风险等级：
|
|
|
|
- 低
|
|
|
|
验证方式：
|
|
|
|
- 首屏功能正常
|
|
- 弹窗首次打开正常
|
|
- 打包后 smoke test 正常
|
|
|
|
### Phase 6: 补强 React 渲染层测试
|
|
|
|
目标：
|
|
|
|
- 给这轮 React 收敛提供稳定回归保护
|
|
|
|
建议涉及文件：
|
|
|
|
- 新增 `App` 相关组件测试
|
|
- 新增 `CleanerPage` / `useCleaner` 相关测试
|
|
- 新增 `UpdateDialog` 状态流测试
|
|
- 新增 `ExtractorPage` 共享订单号同步测试
|
|
|
|
优先补测内容：
|
|
|
|
- 认证启动分支
|
|
- 更新弹窗状态切换
|
|
- Cleaner 筛选与执行状态切换
|
|
- Extractor 输入与共享 ID 同步
|
|
|
|
预期收益：
|
|
|
|
- 降低后续 UI/状态重构风险
|
|
- 提高页面容器层的修改信心
|
|
|
|
风险等级：
|
|
|
|
- 低
|
|
|
|
验证方式：
|
|
|
|
- 单元测试 / 组件测试通过
|
|
- 关键页面 smoke test 正常
|
|
|
|
## 6. 推荐执行顺序
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Phase 1 App 入口与认证收敛]
|
|
B[Phase 2 Cleaner 页面与 Hook 拆分]
|
|
C[Phase 3 Extractor 同步路径收敛]
|
|
D[Phase 4 UpdateDialog 异步状态收敛]
|
|
E[Phase 5 弹窗按需加载]
|
|
F[Phase 6 React 层测试补强]
|
|
|
|
A --> B
|
|
A --> D
|
|
B --> F
|
|
C --> F
|
|
D --> F
|
|
E --> F
|
|
```
|
|
|
|
建议优先顺序：
|
|
|
|
1. 先做 `App` 入口与认证启动流收敛
|
|
2. 再做 `CleanerPage + useCleaner`
|
|
3. 然后收敛 `ExtractorPage` 的共享 ID 同步
|
|
4. 再处理 `UpdateDialog`
|
|
5. 最后做弹窗按需加载
|
|
6. 测试补强贯穿整个过程
|
|
|
|
## 7. 每阶段完成标准
|
|
|
|
每一阶段建议采用统一完成标准：
|
|
|
|
- 页面或 hook 的职责边界明显变清晰
|
|
- 对外行为保持兼容
|
|
- `npm run typecheck` 通过
|
|
- 相关单元测试 / 组件测试通过
|
|
- 关键页面功能手工验证通过
|
|
- 对应说明文档同步更新
|
|
|
|
## 8. 与现有重构工作的衔接
|
|
|
|
当前已经完成的工作为这轮 React 优化提供了基础：
|
|
|
|
- `validation-handler` 已拆成更清晰的主进程结构
|
|
- `useCleaner` 已做过第一轮内部 helpers/api 抽离
|
|
- Electron 侧 preload、update、handler、bootstrap 已经收敛
|
|
|
|
这意味着 React 侧现在可以更放心地继续拆：
|
|
|
|
- 页面入口不会再同时背负太多主进程耦合
|
|
- 更新弹窗可以直接依托已收敛的 update service / preload facade
|
|
- Cleaner 页面可以聚焦 UI 与状态，不必再同时处理主进程边界混乱问题
|
|
|
|
## 9. 后续建议
|
|
|
|
建议执行方式如下：
|
|
|
|
1. 先从 `Phase 1` 开始，优先收敛 `App.tsx`
|
|
2. 每完成一个阶段，单独提交
|
|
3. 对 `Cleaner` 和 `UpdateDialog` 每完成一轮都补测试
|
|
4. 在大页面拆分后，再做 bundle 与懒加载优化
|
|
|
|
如果后续决定正式执行，本计划可作为 React 渲染层重构的主索引文档持续维护。
|