Polar 前端性能实践：把交互逻辑移入事件处理器（Put Interaction Logic in Event Handlers）

Polar 前端性能实践：把交互逻辑移入事件处理器（Put Interaction Logic in Event Handlers）

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar

导读

本文讲解 Polar 前端工程（clients/apps/web）所沉淀的 Vercel React 最佳实践规则之一：由用户明确动作（提交、点击、拖拽）触发的副作用，应直接在事件处理器中执行，而不是把动作建模成"状态 + useEffect"。读完本文，你将理解 useEffect 重复执行副作用的底层原理、两种写法的风险对比，并掌握一套可复用的判定标准与配套优化手段（收窄依赖、派生状态、ref 防重入、useEffectEvent），让表单、弹窗、列表等高频交互组件既少渲染又无重复副作用。

规则背景：它来自哪里，优先级如何

这条规则位于仓库中的技能包目录：

• 规则原文：clients/apps/web/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
• 技能包总览：clients/apps/web/.agents/skills/vercel-react-best-practices/SKILL.md

这是一套由 Vercel 工程团队维护、面向 React / Next.js 的性能优化指南，共 64 条规则，按影响程度分为 8 个类别。rerender-前缀对应第 5 类Re-render Optimization（重渲染优化），影响等级为MEDIUM（中等），其 impactDescription 明确写道：avoids effect re-runs and duplicate side effects（避免 effect 重复执行与副作用重复）。同类的相邻规则还有：

• rerender-dependencies.md（收窄 effect 依赖）
• rerender-derived-state-no-effect.md（渲染期计算派生状态）
• advanced-event-handler-refs.md（把事件处理器存进 ref，使用 useEffectEvent）

在编译后的完整文档 AGENTS.md 中，本规则编号为5.8 Put Interaction Logic in Event Handlers。也就是说，它属于"中等收益、高频出现"的一类问题：不修复不致命，但修复后对渲染次数与副作用正确性有直接、可感知的改善，非常适合在代码评审和 AI 辅助重构时自动套用。

核心问题：动作被建模成"状态 + effect"的两大隐患

规则原文给出的错误写法如下：

function Form() { const [submitted, setSubmitted] = useState(false) const theme = useContext(ThemeContext) useEffect(() => { if (submitted) { post('/api/register') showToast('Registered', theme) } }, [submitted, theme]) return <button onClick={() => setSubmitted(true)}>Submit</button> }

这段代码把"用户点击提交"这一一次性动作，转换成了"submitted状态从 false 变为 true"这一状态变更，再用 effect 监听状态变化去执行副作用。它至少带来两个问题：

1. effect 会在无关变更时重复执行

useEffect的依赖数组[submitted, theme]意味着：只要submitted或theme中任何一个值变化，effect 就会重新运行。theme来自ThemeContext，它属于全局共享上下文——主题切换、Context 提供者重渲染导致的新引用、甚至父组件任何一次导致 context value 变化的重渲染，都会让这个 effect 再次触发post('/api/register')。

更隐蔽的是：即使submitted已经是true，只要后续theme一变，if (submitted)依然成立，副作用会被再次执行。用户只点击了一次"提交"，网络请求却可能发出多次。这正是 impactDescription 中 "duplicate side effects"（副作用重复）的典型场景。

2. 动作语义被错误地"持久化"了

submitted是一个布尔状态，一旦置为true就不会自动复位。它把"发生过的动作"变成了"一直存在的状态"，副作用从"应该执行一次"退化为"只要依赖变化就检查一次"。这类状态本质上是不该存在于 state 中的瞬态信号，与 rerender-derived-state-no-effect.md 中"不要为了响应状态变化而在 effect 里设置 state"的教训同源：凡是从既有 props/state/事件能直接得出的东西，都不应再引入一套状态 + effect 的间接链路。

另外需要说明：在 React 开发模式（StrictMode）下 effect 会被刻意地挂载→卸载→再挂载，这会让上述错误写法在开发阶段就暴露出"重复提交"问题，但生产环境的重复触发（依赖变化导致）则更隐蔽，需要靠依赖收窄或直接移入事件处理器来根治。

正确做法：直接在事件处理器里执行

规则给出的正确写法：

function Form() { const theme = useContext(ThemeContext) function handleSubmit() { post('/api/register') showToast('Registered', theme) } return <button onClick={handleSubmit}>Submit</button> }

核心变化：

1. 删除了submitted状态，不再用状态表达动作；
2. post与showToast被移入handleSubmit，仅在用户点击时同步执行一次；
3. theme虽然仍在读取，但它只参与"这次点击发生时"的取值，不会因为 context 后续变化而触发任何副作用重放。

由于事件处理器天然"只跑一次"（对应一次用户交互），重复提交与无关重渲染引发的副作用都从机制上被消除。需要注意的是，theme仍会被组件读取，这本身不构成多余的重渲染——规则关注的是副作用不要因依赖变化而重放，而读取 context 值做渲染是正常的 React 数据流。

判定标准：什么代码该移进事件处理器

规则原文引用 React 官方文档的判定问题："Should this code move to an event handler?"（这段代码应该移到事件处理器吗？）。结合 SKILL.md 的触发场景（编写新组件、评审代码、重构性能问题），可以归纳出以下实操判定标准：

核心直觉是：useEffect 的职责是"与外部系统同步"，而不是"执行用户操作"。一次性的、由交互直接引发的副作用（发请求、弹 toast、写 localStorage、跳转）都不应该被建模为"状态变化后被 effect 观察到"，因为它们本质上不是"状态"。

判定标准的补充：effect 中如果有"必须用最新值"的处理器怎么办

有时副作用确实需要在 effect 中执行（例如监听全局事件），但又希望订阅关系不随每次渲染重建。此时不应退回"state + effect"建模，而应使用配套规则 advanced-event-handler-refs.md 中的手法——把处理器存入 ref，保持订阅稳定：

function useWindowEvent(event: string, handler: (e) => void) { const handlerRef = useRef(handler) useEffect(() => { handlerRef.current = handler }, [handler]) useEffect(() => { const listener = (e) => handlerRef.current(e) window.addEventListener(event, listener) return () => window.removeEventListener(event, listener) }, [event]) }

在最新版 React 中，也可以直接用useEffectEvent获得稳定引用：

import { useEffectEvent } from 'react' function useWindowEvent(event: string, handler: (e) => void) { const onEvent = useEffectEvent(handler) useEffect(() => { window.addEventListener(event, onEvent) return () => window.removeEventListener(event, onEvent) }, [event]) }

这两段代码展示了"事件处理器归属"的边界：由用户动作直接触发的逻辑进事件处理器；被 effect 订阅的全局事件，则用 ref / useEffectEvent 保持订阅稳定。它们与本文规则互为补充，共同覆盖了"交互逻辑放哪"的完整问题空间。

仓库实证：Polar 中事件处理器模式的真实用法

规则并非纸上谈兵。在 Polar 的前端代码中，可以找到大量"交互逻辑放在事件处理器"的实例，以邮箱验证码登录页 clients/apps/web/src/app/(main)/auth/email-otp/VerifyPage.tsx/auth/email-otp/VerifyPage.tsx) 为例：

const [loading, setLoading] = useState(false) const submittingRef = useRef(false) const onSubmit: SubmitHandler<{ code: string }> = async ({ code }) => { if (submittingRef.current) return // 防止重复提交 submittingRef.current = true setLoading(true) try { const { error } = await emailOTPVerify.mutateAsync(code) if (error) { if (isValidationError(error.detail)) { setValidationErrors(error.detail, setError) } else if (error.detail) { setError('code', { message: error.detail }) } return } window.location.href = `${CONFIG.FRONTEND_BASE_URL}/auth` } catch { setError('code', { message: 'An unexpected error occurred. Please try again.', }) } finally { setLoading(false) submittingRef.current = false } }

这段代码完全符合本文规则的三个要点：

1. 验证码校验、错误回填、登录成功跳转全部在onSubmit处理器内完成，没有引入任何"验证状态 + effect 监听"的中间层；
2. 用useRef维护submittingRef标志位防重入（且不触发重渲染），在 effect 或依赖变化下也不会重放请求；
3. 页面只保留一个与 UI 直接相关的loading状态，其更新也在处理器内成对出现（setLoading(true)/finally中复位）。

从源码结构看，仓库中同一模式的表单组件（如 VerifyPage.tsx/auth/email-otp/VerifyPage.tsx)、RequestPage.tsx/[organization]/portal/request/RequestPage.tsx) 等）普遍遵循"提交逻辑在 submit handler、UI 状态用 state、防重入用 ref"的分工，这正是本规则落地后的代码形态。

相关规则联动：一条完整的"去 effect 化"检查清单

本文规则很少单独出现，实践中常与 Re-render Optimization 类目下的其他规则组合使用。给出一份组合自查清单：

1. [本规则] 动作副作用：由用户动作触发 → 移入事件处理器；
2. rerender-dependencies.md 依赖收窄：必须留在 effect 中的副作用 → 用原始值/布尔派生值代替对象依赖，避免无关变化触发（如[user.id]代替[user]）；
3. rerender-derived-state-no-effect.md 派生状态：能在渲染期算出的值（如fullName = firstName + ' ' + lastName）→ 渲染期直接计算，绝不在 effect 里setState；
4. advanced-event-handler-refs.md 稳定订阅：effect 中需要最新回调 → 用 ref 或useEffectEvent包装。

按这条链路检查，大多数"effect 滥用"都能被收敛到三种正确形态之一：事件处理器、渲染期派生、真正的外部系统同步。

小结

• 触发规则：由 submit / click / drag 等明确用户动作触发的副作用，直接放进事件处理器；不要建模成"状态 + effect"。
• 核心收益：避免 effect 在无关依赖变化时重复执行，从机制上杜绝重复请求、重复 toast 等重复副作用（影响等级 MEDIUM）。
• 配套手段：需要保留在 effect 里的逻辑，配合收窄依赖（原始值依赖）、渲染期派生状态、ref / useEffectEvent 稳定订阅使用。
• 仓库依据：规则原文见 rerender-move-effect-to-event.md，编译版见 AGENTS.md 的 5.8 节；真实落地示例见 VerifyPage.tsx/auth/email-otp/VerifyPage.tsx)。

把交互逻辑放回事件处理器，是 React 组件从"响应式正确"走向"性能与行为都正确"的第一步，也是 SKILL.md 中 Re-render Optimization 类别里性价比最高、最适合自动化评审直接套用的规则之一。

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar