使用 Biome GritQL 自定义规则：阻断 RHF 性能隐患的 3 个关键策略

React Hook Form (RHF) 的性能优势建立在精细的订阅模型之上，但这份灵活也带来了副作用：新手极易因为解构不当，把精准更新变成全量重渲染。

最近我将项目的基础设施从 ESLint 迁移到了 Biome，构建速度虽然上去了，但新的痛点也随之而来：Biome 目前尚不支持 ESLint 的插件生态。为了守住性能底线，我深入研究了 Biome 的 GritQL 引擎。通过编写自定义规则，成功将 RHF 的三个经典反模式直接“焊死”在了 Linter 里。

下面分享具体的规则实现和背后的性能考量。

核心规则：react-hook-form-rules.grit

在项目根目录创建 react-hook-form-rules.grit。GritQL 的语法虽然有些生僻，但其匹配 AST（抽象语法树）的能力却非常精准。

any {
  // 规则 1：阻断 formState 的顶层解构
  // 原理：直接访问 methods.formState 会触发全量订阅
  `$m1.formState` where {
    register_diagnostic(
      span=$m1, 
      message="性能警告：直接访问 formState 会导致全量重渲染。请使用 useFormState 钩子进行按需订阅。"
    )
  },

  // 规则 2：强制使用 useWatch 替代 .watch()
  // 原理：.watch() 会触发组件级重渲染，而 useWatch 仅触发 hook 级更新
  `$m2.watch($a1)` where {
    register_diagnostic(span=$m2, message="性能优化：建议使用 useWatch() 替代 .watch() 以减少不必要的组件渲染。")
  },
  `watch($a2)` where {
    register_diagnostic(span=$a2, message="性能优化：建议使用 useWatch() 替代 watch()。")
  },

  // 规则 3：禁止 methods 进入依赖数组
  // 原理：methods 引用不稳定，放入 useEffect 依赖会导致死循环或冗余执行
  `methods` as $m3 where {
    $m3 <: within `[$d1]` as $a3 ,
    $a3 <: within any {
      `useEffect($_, $a3)`,
      `useMemo($_, $a3)`,
      `useCallback($_, $a3)`
    } ,
    register_diagnostic(
      span=$m3, 
      message="潜在 Bug：methods 引用不稳定，不应作为依赖项。请仅解构并依赖具体的 stable method（如 reset, setValue）。"
    )
  }
}

为什么要拦截这些模式？

这三条规则，恰好对应了 RHF 开发中最容易导致性能崩塌的三种典型场景。

1. 破坏 Proxy 订阅机制

Bad Pattern:

const { formState } = useForm(); // ❌ 此时你订阅了所有表单状态的变化
// 或者
const methods = useForm();
console.log(methods.formState.errors); // ❌ 同上

底层逻辑： RHF 使用 Proxy 来追踪 formState 的访问路径。一旦你在顶层解构或直接访问 formState，RHF 就会认为当前组件依赖于所有状态的变化。结果就是：用户在 A 输入框打字，毫不相关的 B 区域也会跟着重渲染。

Fix: 使用 useFormState 钩子进行按需、隔离的订阅。

2. 滥用 API 导致渲染范围污染

Bad Pattern:

const { watch } = useForm();
const firstName = watch("firstName"); // ❌ 这里的 watch 会触发当前组件重渲染

底层逻辑： watch 方法的设计初衷是监听字段变化，但它不仅返回数据，还会通知宿主组件更新。在一个复杂表单中，你可能只是想在一个子组件里显示一个名字，结果却导致父组件乃至整棵组件树都重新渲染。

Fix: useWatch 是专门为这种场景设计的。它利用 React Context 机制，将更新触发范围控制在 Hook 内部，实现了最小单元的渲染。

3. 误判引用稳定性，引发循环陷阱

Bad Pattern:

const methods = useForm();
useEffect(() => {
  methods.reset();
}, [methods]); // ❌ methods 对象本身是非稳定的

底层逻辑： useForm 返回的 methods 对象在每次渲染时并不保证引用一致。把它放进 useEffect 的依赖数组，极大概率会导致 Effect 在每次渲染后都重复执行，形成一个隐性的性能黑洞，甚至引发无限循环。

Fix: RHF 保证了 reset, setValue 等具体方法的引用稳定性。因此，只依赖你真正用到的、稳定的函数本身。

落地配置

将自定义规则集成到 biome.json 中非常简单，不需要任何复杂的 AST 解析器配置：

{
  "plugins": ["./react-hook-form-rules.grit"]
}

工程化思考

工具存在的意义，并非只是为了在 Code Review 时指出“你这里写错了”，而是为了让“错误”在开发者输入的瞬间就无所遁形。

通过 Biome 将这些最佳实践固化下来之后，团队的新成员不再需要去死记硬背 RHF 文档的细节，也不必在 Code Review 时反复解释“为什么这里不能用 .watch()”。Linter 的报错信息本身就是最好的、即时反馈的 技术文档。

如果你也在进行类似的工具链迁移，不妨尝试用 GritQL 把团队内部形成的开发默契，转化为硬性的、可执行的代码规则。这或许才是工程化实践的价值所在。欢迎在 云栈社区 分享你的实践经验。