docs: add electron optimization plan
This commit is contained in:
Misaka
@@ -0,0 +1,377 @@
|
||||
# Electron 最佳实践优化计划
|
||||
|
||||
本文档基于 `$electron-best-practices` 对当前项目的审查结果整理而成，目标不是一次性重构整个 Electron 应用，而是按照“低风险、可验证、逐步收敛”的方式，分阶段提升主进程、preload、IPC、更新模块和工程配置的可维护性。
|
||||
|
||||
## 1. 计划背景
|
||||
|
||||
当前项目已经具备了较好的 Electron 基础结构：
|
||||
|
||||
- 主进程、preload、renderer 三层已分离
|
||||
- Renderer 通过 `contextBridge` 暴露能力
|
||||
- IPC 统一采用 `invoke/handle` 模式
|
||||
- 大部分主进程能力已经模块化到 `ipc/` 与 `services/`
|
||||
|
||||
但从长期维护角度看，项目仍存在几个明显问题：
|
||||
|
||||
- `src/main/index.ts` 入口文件承担职责过多
|
||||
- 部分 IPC handler 仍然是“厚编排层”
|
||||
- `src/preload/index.ts` 更像“接口总表”，不是按领域划分的 facade
|
||||
- 更新链路实现较重，边界尚不清晰
|
||||
- 打包配置存在模板残留，容易误导维护者
|
||||
- Electron 边界层测试尚未系统化
|
||||
|
||||
## 2. 优化目标
|
||||
|
||||
本轮优化聚焦以下目标：
|
||||
|
||||
- 让主进程入口只负责启动顺序，不承载业务细节
|
||||
- 让 IPC handler 回归“薄壳”，把编排逻辑下沉到应用服务层
|
||||
- 让 preload API 按业务领域组织，而不是按主进程实现镜像
|
||||
- 收敛更新模块的职责边界，降低后续维护复杂度
|
||||
- 清理打包与发布配置中的模板残留
|
||||
- 为 Electron 边界补足更稳定的测试支撑
|
||||
|
||||
## 3. 优化范围
|
||||
|
||||
本计划优先处理 Electron 工程化与可维护性问题，不把安全性作为唯一优先目标，但会顺带处理那些同时影响可维护性的边界设计问题。
|
||||
|
||||
本次计划重点覆盖：
|
||||
|
||||
- 主进程启动与应用初始化
|
||||
- IPC handler 与 application service 分层
|
||||
- preload API 结构
|
||||
- 更新模块
|
||||
- 打包配置
|
||||
- Electron 边界层测试
|
||||
|
||||
暂不作为本轮首要目标：
|
||||
|
||||
- 大规模 UI 重构
|
||||
- 业务流程重写
|
||||
- ERP 自动化细节重构
|
||||
|
||||
## 4. 当前问题总览
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
MainIndex[src/main/index.ts]
|
||||
IPC[IPC Handlers]
|
||||
Preload[src/preload/index.ts]
|
||||
Update[update-service.ts]
|
||||
Builder[electron-builder.yml]
|
||||
Tests[tests/unit]
|
||||
|
||||
MainIndex -->|启动逻辑过重| Maintainability[维护成本上升]
|
||||
IPC -->|编排过厚| Maintainability
|
||||
Preload -->|API 面过大| Maintainability
|
||||
Update -->|职责边界不清| Maintainability
|
||||
Builder -->|模板残留| Maintainability
|
||||
Tests -->|边界覆盖不足| Maintainability
|
||||
```
|
||||
|
||||
## 5. 分阶段执行计划
|
||||
|
||||
### Phase 1: 收敛主进程入口
|
||||
|
||||
目标：
|
||||
|
||||
- 让 `src/main/index.ts` 只表达启动顺序
|
||||
- 把运行时检查、窗口创建、异常守卫、模块初始化拆到独立函数或模块
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `src/main/index.ts`
|
||||
- `src/main/bootstrap/` 下新增或调整模块
|
||||
|
||||
建议拆分方向：
|
||||
|
||||
- `bootstrapApp()`
|
||||
- `createMainWindow()`
|
||||
- `setupProcessGuards()`
|
||||
- `verifyPlaywrightRuntime()`
|
||||
- `initializeAppServices()`
|
||||
|
||||
预期收益：
|
||||
|
||||
- 降低入口文件修改风险
|
||||
- 提高启动问题排查效率
|
||||
- 为多窗口、多实例策略预留更清晰的扩展点
|
||||
|
||||
风险等级：
|
||||
|
||||
- 低到中
|
||||
|
||||
验证方式：
|
||||
|
||||
- 应用冷启动成功
|
||||
- 窗口创建与关闭流程正常
|
||||
- 异常日志、更新初始化、IPC 注册行为不回归
|
||||
|
||||
### Phase 2: 让 IPC Handler 回归薄壳
|
||||
|
||||
目标：
|
||||
|
||||
- 把 `cleaner-handler`、`auth-handler` 这类厚编排层下沉到应用服务
|
||||
- 明确 handler、application service、infrastructure service 的职责边界
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `src/main/ipc/cleaner-handler.ts`
|
||||
- `src/main/ipc/auth-handler.ts`
|
||||
- `src/main/ipc/update-handler.ts`
|
||||
- `src/main/services/`
|
||||
|
||||
建议拆分方向：
|
||||
|
||||
- `CleanerApplicationService`
|
||||
- `AuthApplicationService`
|
||||
- `UpdateApplicationService`
|
||||
|
||||
handler 只负责：
|
||||
|
||||
- 接收请求
|
||||
- 调用 service
|
||||
- 映射返回结构
|
||||
- 统一错误包装
|
||||
|
||||
预期收益：
|
||||
|
||||
- 提升主进程业务编排的可测试性
|
||||
- 降低 handler 文件复杂度
|
||||
- 让业务流程更容易被复用和替换
|
||||
|
||||
风险等级：
|
||||
|
||||
- 中
|
||||
|
||||
验证方式：
|
||||
|
||||
- 关键 IPC 流程回归测试
|
||||
- 原有 renderer 调用协议保持不变
|
||||
- 清理、登录、更新等主流程手动验收通过
|
||||
|
||||
### Phase 3: 重组 Preload API
|
||||
|
||||
目标：
|
||||
|
||||
- 把 `src/preload/index.ts` 从“大总表”改造成“按领域组织的 facade”
|
||||
- 稳定 renderer 对 Electron 能力的访问边界
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `src/preload/index.ts`
|
||||
- `src/preload/index.d.ts`
|
||||
- `src/main/types/`
|
||||
|
||||
建议拆分方向：
|
||||
|
||||
- `authApi`
|
||||
- `cleanerApi`
|
||||
- `updateApi`
|
||||
- `reportApi`
|
||||
- `fileApi`
|
||||
|
||||
建议原则：
|
||||
|
||||
- renderer 只拿到业务语义接口
|
||||
- preload 不原样映射主进程实现细节
|
||||
- 类型定义集中管理，避免 renderer 和 main 双边漂移
|
||||
|
||||
预期收益：
|
||||
|
||||
- 降低渲染层对 IPC 细节的耦合
|
||||
- 提高 preload 的可读性和可扩展性
|
||||
- 为后续做 runtime schema 校验打基础
|
||||
|
||||
风险等级：
|
||||
|
||||
- 中
|
||||
|
||||
验证方式：
|
||||
|
||||
- `npm run typecheck`
|
||||
- preload surface 测试通过
|
||||
- 主要页面功能回归正常
|
||||
|
||||
### Phase 4: 收敛更新模块边界
|
||||
|
||||
目标：
|
||||
|
||||
- 把更新服务中的下载、状态管理、安装协调、日志处理边界进一步明确
|
||||
- 降低自定义更新链路的维护成本
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `src/main/services/update/update-service.ts`
|
||||
- `src/main/ipc/update-handler.ts`
|
||||
- `src/main/types/`
|
||||
|
||||
建议拆分方向：
|
||||
|
||||
- `UpdateStateMachine`
|
||||
- `UpdateDownloadService`
|
||||
- `UpdateInstallCoordinator`
|
||||
- `UpdateEventBridge`
|
||||
|
||||
预期收益：
|
||||
|
||||
- 更新问题更容易定位
|
||||
- 状态流转更容易测试
|
||||
- 后续切换更新策略时影响面更小
|
||||
|
||||
风险等级：
|
||||
|
||||
- 中到高
|
||||
|
||||
验证方式：
|
||||
|
||||
- 更新检查、下载、安装提示链路验证
|
||||
- 状态事件顺序测试
|
||||
- 失败重试与异常日志验证
|
||||
|
||||
### Phase 5: 清理打包与发布配置
|
||||
|
||||
目标：
|
||||
|
||||
- 让构建配置更贴近当前项目实际维护范围
|
||||
- 清理无效、模板化或误导性的配置项
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `electron-builder.yml`
|
||||
- `package.json`
|
||||
- `scripts/` 下发布相关脚本
|
||||
- `docs/releases/` 与构建说明文档
|
||||
|
||||
重点检查项：
|
||||
|
||||
- 实际支持的平台范围
|
||||
- 发布目标与渠道
|
||||
- 无关权限说明
|
||||
- Windows 优先配置是否清晰
|
||||
|
||||
预期收益：
|
||||
|
||||
- 降低发版配置理解成本
|
||||
- 减少“看似支持、实际无人维护”的伪能力
|
||||
- 让发布文档与配置保持一致
|
||||
|
||||
风险等级：
|
||||
|
||||
- 低
|
||||
|
||||
验证方式：
|
||||
|
||||
- 本地构建通过
|
||||
- 发布脚本执行链路无回归
|
||||
- 文档与配置一致性核对完成
|
||||
|
||||
### Phase 6: 补强 Electron 边界层测试
|
||||
|
||||
目标：
|
||||
|
||||
- 让最容易劣化的 Electron 边界层拥有稳定回归保护
|
||||
|
||||
建议涉及文件：
|
||||
|
||||
- `tests/unit/preload-surface.test.ts`
|
||||
- `tests/unit/ipc-index.test.ts`
|
||||
- 新增 `tests/unit/update-service.*`
|
||||
- 新增 `tests/unit/cleaner-handler.*`
|
||||
- 新增 `tests/unit/auth-handler.*`
|
||||
|
||||
优先补测内容：
|
||||
|
||||
- 主进程启动编排
|
||||
- preload surface 稳定性
|
||||
- IPC 返回包装与错误路径
|
||||
- update service 状态迁移
|
||||
- handler 与 service 交互边界
|
||||
|
||||
预期收益：
|
||||
|
||||
- 降低后续拆分时的回归风险
|
||||
- 提升主进程重构信心
|
||||
- 让 Electron 工程层而非仅业务工具层获得测试保护
|
||||
|
||||
风险等级：
|
||||
|
||||
- 低
|
||||
|
||||
验证方式：
|
||||
|
||||
- 单元测试通过
|
||||
- 关键流程 smoke test 通过
|
||||
|
||||
## 6. 推荐执行顺序
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Phase 1 主进程入口收敛]
|
||||
B[Phase 2 IPC Handler 薄壳化]
|
||||
C[Phase 3 Preload API 重组]
|
||||
D[Phase 4 更新模块收敛]
|
||||
E[Phase 5 构建配置清理]
|
||||
F[Phase 6 Electron 边界测试补强]
|
||||
|
||||
A --> B
|
||||
B --> C
|
||||
C --> D
|
||||
D --> E
|
||||
B --> F
|
||||
C --> F
|
||||
D --> F
|
||||
```
|
||||
|
||||
建议优先顺序：
|
||||
|
||||
1. 先做主进程入口收敛
|
||||
2. 再做 IPC handler 薄壳化
|
||||
3. 然后重组 preload API
|
||||
4. 再处理更新模块
|
||||
5. 清理打包配置
|
||||
6. 在每一阶段同步补强测试
|
||||
|
||||
说明：
|
||||
|
||||
- `Phase 1` 与 `Phase 2` 性价比最高
|
||||
- `Phase 3` 适合在 handler 边界稳定后推进
|
||||
- `Phase 4` 风险相对更高，应放在前面边界清晰后再处理
|
||||
- `Phase 6` 不应完全放到最后，建议伴随每阶段一起推进
|
||||
|
||||
## 7. 每阶段完成标准
|
||||
|
||||
每一阶段建议采用统一完成标准：
|
||||
|
||||
- 相关模块职责边界变清晰
|
||||
- 对外接口保持兼容或完成显式迁移
|
||||
- `npm run lint` 通过
|
||||
- `npm run typecheck` 通过
|
||||
- 相关单元测试通过
|
||||
- 关键手工路径验证完成
|
||||
- 对应文档同步更新
|
||||
|
||||
## 8. 本计划与现有重构工作的衔接
|
||||
|
||||
当前已经完成的两轮重构：
|
||||
|
||||
- `validation-handler` 第一阶段拆分
|
||||
- `useCleaner` 第一阶段拆分
|
||||
|
||||
它们为本计划提供了两个基础：
|
||||
|
||||
- 团队已经验证“先拆超大文件，再保持对外行为不变”的策略可行
|
||||
- 后续继续拆 `cleaner-handler`、`preload`、`App` 时，可以沿用相同方法论
|
||||
|
||||
因此，Electron 向优化建议优先从主进程和边界层继续推进，而不是立刻进入更深的 UI 重构。
|
||||
|
||||
## 9. 后续建议
|
||||
|
||||
建议后续执行方式如下：
|
||||
|
||||
1. 先按本计划完成 `Phase 1`
|
||||
2. 每完成一个阶段，单独补一份重构说明文档
|
||||
3. 每个阶段单独提交，避免一次性大改
|
||||
4. 每阶段结束后重新运行 `lint`、`typecheck` 和对应测试
|
||||
|
||||
如果后续决定正式执行，本计划可作为 Electron 工程化重构的主索引文档持续维护。
|
||||
Reference in New Issue
Block a user