wevu-best-practices

wevu 最佳实践

目的

在遵守 wevu 约束的同时，以 Vue 风格的便捷性实现小程序运行时逻辑。明确生命周期时机、响应式更新和组件契约。

触发信号

• 用户询问如何使用 wevu 实现页面／组件逻辑。
• 用户询问生命周期钩子的触发时机或 setup 模式。
• 用户询问 props／emit 契约、事件 detail 载荷或双向绑定模式。
• 用户询问 store 架构、storeToRefs 或类型推断行为。
• 用户报告运行时行为与 Vue 3 Web 端行为不同。

适用边界

当主要问题涉及运行时行为和状态／事件契约时，使用此技能。

以下情况不要将此技能作为主要技能：

• 任务涉及构建／配置／分包／CI 编排。使用 weapp-vite-best-practices。
• 任务主要涉及 .vue 宏／模板语法兼容性。使用 weapp-vite-vue-sfc-best-practices。
• 任务涉及原生小程序的分阶段迁移。使用 native-to-weapp-vite-wevu-migration。

快速开始

1. 检查运行时 API 的导入方式和组件注册模式。
2. 确认钩子注册时机以及组件／页面边界。
3. 统一状态／事件绑定模式（ref/reactive、emit、bindModel）。
4. 通过有针对性的运行时测试或单元测试进行验证。

执行流程

1. 明确运行时约定

• 仅从 wevu 导入运行时 API。
• 页面和组件均使用 defineComponent 注册。
• 使用选项式 data 时，将其定义为函数。

2. 验证边界和时机

• 仅在页面上下文中使用页面钩子。
• 在 setup() 中同步注册生命周期钩子。
• 避免在 await 之后注册钩子。

3. 统一响应式更新模式

• 优先使用 ref/reactive/computed 派生状态。
• 避免进行大型、不透明的状态写入；优先采用细粒度的响应式更新。
• 表单／事件语义较复杂时，使用显式绑定。

4. 定义事件和双向绑定契约

• 使用 ctx.emit(event, detail, options)，并遵循小程序语义。
• 对可复用的字段契约，优先使用 bindModel／useBindModel。
• 涉及值转换时，说明解析器／格式化器的行为。

5. 遵循 store 使用规范

• 对简单领域和可靠的 TS 类型推断，优先使用 Setup Store。
• 解构状态／getter 时，使用 storeToRefs。
• 只有在需要全局插件／持久化行为时，才引入 createStore()。

6. 明确验证兼容性

• 避免在运行时业务逻辑中使用仅限 DOM／浏览器的 API。
• 在 Node／Vitest 中，为桥接测试模拟 Component／wx。
• 将平台差异视为明确约束，而非隐式错误。

约束

• 避免在 setup() 中于 await 之后注册钩子。
• 对 store，避免不使用 storeToRefs 直接解构状态。
• 避免在模板或生命周期时机上依赖未文档化的 Vue Web 专属行为。
• 避免将不可序列化的原生实例对象返回到模板状态中。

输出要求

应用此技能时，返回：

• 运行时风险摘要（生命周期／状态／事件／store）。
• 具体到文件的修改内容。
• 与 Vue 3 Web 运行时相比的兼容性注意事项。
• 最少的验证命令及预期信号。

完成检查

• API 从 wevu 导入，业务代码中不从 vue 运行时导入。
• 页面／组件边界使用一致。
• 钩子同步注册，时机可预测。
• store 使用遵循单例 + storeToRefs 约定。
• 模板／事件绑定符合小程序支持的语义。

参考资料

• references/component-patterns.md
• references/store-patterns.md
• references/troubleshooting-checks.md