11.5 避坑清单

> **本节目标**：提供上线前必查的 30 项检查清单，覆盖正确性、性能、架构、可维护性、安全。

11.5.1 正确性（10 项）

- [ ] **1. 所有命令方法都调用了 `cx.notify()`**：状态变化后必须通知，否则 UI 不更新 - [ ] **2. 异步任务在 `this.update` 闭包中修改状态**：后台线程不能直接访问 `&mut self` - [ ] **3. `each` 列表都有稳定的 `key`**：用业务 ID，不用数组索引 - [ ] **4. 双向绑定的字段类型与控件匹配**：`<input type="number">` 绑定 `i32` 而非 `String` - [ ] **5. 计算属性是纯函数**：不修改状态、不调用 `cx.notify()` - [ ] **6. 命令签名与事件载荷匹配**：`on-change` 对应 `ChangeEvent`，不能错配 - [ ] **7. `if` 条件返回 bool**：不返回 `Option` 或 `i32` - [ ] **8. 组件必填 props 都已传入**：LSP 会警告，但上线前再确认 - [ ] **9. 事件对象的数据类型正确**：`ev.data::<u64>()` 与触发时传入的类型一致 - [ ] **10. 错误分支有 UI 反馈**：失败时显示错误，不要静默吞掉

11.5.2 性能（6 项）

- [ ] **11. 循环中不调用 `cx.notify()`**：批量修改后单次 notify - [ ] **12. 高频输入有防抖**：搜索框、自动保存等场景 - [ ] **13. 大列表使用 `VirtualList`**：超过 1000 项必须虚拟化 - [ ] **14. 计算属性依赖范围最小化**：不依赖整个列表，依赖具体字段 - [ ] **15. 重计算在后台线程**：用 `cx.background_executor().spawn` - [ ] **16. 渲染耗时 < 16ms**：用 `cx.observe_render_time` 监控

11.5.3 生命周期与资源（5 项）

- [ ] **17. `on_unloaded` 中取消所有异步任务**：保存 `Task` 句柄，unload 时 abort - [ ] **18. 订阅在 unload 时自动清理**：`Subscription` 保存在字段中，drop 时自动取消 - [ ] **19. 文件 / 网络句柄正确关闭**：用 RAII 或在 unload 中显式关闭 - [ ] **20. 定时器在 unload 时清除**：`Timer` 句柄保存并 abort - [ ] **21. 无循环引用**：跨视图引用用 `WeakEntity`

11.5.4 架构（5 项）

- [ ] **22. ViewModel 字段不超过 15 个**：超过则拆分 - [ ] **23. 组件不直接调用 Service**：组件无业务知识 - [ ] **24. Model 不依赖 GPUI**：可独立编译 - [ ] **25. 视图之间无直接 `use`**：通过 Context 事件通信 - [ ] **26. 命令方法不超过 30 行**：超过则抽 Service 方法

11.5.5 可维护性（2 项）

- [ ] **27. 命名遵循约定**：ViewModel 后缀、命令动词开头、计算属性名词 - [ ] **28. 关键逻辑有注释**：业务规则、性能 hack、临时方案

11.5.6 测试（2 项）

- [ ] **29. Model 与 ViewModel 的纯逻辑有单测**：覆盖边界条件 - [ ] **30. 关键用户流程有集成测试**：登录、提交、加载等

11.5.7 使用清单的方法

上线前

逐项过一遍，每项确认“已检查”或“不适用”。任何未通过的项目都要在上线前解决或有明确理由。

代码审查时

把清单作为 review 的检查表，避免遗漏常见问题。

重构时

重构后过一遍清单，确保没有引入新的反模式。

11.5.8 清单的演进

这份清单是起点，不是终点。每个团队应当根据自身经验补充：

- 项目特有的坑 - 业务领域的特殊要求 - 团队约定的规范

把踩过的坑沉淀回清单，让它成为团队的“防错字典”。

---

至此，本书正文结束。回顾全书：

- **第 1 章**建立对 RML 的整体认知 - **第 2-3 章**掌握标记与绑定两大基石 - **第 4-5 章**学会业务逻辑与事件处理 - **第 6-7 章**学会组件与样式封装 - **第 8 章**掌握生命周期与资源管理 - **第 9 章**建立架构思维 - **第 10 章**掌握工具链与调试 - **第 11 章**把知识落到实战

RML 的设计哲学是“深进浅出”——底层是编译期代码生成、绑定引擎、增量渲染，表层是 HTML 友好的标记和纯 Rust 业务逻辑。理解底层让你能调试和优化，掌握表层让你能高效交付。

祝你在 RML 的实践中构建出优雅、健壮、可维护的桌面应用。

← 返回 [总目录](../INDEX.md)