effectorjs

EffectorJS 技能

使用此技能，为新功能、重构和代码审查生成确定性且作用域安全的 Effector 解决方案。

工作流

1. 对请求分类：

• modeling：创建或扩展 store、event、effect。
• refactor：用声明式流程替换反模式。
• ssr：实现或调试作用域安全的 SSR。
• review：评估风险、回归问题和缺失的测试。
• legacy-migration：安全地将旧模式迁移到现代 v23+。

2. 仅加载所需的参考资料：

• 始终从 references/core-patterns.md 开始。
• 在核心模式之后始终加载 references/lint-derived-best-practices.md，以遵循由插件支持的最佳实践。
• 当任务涉及应用引导、启动逻辑、初始化顺序、测试、作用域或 SSR 时，添加 references/explicit-start.md。
• 当任务涉及顺序、watch、时序、类似竞态的行为或副作用放置位置时，添加 references/computation-priority.md。
• 当任务涉及 React/SSR/作用域时，添加 references/react-ssr-scope.md。
• 当任务涉及 Solid 集成时，添加 references/solid-scope.md。
• 当任务涉及 Vue 集成时，添加 references/vue-scope.md。
• 当任务需要修复或审查现有逻辑时，添加 references/anti-patterns-and-fixes.md。
• 当存在已弃用的 API/导入时，添加 references/legacy-migration-map.md。
• 以 references/checklists.md 作为最后一项，检查验收标准。

3. 按以下顺序构建解决方案：

• 建模原子 store 和显式 event。
• 定义显式的应用启动事件（appStarted），并保持启动流程以声明式方式连接。
• 将副作用移至 effect。
• 优先使用 sample 连接单元；使用 attach 组合 effect。
• 在测试、SPA 引导边界和 SSR 中优先遵循作用域规则（fork、allSettled）。
• 对于 UI 框架，使用 useUnit 并正确配置 provider。

4. 输出约定：

• 提出模型拓扑（store/event/effect 及其职责）。
• 提供连接代码片段（必要时使用 sample、attach、split）。
• 在适用时说明作用域/SSR 注意事项。
• 说明符合 lint 派生的命名、数据流、作用域和 React 约束的情况。
• 提供测试场景和验收清单。

默认设置

• 目标版本为现代 Effector v23+。
• 将已弃用/旧版模式视为迁移目标，而非默认做法。
• 优先采用精简、明确的单元图，而不是巧妙的抽象。
• 将 eslint-plugin-effector 派生的实践视为基础约束。
• 在说明和审查中使用与术语表一致的术语。

术语表对齐（Effector）

• Unit：包括 Store、Event、Effect、Domain、Scope。
• Common unit：仅包括 Store、Event、Effect（许多 API 的响应式更新源）。
• Derived store：由其他 store 构建的只读 store（map、combine、effect 派生的 store，例如 .pending）。
• Derived store 约束：不得直接修改，也不得用作 sample 的 target。
• Reducer：store.on(...) 处理器必须返回下一个状态；返回 undefined 或相同引用（===）表示 store 不会更新。
• Watcher：仅用于副作用/调试可观测性；其返回值会被忽略。
• Subscription：将取消订阅处理器视为基础设施层面的关注点；避免在业务逻辑中手动管理订阅。
• Purity：纯函数（map、.on、转换回调）不得命令式调用 event/effect。
• Domain：单元的命名空间；onCreate* 钩子可用于基础设施层面的横切关注点（日志/监测），但不应用于业务流程编排。

防护原则

• 不要在 watch 中放置业务逻辑。
• 编排时优先使用 sample，而非 forward/guard。
• 遵循计算优先级：保持 map/.on 纯净，并避免在纯计算阶段产生副作用。
• 如果声明式连线能够表达流程，就不要在 effect 函数体中命令式调用事件或 effects。
• 不要使用 $store.getState() 处理业务数据流；通过 sample 的 source 传递状态。
• 不要将派生 store 用作 sample 中的 target；target 只能是可写单元、事件或 effects。
• 按语义顺序排列 sample/guard 选项：clock -> source -> filter -> fn -> target。
• 避免含义模糊的 target 用法（不要同时进行结果赋值并显式指定 target）。
• 避免在 clock/source 数组中重复使用单元，也不要为同一 store-event 对添加重复的 .on 处理器。
• 不要使用没有运行时效果的 sample/guard（必须有 target 或捕获结果）。
• 不要在运行时动态创建单元。
• 使用明确的命名（$store、eventHappened、someFx）。
• 在 React 中，使用 useUnit 绑定可调用单元；避免在 JSX 处理器中直接使用原始事件或 effects。

旧版代码处理

如果存在旧版代码：

1. 首先保持行为不变。
2. 明确标记旧版部分。
3. 提出采用安全迁移差异策略的现代替代方案。
4. 添加测试，在清理之前证明行为一致。