Langfuse 前端 React Effect 重构实战八种去useEffect模式与状态所有权指南【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse在 Langfuse 的 Web 前端Next.js tRPC TanStack Query Zustand 技术栈中useEffect被严格限定为「与 React 之外的系统做同步」的工具。本文以仓库中 refactoring-patterns.md 为骨架完整讲解八种可落地的 Effect 重构模式并结合 SKILL.md 给出的决策规则与迁移工作流以及web/src下的真实实现佐证如 table-selection-store.ts、DismissController.tsx说明如何把「由数据派生 → 由事件驱动 → 由外部系统同步」的职责分清楚。读完本文你将掌握一套可复制、可验证的 Effect 消除与状态所有权重构方案能让表单、表格、弹窗等高频场景不再依赖 Effect 传递状态。一、核心原则Effect 只属于 React 之外的世界在动手重构之前先确立唯一的设计立场不要默认添加useEffect。它只用于让组件与一个 React 不控制的具体外部系统同步如果没有这样的外部系统就删掉这个 Effect。判断一个 Effect 是否该保留需要依次回答四个问题源自 SKILL.md正在同步的是哪个外部系统是什么启动或更新这次同步需要怎样的清理逻辑来防止泄漏或重复订阅为什么事件处理器、查询 API、渲染期派生、条件挂载或现有集成 Hook不能承担这个行为如果第一个问题没有具体答案就不应该使用 Effect。同时要警惕「换汤不换药」式的逃避如果一个 Effect 只是把 props 或查询数据写进 React/Zustand 状态那么它默认是可删除的。不能通过改用useLayoutEffect、压制依赖 lint、把同样的同步逻辑藏进自定义 Hook或添加 ESLint disable 来回避设计问题。二、八种重构模式详解模式一先门控必需数据再挂载子组件Gate Required Data, Then Initialize the Child不要让一个有状态表单在缺少默认值时先挂载、再在 paint 之后修补。正确的做法是让持有查询的父组件负责 loading/error 状态只在数据完整时用完整初始值挂载表单。function UserFormContainer({ userId }: { userId: string }) { const userQuery api.users.byId.useQuery({ userId }); if (userQuery.isPending) return Spinner /; if (userQuery.isError) return ErrorPage /; const initialValues toUserFormValues(userQuery.data); return UserForm key{userQuery.data.id} initialValues{initialValues} /; } function UserForm({ initialValues }: { initialValues: UserFormValues }) { const [values, setValues] useState(() initialValues); return UserFields values{values} onChange{setValues} /; }这里的key明确表达了语义切换用户即丢弃上一份草稿。这是一个刻意的身份边界而不是靠 Effect 在背后悄悄重置。关于key的选择需要格外克制不要把查询更新的时间戳或版本号放进key除非每一次 refetch 都应当有意丢弃编辑内容。如果用户需要自主决定何时采纳服务端新值就应当暴露一个 reset/refresh 操作而不是让 refetch 静默覆盖输入。Langfuse 代码库中大量使用这种useState(() ...)惰性初始化来承载「每个实体/页面拥有一份独立状态」的场景例如 ExperimentsTable.tsx 中的useState(() createExperimentsTableStore())、DatasetsTable.tsx 中的useState(() createDatasetsTableStore())以及 EvaluatorsPage.tsx 中的useState(() createEvaluatorsTableStore())。初始化器只执行一次与「数据就绪后才挂载」的模式天然契合。模式二从服务端状态派生客户端状态的合法性Derive Valid Client State from Server State保留用户存储的意图并派生它当前是否有效而不是在每次查询数据变化时覆盖选择存储。const selectedUserId useUserStore((state) state.selectedUserId); const selectedUser users.find((user) user.id selectedUserId) ?? null;这种写法避免了同步 Effect同时保留了足够信息来展示「当前选择已失效」或在服务端值重新出现时恢复它。派生值应通过一个 selector 或自定义 Hook暴露防止调用方绕过校验规则直接读取原始状态。对应到 Langfuse 实践中表格行选择就是一个「保留意图 派生有效性」的绝佳案例。见 table-selection-store.ts它用 vanilla Zustand 保存rowSelection、selectAll等原始意图而组件侧通过useTableRowIsSelected、useTableSelectAll、useTableRowSelection这些封装了useSyncExternalStore的派生 Hook 读取选择状态并把「store 不存在时」的回退值作为第三个参数传入——选择状态完全不需要 Effect 来搬运。模式三渲染期计算冗余值Compute Redundant Values During Render// Avoid: useEffect(() setFullName(${first} ${last}), [first, last]); const fullName ${first} ${last};把昂贵或复杂的转换提取为纯函数并直接单测只有测量证明纯计算确实昂贵、或消费者确实需要引用稳定性时才考虑 memoization。在 Langfuse 前端中类似的派生逻辑如日期范围、格式化展示值大量沉淀在web/src/utils与web/src/features/filters等目录的纯函数模块中配合*.clienttest.ts直接对纯函数做行为测试。模式四把用户触发的工作放进 ActionPut User-Triggered Work in an Action不要把「当这个 flag 变为 true 时就提交」编码成状态 Effect 的组合。应当从导致它的那个事件里调用工作流。type SaveWidgetDependencies { store: WidgetStore; queryClient: QueryClient; mutateAsync: (input: SaveWidgetInput) PromiseWidget; }; export async function saveWidget({ store, queryClient, mutateAsync, }: SaveWidgetDependencies) { const input selectWidgetInput(store.getState()); const widget await mutateAsync(input); store.getState().markSaved(widget.id); await queryClient.invalidateQueries({ queryKey: [widgets] }); }组件可以用 Hook 取得mutateAsync或 queryClient然后在onClick/onSubmit中把依赖传给 action。vanilla Zustand store 可以被 action 直接读取。关键约束action 本身绝不能调用 Hook。模式五服务端数据交给查询 APIUse Query APIs for Server Data不要在 Effect 里 fetch 服务端数据然后把loading、error、data镜像进本地 state——tRPC/React Query 完全有能力拥有这个生命周期。查询数据应始终作为服务端状态保留渲染值从它派生。对于 mutation 之后必须执行的命令式工作把序列保持在mutation 回调或由事件调用的具名 action 中。不要引入一个「mutation 已完成」的 flag 让另一个 Effect 去监听——这正是 SKILL.md 快速气味测试中点名的反模式「设置 flag → 让 Effect 执行动作 → 清除 flag」。模式六通过身份或显式事件重置状态Reset State Through Identity or an Explicit Event当本地状态归属于某个特定实体时必须从以下四种行为中明确选择一种后台数据 refetch 时保留草稿实体身份变化时用 key 重挂载keyed 子组件通过刻意的cancel/reset/reload 事件重置消除本地状态让服务端/查询值成为唯一事实来源。绝不能放任 Effect 隐式选择——因为它常常在后台 refetch 时覆盖用户输入。模式一中的key{userQuery.data.id}就是「实体身份变化即重挂载」的实现而「显式事件重置」对应的则是表单页面上独立的 reset/refresh 按钮二者语义必须刻意区分。模式七只保留外部系统同步Retain Only External-System Synchronization当组件必须连接 React 不控制的东西时Effect 才是恰当的useEffect(() { const unsubscribe externalStore.subscribe(handleChange); return unsubscribe; }, [externalStore, handleChange]);其他合法案例包括ResizeObserver、浏览器事件监听器、计时器、命令式第三方组件。如果现有订阅 Hook如useSyncExternalStore能更直接地建模这类集成应优先使用。设置与清理必须对称且不要在该集成 Effect 中混入普通的数据派生。Langfuse 前端对此有大量实证table-selection-store.ts 用useSyncExternalStore订阅 vanilla Zustand storeDismissController.tsx 用useSyncExternalStore感知 hydration 完成SessionMetadataJsonPathControl.tsx 以useSyncExternalStore(subscribe, getSnapshot, EMPTY_CACHE_SNAPSHOT)三参形式提供服务端快照回退。它们都遵循「订阅 → 快照 → 清理」的对称生命周期。模式八外部集成优先条件挂载Prefer Conditional Mounting for External Integrations如果某个外部集成只应在前置条件满足后存在就把前置条件做成组件边界而不是 Effect 内部的守卫。function PlayerArea({ ready }: { ready: boolean }) { return ( PlayerShell ready{ready} / {ready ? PlayerInstance / : null} / ); }集成组件现在只有一个生命周期挂载即连接卸载即断开。当实体 ID 变化时用key提供全新生命周期即可。这与模式一互为表里——数据未就绪时不挂载而不是挂载后用 Effect 等待数据。三、快速气味测试遇到这些形状就该重构在 Langfuse 前端评审或新增代码时出现以下任何一种形状都应触发重构依据 SKILL.mduseEffect(() setX(deriveFromY(y)), [y])—— 典型的冗余状态复制fetch 数据后镜像为setState—— 应交给查询 API设置 flag、让 Effect 执行动作、再清除 flag —— 应放进事件处理器链式 Effect一次 state 写入触发下一个 Effect —— 应改为事件/派生驱动因 ID 或 prop 变化而重置本地状态 —— 应改用 key 或显式事件在 Effect 内部守卫集成而组件本可以在前置条件成立后才挂载 —— 应条件挂载。四、仓库级迁移工作流从清点到验收SKILL.md 提供了一套可重复的五步流程保证重构既彻底又可验证1. 确立行为边界Establish the Behavior Boundary识别状态所有者、查询所有者、用户事件、外部系统与 loading/error 状态。若是修 bug先写失败测试并确认其确实失败若是行为保持型迁移复用现有覆盖只在草稿保留、实体变化、refetch、提交、清理等行为风险点上补充聚焦测试。不要写检查源码结构、或断言「某个 Hook 不存在」的测试。2. 盘点每一个 EffectInventory Every Effect搜索整个目标模块含测试与 storiesrg -n \b(use(?:Layout)?Effect|React\.use(?:Layout)?Effect)\b web/src/features/feature把每个结果分类为渲染派生 / 查询到本地状态初始化 / 客户端-服务端状态同步 / 用户事件或异步工作流 / 外部系统集成 / 仅测试用 harness 行为。不要只看数量要记录每个 Effect 的触发条件、它写入或控制什么以及对应的替换模式。3. 一次只重构一个语义接缝Refactor One Semantic Seam at a Time推荐顺序用纯派生替换冗余状态拆分「持有数据的父组件」与「有状态的子组件」把事件驱动工作移到处理器或外部 action把不可避免的集成隔离进窄 Hook删除死状态、守卫、依赖与 import。保持用户可见行为稳定不要把无关的文件移动、视觉改动和状态架构改动塞进同一个切片。4. 完成子模块迁移Complete a Submodule Migration每个切片后重新盘点。宣布子模块「干净」前需确认每个原始 Effect 都有交代没有 Effect 只是被藏进包装 Hookrefetch 不会覆盖本地编辑实体变化具备刻意的保留/重置语义复杂 action 在不渲染该功能时也可调用任何真实保留的外部集成 Effect 都有文档说明。5. 验证Verify至少运行变更行为的聚焦客户端测试对迁移路径跑 ESLint再跑pnpm --filter web run lint状态或 action 接口变化时做类型检查用种子数据做真实浏览器回归再次盘点 Effect 清单证明目标范围已干净。最后报告命令摘要与保留 Effect 的外部系统理由。五、Langfuse 前端中的落地佐证这些模式并非纸上谈兵web/src内已有稳定实践模式仓库实证说明模式一惰性初始化 keyChatMessages/index.tsx 的key{message.id}ExperimentsTable.tsx、DatasetsTable.tsx、EvaluatorsPage.tsx 的useState(() createXxxStore())实体级本地状态通过惰性初始化和key管理生命周期模式二 / 模式七table-selection-store.tsvanilla Zustand 保存选择意图useSyncExternalStore派生展示值模式七DismissController.tsx、SessionMetadataJsonPathControl.tsx用useSyncExternalStore取代「同步类」Effect模式四 / 模式五各 feature 下actions/*.ts与 mutation 回调提交/刷新等命令式工作由事件触发action 持有 store/queryClient 依赖绝不调用 Hook六、结语把 Effect 重新定位为「最后手段」对 Langfuse 前端而言重构 Effect 的本质是重新分配状态所有权能派生就不要存储能由查询拥有就不要镜像能由事件驱动就不要用 flag 接力能条件挂载就不要在 Effect 里守卫只有真正的外部系统订阅、观察者、计时器、命令式组件才值得一个对称的集成 Effect。重构时坚持「一次一个语义接缝、行为测试护航、逐模块清点验收」的工作流就能在不改变用户可见行为的前提下让组件树变得更可预测、更少竞态、更易测试。进一步的决策细则与执行流程可继续阅读 SKILL.md 与其引用文档 refactoring-patterns.md后者也是本文全部模式与代码示例的原始出处。【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考