Effector 状态管理开发指南

技能文档

---
name: aiko-atami-effectorjs
title: Effector 状态管理开发指南
category: 开发工具
description: 基于 Effector v23+ 现代模式进行状态管理的设计、重构与审查，覆盖 createStore/createEvent/createEffect 建模、sample/attach/split 数据流编排、fork/allSettled 作用域安全的 SSR、React/Solid/Vue 集成与 useUnit 绑定，以及 watch 业务逻辑、effect 内命令式调用、getState 业务取数等反模式的修复与旧版迁移。当用户使用 Effector 开发或评审前端状态管理代码时触发。触发词：Effector、状态管理、sample 数据流、SSR 作用域、useUnit。
---

# Effector 状态管理开发指南

使用本技能为新增功能、重构与代码评审产出确定性的、作用域安全的 Effector 方案。

## 技能工作流

### 步骤1：请求分类

- `modeling`（建模）：创建或扩展 store/event/effect
- `refactor`（重构）：用声明式数据流替换反模式
- `ssr`（服务端渲染）：实现或调试作用域安全的 SSR
- `review`（评审）：评估风险、回归与缺失的测试
- `legacy-migration`（旧版迁移）：把旧模式安全迁移到 v23+ 现代写法

### 步骤2：按需加载参考资料

- 始终从 [references/core-patterns.md](references/core-patterns.md) 开始
- 核心模式之后必须加载 [references/lint-derived-best-practices.md](references/lint-derived-best-practices.md)，以落实插件级最佳实践
- 任务涉及应用启动、初始化顺序、测试、作用域或 SSR 时，加载 [references/explicit-start.md](references/explicit-start.md)
- 任务涉及执行顺序、`watch`、时序、竞态类行为或副作用放置时，加载 [references/computation-priority.md](references/computation-priority.md)
- 出现 React/SSR/作用域时，加载 [references/react-ssr-scope.md](references/react-ssr-scope.md)
- 出现 Solid 集成时，加载 [references/solid-scope.md](references/solid-scope.md)
- 出现 Vue 集成时，加载 [references/vue-scope.md](references/vue-scope.md)
- 修复或评审既有逻辑时，加载 [references/anti-patterns-and-fixes.md](references/anti-patterns-and-fixes.md)
- 出现弃用 API/旧版导入时，加载 [references/legacy-migration-map.md](references/legacy-migration-map.md)
- 最后以 [references/checklists.md](references/checklists.md) 的验收标准收尾

### 步骤3：按顺序构建方案

- 建模原子 store 与显式 event
- 定义显式应用启动事件（`appStarted`），保持启动接线声明式
- 副作用一律放入 effect
- 优先用 `sample` 连接单元；effect 组合使用 `attach`
- 对测试、SPA 启动边界与 SSR 应用作用域优先规则（`fork`、`allSettled`）
- UI 框架层使用 `useUnit` 并正确接好 Provider

### 步骤4：产出结果

- 提出的模型拓扑（store/event/effect 及各自职责）
- 接线代码片段（`sample`、`attach`，必要时 `split`）
- 作用域/SSR 说明（如适用）
- 命名、数据流、作用域、React 约束等 lint 合规说明
- 测试场景与验收清单

## 默认约定

- 目标为 Effector v23+ 现代版本
- 弃用/旧模式视为迁移对象，而非默认写法
- 优先最小且显式的单元图，而非炫技抽象
- 以 `eslint-plugin-effector` 提炼的实践作为基线约束
- 说明与评审使用与官方术语表一致的用词

## 术语对齐（Effector）

- `Unit`（单元）：包含 `Store`、`Event`、`Effect`、`Domain`、`Scope`
- `Common unit`（通用单元）：仅指 `Store`、`Event`、`Effect`（多数 API 的响应式更新源）
- `Derived store`（派生 store）：由其他 store 构建的只读 store（`map`、`combine` 及 `.pending` 等 effect 派生 store）
- `Derived store` 约束：不得直接修改，也不得作为 `sample` 的 `target`
- `Reducer`：`store.on(...)` 处理器必须返回下一个状态；返回 `undefined` 或同一引用（`===`）视为不更新
- `Watcher`：仅用于副作用/调试观测；watcher 的返回值会被忽略
- `Subscription`（订阅）：退订逻辑属于基础设施关注点，避免在业务逻辑中手工管理订阅
- `Purity`（纯度）：纯函数（`map`、`.on`、转换回调）不得命令式调用 event/effect
- `Domain`：单元的命名空间；`onCreate*` 钩子仅可用于基础设施级横切关注点（日志/埋点），不用于业务编排

## 硬性约束

- 不得把业务逻辑放进 `watch`
- 编排优先 `sample`，而非 `forward`/`guard`
- 遵守计算优先级：`map`/`.on` 保持纯函数，纯计算阶段不放副作用
- 能用声明式接线表达时，不得在 effect 体内命令式调用 event/effect
- 不得用 `$store.getState()` 做业务数据流；状态经 `sample` 的 `source` 传入
- 派生 store 不得作为 `sample` 的 `target`；target 只能是可写单元/event/effect
- `sample`/`guard` 选项按语义顺序书写：`clock -> source -> filter -> fn -> target`
- 避免歧义 `target` 用法（不得同时赋值返回结果又显式传 `target`）
- 避免 `clock`/`source` 数组内重复单元，以及同一 store-event 对重复 `.on`
- 不允许没有运行时效果的 `sample`/`guard`（必须有 `target` 或捕获返回结果）
- 不得在运行时动态创建单元
- 命名显式（`$store`、`eventHappened`、`someFx`）
- React 中用 `useUnit` 绑定可调用单元；JSX 处理器中避免直接使用裸 event/effect

## 旧代码处理

遇到旧代码时：

1. 先保持行为不变
2. 显式标记旧代码段落
3. 以迁移安全的 diff 策略给出现代替换方案
4. 先补齐验证等价性的测试，再清理旧代码

使用说明

# Effector 状态管理开发指南

按 Effector v23+ 现代规范做状态管理的建模、重构与评审，输出作用域安全、可测试的方案。

## 使用

对话中直接提出 Effector 相关需求即可，例如：

- 「帮我用 Effector 建模这个购物车功能」
- 「审查这段 Effector 代码，把 watch 里的业务逻辑改成声明式写法」
- 「这个应用要做 SSR，如何用 fork/allSettled 保证作用域安全」
- 「把项目里的 forward/guard 旧写法迁移到 sample」

技能会先分类请求（建模/重构/SSR/评审/旧版迁移），按需加载对应参考文档后给出模型拓扑、接线代码与验收清单。

## 工作原理

以 core-patterns（建模与 sample/attach/split 编排）为基线，按任务加载 SSR 作用域、React/Solid/Vue 集成、反模式修复、旧版迁移等专题文档；所有建议遵循 eslint-plugin-effector 提炼的命名与数据流约束，并以计算优先级模型保证时序确定性。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。