Formily Reactive 之 action:掌握批量更新与依赖追踪隔离的响应式编程利器
Formily Reactive 之 action:掌握批量更新与依赖追踪隔离的响应式编程利器
导读
action 是 Formily 响应式核心 @formily/reactive 中用于定义"批量动作"的基础 API。它解决的问题非常具体:当你在一个函数内连续修改多个响应式状态时,如何让依赖这些状态的 autorun / reaction 只触发一次,而不是被中间态反复触发;同时,它与 batch 的唯一差别在于——action 内部无法收集依赖。本文基于 packages/reactive/docs/api/action.md 展开,结合 action 源码实现、reaction 底层调度 与 action 单元测试,系统讲解 action 的三种调用形态(原地、局部、高阶绑定)、批量与依赖追踪隔离的底层原理,以及它在数据模型定义(define)中的注解用法。读完本文,你将能够在 Formily 项目中用 action 精确控制状态更新的通知粒度,写出高性能、可预期的响应式业务代码。
一、action 是什么:定位与核心差异
1.1 官方定义
依据 action.md 的描述:
Define a batch action. The only difference with batch is that dependencies cannot be collected inside an action. (定义一个批量动作。与
batch的唯一差别就是 action 内部是无法收集依赖的。)
这包含两层语义:
- 它是批量动作(batch action):包裹在
action内的多次状态修改,会在动作结束后统一触发一次依赖通知; - 它隔离依赖收集(no dependency collection):在 action 执行期间,处于该动作内的响应式属性读取不会被任何外部的追踪者(如
autorun、reaction、computed)收集为依赖。
1.2 与 batch 的区别
在 batch.ts 中可以看到,batch 只做批量通知,不关闭依赖收集:
export const batch: IBatch = createBoundaryAnnotation(batchStart, batchEnd)
batch.scope = createBoundaryAnnotation(batchScopeStart, batchScopeEnd)
batch.endpoint = (callback?: () => void) => {
if (!isFn(callback)) return
if (BatchCount.value === 0) {
callback()
} else {
BatchEndpoints.add(callback)
}
}
而 action.ts 在批量调度的基础上额外叠加了 untrackStart / untrackEnd:
export const action: IAction = createBoundaryAnnotation(
() => {
batchStart()
untrackStart()
},
() => {
untrackEnd()
batchEnd()
}
)
action.scope = createBoundaryAnnotation(
() => {
batchScopeStart()
untrackStart()
},
() => {
untrackEnd()
batchScopeEnd()
}
)
由此可见,action = batch(批量通知) + untracked(禁止依赖收集),这就是文档中"与 batch 的唯一差别"的源码级证据。
二、API 签名与三种调用形态
依据 action.md 的签名,结合 types.ts 中 IAction 的完整定义:
interface IAction extends IBoundable {
<T>(callback?: () => T): T //原地action
scope?: (<T>(callback?: () => T) => T) & IBoundable //原地局部action
}
interface IBoundable {
bound?: <T extends (...args: any[]) => any>(callback: T, context?: any) => T //高阶绑定
}
完整的使用形态如下表:
| 形态 | 签名 | 说明 |
|---|---|---|
| 原地 action | action<T>(callback?: () => T): T |
立即执行一个批量动作,可选传入回调并返回其返回值 |
| 原地局部 action | action.scope<T>(callback?: () => T): T |
立即执行一个局部批量动作,只影响自身作用域内的通知时机 |
| 高阶绑定 | action.bound<T extends (...args: any[]) => any>(callback: T, context?: any): T |
将回调包装为一个批量动作函数返回,可指定 this 上下文 |
| 局部高阶绑定 | action.scope.bound<T>(callback: T, context?: any): T |
局部作用域版本的高阶绑定 |
值得注意的是:
callback是可选参数,action()空调用也是合法的(测试用例 action.spec.ts 中就有action(() => {})与action()的用例);- 传入的 callback 可以为空,此时返回值是
undefined; scope同样拥有bound高阶绑定能力(见IBoundable接口),因此存在action.scope.bound这一组合形态。
三、官方示例:action.bound 的基本用法
action.md 给出了如下示例——先创建可观察对象,再用 action.bound 包装一个一次性修改两个字段的方法:
import { observable, action } from '@formily/reactive'
const obs = observable({})
const method = action.bound(() => {
obs.aa = 123
obs.bb = 321
})
method()
这里的关键点:
action.bound返回的是一个新的函数,调用它时才执行批量动作;- 当
obs.aa与obs.bb同时被修改时,任何订阅了这两个字段的autorun都只会收到一次通知; - 由于 action 内部无法收集依赖,
method()内部对obs.aa、obs.bb的读取不会建立新的依赖关系——这保证了批处理逻辑本身不会污染外部的追踪上下文。
四、批量通知机制:底层如何"只触发一次"
要真正理解 action,需要先看清 reaction.ts 中批量调度的实现:
export const batchStart = () => {
BatchCount.value++
}
export const batchEnd = () => {
BatchCount.value--
if (BatchCount.value === 0) {
const prevUntrackCount = UntrackCount.value
UntrackCount.value = 0
executePendingReactions()
executeBatchEndpoints()
UntrackCount.value = prevUntrackCount
}
}
其工作流程是:
batchStart()使全局BatchCount计数加一,进入批量模式;- 批量模式期间发生的响应式变更不会立刻派发,而是进入"待执行反应"队列(pending reactions);
batchEnd()使计数减一;只有当计数归零(即最外层动作结束)时,才会一次性executePendingReactions()执行所有排队中的反应。
action 与 batch 共用这套调度,区别仅在于 action 额外调用了 untrackStart / untrackEnd(见 action.ts),通过 UntrackCount 计数在动作执行期间关闭依赖收集。嵌套的 action/batch 通过计数器的增减自然形成"栈",因此支持任意层级的嵌套组合。
下面的测试用例直观展示了 action 的效果(action.spec.ts):
test('action', () => {
const obs = observable({ aa: { bb: 123 } })
const handler = jest.fn()
autorun(() => {
handler(obs.aa.bb)
})
obs.aa.bb = 111
obs.aa.bb = 222
expect(handler).toBeCalledTimes(3) // 初始 1 次 + 2 次修改各触发 1 次
action(() => {
obs.aa.bb = 333
obs.aa.bb = 444
})
expect(handler).toBeCalledTimes(4) // 批量内两次修改只触发 1 次
})
对照组 no action 用例(action.spec.ts)中,同样的两次连续修改会让 handler 被调用 5 次。两次对比即可量化 action 带来的通知合并效果。
五、依赖追踪隔离:action 内部读不到依赖
5.1 为什么需要隔离
如果 action 内部可以收集依赖,那么当批量逻辑中包含"先读后写"的代码时(例如 if (obs.cc > 0) { ... obs.cc = obs.cc + 20 }),外部追踪者可能会误把 action 内读取的属性加入依赖表,导致后续无关字段变化时也触发重跑,造成多余计算甚至死循环。untrackStart / untrackEnd(reaction.ts)通过在追踪时提升 UntrackCount 来屏蔽依赖记录,从源头避免这类问题。
5.2 测试证据
action.spec.ts 的 action track 用例验证了这一点:
test('action track', () => {
const obs = observable({ aa: { bb: 123 }, cc: 1 })
const handler = jest.fn()
autorun(() => {
action(() => {
if (obs.cc > 0) {
handler(obs.aa.bb)
obs.cc = obs.cc + 20
}
})
})
expect(handler).toBeCalledTimes(1)
expect(obs.cc).toEqual(21)
obs.aa.bb = 321
expect(handler).toBeCalledTimes(1) // obs.aa.bb 变化后 autorun 未重跑
expect(obs.cc).toEqual(21)
})
obs.aa.bb 在 action 内被读取,但该读取未被 autorun 收集为依赖,因此后续修改 obs.aa.bb 不会再触发 handler。这正是"action 内部无法收集依赖"的实战含义。
六、action.scope:局部批量动作
6.1 语义与底层实现
action.scope 是局部作用域的批量动作:它通过 batchScopeStart / batchScopeEnd(reaction.ts)开启 BatchScope 标记,将"通知时机"的边界限定在 scope 自身作用域内——scope 结束时立即执行其内部的待处理反应,而不是等待最外层动作统一结算。
6.2 典型场景与测试
在需要"外层批量、内层分组提交"的场景中非常有用。例如 action.spec.ts 的用例:外层 action 内连续执行两个 action.scope,每个 scope 内部的修改各自成批提交,使得 handler 按分组粒度触发:
test('action.scope xxx', () => {
const obs = observable<any>({})
const handler = jest.fn()
autorun(() => {
handler(obs.aa, obs.bb, obs.cc, obs.dd)
})
action(() => {
action.scope(() => {
obs.aa = 123
})
action.scope(() => {
obs.cc = 'ccccc'
})
obs.bb = 321
obs.dd = 'ddddd'
})
expect(handler).toBeCalledTimes(4)
})
6.3 与 action 的行为差异总结
| 维度 | action |
action.scope |
|---|---|---|
| 批量边界 | 最外层结束时统一通知 | 作用域结束时立即通知 |
| 底层调度 | batchStart/batchEnd |
batchScopeStart/batchScopeEnd |
| 依赖收集 | 均关闭(untrackStart/untrackEnd) |
均关闭(untrackStart/untrackEnd) |
| 典型用途 | 表单提交等整体批量操作 | 分步骤、分区块的批量更新 |
七、高阶绑定:bound 与 context
action.bound 与 action.scope.bound 返回一个包装后的函数,支持传入 context 指定回调执行时的 this。其底层由 internals.ts 的 createBindFunction 实现:
export const createBindFunction = <Boundary extends BoundaryFunction>(
boundary: Boundary
) => {
function bind<F extends (...args: any[]) => any>(
callback?: F,
context?: any
): F {
return ((...args: any[]) =>
boundary(() => callback.apply(context, args))) as any
}
return bind
}
要点:
- 返回的包装函数被调用时,会用
callback.apply(context, args)把this绑定为传入的context,并将入参透传给原回调; - 由于
boundary内部使用try / finally(见createBoundaryFunction,internals.ts),即使回调抛出异常,batchEnd / untrackEnd也会被保证执行,不会出现批量模式未退出的泄漏状态; action.bound(() => {})不传 context 时,this在非严格模式下指向全局对象,严格模式下为undefined,日常使用建议显式传入 context。
实际项目中更常见的用法是把 action.bound 与 define 注解结合(见下文第八节),让类方法天然成为批量动作且绑定到实例。
八、注解用法:在 define 模型中声明 action 方法
action 本身是"注解"(annotation)体系的一部分——internals.ts 中的 createBoundaryAnnotation 同时生成了可调用函数与 createAnnotation 注解两种形态,因此 action 可以直接作为 define 的模型注解使用。
8.1 define + action 示例
action.spec.ts 演示了模型方法注解:
const obs = define(
{
aa: {
bb: 123,
},
setData() {
this.aa.bb = 333
this.aa.bb = 444
},
},
{
aa: observable,
setData: action,
}
)
调用 obs.setData() 时,内部的两次赋值被合并为一次通知(handler 从 3 次增至 4 次)。注解形式下:
setData: action:方法调用即批量动作;setData: action.bound:批量动作且自动绑定实例this(action.spec.ts),源码中createBoundaryAnnotation会执行target[key] = boundary.bound(target[key], target),这正是注解自动绑定this的实现位置;setData: action.scope/setData: action.scope.bound:局部作用域批量动作,见 action.spec.ts。
8.2 为什么注解默认就是 bound
从 createBoundaryAnnotation(internals.ts)可以看到,注解分支直接使用 boundary.bound(target[key], target) 包装原方法并以 target 为上下文,因此在 define 模型里用 action 注解声明的方法,内部通过 this.xxx 访问模型字段是完全安全的,无需手动 bind(this)。
九、嵌套组合与 formily 生态中的应用
9.1 嵌套 action / batch 的行为
由于批量调度基于全局计数,action 与 batch 可以任意嵌套。测试 action.spec.ts 验证了嵌套场景下的最终派发语义:
action(() => {
obs.aa = 1
action(() => {
obs.aa = 2
})
})
最内层修改 obs.aa = 2 才是 reaction 最终收到的值,嵌套的中间修改 obs.aa = 1 不会触发额外派发,最终 handler 只被调用 2 次(分别收到 2 和 4)。
9.2 action 在 Formily 中的角色
action、batch、untracked、reaction、autorun 等 API 统一从 packages/reactive/src/index.ts 导出(export * from './batch'、export * from './action'、export * from './untracked'),是 Formily 表单内核(如 packages/core 的字段模型)处理高频状态变更的基石。理解 action 的"批量通知 + 依赖隔离"双重语义,是进一步阅读 Formily 核心源码、优化表单性能的前提。
十、实践建议与小结
10.1 使用建议
- 写操作密集的处理器:在事件回调、提交逻辑、异步写回等"一次要改多个字段"的场景,用
action或action.bound包裹,避免中间态触发多余渲染与计算; - 内部含条件分支的批量逻辑:由于 action 内不收集依赖,"先读后写"的代码不会污染外部追踪关系,可放心使用;
- 需要分阶段提交时:外层用
action,内层用action.scope,把通知粒度控制在业务分组的边界上; - 模型方法:优先使用
define+action(或action.bound)注解声明,让方法自动具备批量与绑定能力; - 异常安全:action 的边界函数使用
try/finally保证批量模式一定会退出,即使回调抛错也不会破坏后续的响应式调度状态。
10.2 相关 API 快速对照
| API | 批量通知 | 关闭依赖收集 | 说明 |
|---|---|---|---|
action |
✅ | ✅ | 标准批量动作 |
action.scope |
✅(局部作用域) | ✅ | 作用域级批量 |
batch |
✅ | ❌ | 仅批量通知 |
untracked |
❌ | ✅ | 仅关闭依赖收集 |
10.3 小结
action 用最简 API(一个函数、两个开关)实现了响应式编程中两个最常用的性能优化原语——批量合并通知与依赖追踪隔离。本文从官方文档的签名出发,结合 action 源码、reaction 批量调度、注解基础设施 和完整的 单元测试,还原了它的实现原理与全部使用形态。后续在 Formily 的表单内核、@formily/react / @formily/vue 的响应式桥接层中,你都会看到这套机制的反复运用。