深入理解 @formily/reactive 的 untracked:在响应式追踪中精确隔离依赖收集
深入理解 @formily/reactive 的 untracked:在响应式追踪中精确隔离依赖收集
untracked 是 @formily/reactive 响应式核心暴露的一组 API(与 batch、autorun、reaction 并列),其作用是在一段给定函数执行期间临时关闭依赖收集:函数内部无论读取多少响应式数据,都不会被当前正在运行的响应式上下文(如 autorun、reaction 或组件渲染)注册为依赖。本文以 untracked.zh-CN.md 为骨架,结合源码实现与测试用例,讲清它的签名、用法、底层拦截原理,以及与 batch 的本质区别,帮助你写出更精确、可预测的响应式逻辑。
untracked 是什么:API 定位与签名
在 Formily 的响应式体系(packages/reactive)中,observable 负责把数据变成可追踪对象,autorun/reaction 负责建立"读取即依赖"的自动订阅关系。但实际业务里经常出现这类诉求:我确实要读取某个响应式值,但我不想因为它而变化而触发当前 effect 重跑——例如在 effect 里读一次配置快照、写日志、或把值传给某个不关心变化的第三方库。
untracked 就是为这种场景准备的。官方文档给出的签名如下:
interface untracked<T extends () => any> {
(untracker?: T): ReturnType<T>
}
要点解读:
- 入参
untracker是一个可选函数,函数内部读取的响应式数据不会被收集为依赖; - 返回值类型与入参函数返回值一致(
ReturnType<T>),因此它天然适合包裹有返回值的表达式,而不只是过程语句; - 参数可省略(
untracked()),此时仅起到"切换开关"作用,不做任何计算。
从源码看,untracked 的实现极简,它由 createBoundaryFunction 配合两个反应期钩子构成,见 untracked.ts:
import { createBoundaryFunction } from './internals'
import { untrackStart, untrackEnd } from './reaction'
export const untracked = createBoundaryFunction(untrackStart, untrackEnd)
整个 API 的语义可以概括为一句话:在给定的 untracker 函数内部,永远不会被依赖收集(与 batch 的用法相似,但作用不同,下文详述)。
快速上手:从文档用例出发
文档给出了最典型的使用场景:在 autorun 中读取响应式值,但希望这个读取不影响订阅关系。
import { observable, autorun, untracked } from '@formily/reactive'
const obs = observable({
aa: 11,
})
autorun(() => {
console.log(untracked(() => obs.aa)) //变化时不会触发
})
obs.aa = 22
执行结果分析:
autorun首次执行时,外层函数体读取了untracked(() => obs.aa)的返回值;- 由于读取发生在
untracked内部,obs.aa的依赖绑定被跳过,因此autorun并没有订阅aa; - 当
obs.aa = 22修改数据并触发响应式通知时,该autorun不在aa的依赖集合中,因此 不会重跑,控制台只会打印一次11。
对应的单元测试见 untracked.spec.ts,其中用 jest.fn 精确验证了"调用次数恒为 1"这一行为:
test('basic untracked', () => {
const obs = observable<any>({})
const fn = jest.fn()
autorun(() => {
untracked(() => {
fn(obs.value)
})
})
expect(fn).toBeCalledTimes(1)
obs.value = 123
expect(fn).toBeCalledTimes(1)
})
原理剖析:UntrackCount 与依赖收集的拦截
要理解 untracked 为什么能"屏蔽"依赖收集,需要追踪三个关键环节:状态计数、边界函数、绑定拦截。
第一步:状态计数开关
untrackStart / untrackEnd 的实现位于 reaction.ts:
export const untrackStart = () => {
UntrackCount.value++
}
export const untrackEnd = () => {
UntrackCount.value--
}
它们操作的 UntrackCount 是 environment.ts 中定义的一个模块级计数器:
export const UntrackCount = { value: 0 }
配套的判定函数:
export const isUntracking = () => UntrackCount.value > 0
也就是说,untracked 内部会把 UntrackCount 从 0 变成 1(支持嵌套叠加),从而让整个系统进入"屏蔽收集"模式。
第二步:边界函数保证成对执行
createBoundaryFunction 位于 internals.ts,它的职责是保证 start/end 在任意情况下都成对调用(即使回调抛异常,finally 也会执行 end):
export const createBoundaryFunction = (
start: (...args: any) => void,
end: (...args: any) => void
) => {
function boundary<F extends (...args: any) => any>(fn?: F): ReturnType<F> {
let results: ReturnType<F>
try {
start()
if (isFn(fn)) {
results = fn()
}
} finally {
end()
}
return results
}
boundary.bound = createBindFunction(boundary)
return boundary
}
注意两个细节:
- 只有当传入
fn是函数时才执行它,所以untracked()无参调用是合法的(测试'no params untracked'专门覆盖了这一点); - 返回的
boundary函数还挂载了bound方法(由 createBindFunction 生成),用于在指定context下执行回调,方便把类方法直接包进untracked边界内。
第三步:在绑定入口处拦截
依赖收集的真正入口是 bindTargetKeyWithCurrentReaction(reaction.ts)。每当代理对象上的属性被读取,baseHandlers/collectionHandlers 都会调用它,把"当前栈顶的 reaction"与"目标对象的某个 key"关联起来:
export const bindTargetKeyWithCurrentReaction = (operation: IOperation) => {
let { key, type, target } = operation
if (type === 'iterate') {
key = ITERATION_KEY
}
const reactionLen = ReactionStack.length
if (reactionLen === 0) return
const current = ReactionStack[reactionLen - 1]
if (isUntracking()) return // ← untracked 的拦截点
if (current) {
DependencyCollected.value = true
addReactionsMapToReaction(current, addRawReactionsMap(target, key, current))
}
}
关键就在 if (isUntracking()) return 这一行:即便此时 ReactionStack 栈顶确实存在正在执行的 autorun/reaction(说明读取确实发生在响应式上下文里),只要 UntrackCount > 0,就直接放弃注册。于是 RawReactionsMap 中不会新增"target.key → reaction"的映射,后续数据变更触发 runReactions 时自然也找不到该 reaction,effect 便不会被唤醒。
这也解释了文档中"用法与 batch 相似"的说法:两者都只是包一层边界函数(batch 走 batchStart/batchEnd),形态相似,但干预的环节完全不同(见下节)。
untracked 与 batch 的异同
batch 的边界实现同样基于 createBoundaryFunction,只是传入的是 batchStart/batchEnd(reaction.ts)。二者的对比如下:
| 维度 | batch |
untracked |
|---|---|---|
| 核心计数器 | BatchCount |
UntrackCount |
| 干预环节 | 通知执行阶段:批量收集 PendingReactions,在 batchEnd 时统一执行 |
依赖收集阶段:isUntracking() 为真时直接跳过绑定 |
| 影响面 | 延迟/合并 effect 触发,减少重复执行 | 完全阻断依赖注册,effect 不再订阅这些数据 |
| 典型场景 | 一次性修改多个字段,避免中间态触发多次 effect | 读取但不订阅,读取结果变化不应影响当前 effect |
| 组合使用 | 可嵌套 | 可嵌套(计数器叠加) |
简单记忆:batch 管"什么时候触发",untracked 管"要不要订阅"。
值得留意的是,二者在实现上是正交的:runReactions 在执行通知时会把 UntrackCount 临时归零再恢复(reaction.ts),确保批量派发 effect 时不会误伤其内部正常的依赖收集;batchEnd 清空待执行队列时也有类似处理。这说明框架刻意保持了两种边界的隔离与可组合性。
边界场景与使用要点
在 computed 上使用 untracked
observable.computed 的 getter 同样受依赖收集约束。当你想"计算出一个值,但不希望它内部读取的依赖影响外层订阅"时,可以像测试 annotations.spec.ts 那样包裹:
test('computed no track get', () => {
const obs = observable({ aa: 123 })
const compu = observable.computed({ get: () => obs.aa })
untracked(() => {
expect(compu.value).toBe(123)
})
})
在这个用例中,untracked 内部读取 compu.value 只是取回计算结果,而不会因为这次读取而让外层上下文订阅 compu 及其依赖的 obs.aa。
嵌套与无参调用
由于 UntrackCount 是累加计数器,untracked 支持嵌套;由于 createBoundaryFunction 仅在传入函数时才执行,untracked() 可作为纯开关使用(测试 'no params untracked' 保证其可空调用且不抛错)。
与 autorun / reaction 的配合
autorun 的执行体位于 ReactionStack 中(autorun.ts),reaction 的 tracker 同样入栈。因此:
- 在
autorun内部用untracked包裹的读取 → 不订阅; - 在
reaction的 tracker 内部同理; - 在
untracked内部调用autorun/reaction,其内部的依赖收集不受影响(各自拥有独立边界),这与batch的行为一致。
使用注意
- 它屏蔽的是"本次读取与当前 reaction 的绑定",并不影响数据本身的可观察性——其他 effect 照常订阅;
- 不要在
untracked回调内做"既想读取又想订阅"的操作,语义上二者互斥; - 若回调内部抛错,
finally会保证untrackEnd执行,计数器不会泄漏,但错误会照常向外传播。
结语
untracked 是 @formily/reactive 中体积最小、语义却最清晰的 API 之一:一行源码定义(untracked.ts),配合反应期计数与绑定入口的拦截(reaction.ts、reaction.ts),即可精确控制依赖收集的开关。理解它之后,你再面对"读配置不订阅""取快照不重跑"这类需求时,就有了标准答案;配合 batch 使用,则能同时控制"订阅关系"与"触发时机"两个维度,写出更符合预期、更容易推理的响应式代码。