MobX 自定义可观察对象(Custom Observables)实战:用 Atom 构建你自己的响应式数据源
MobX 自定义可观察对象(Custom Observables)实战:用 Atom 构建你自己的响应式数据源
导读:MobX 内置的 observable、computed、Map、Set 等类型并非封闭的黑盒,而是全部建立在名为 Atom(原子) 的底层原语之上。本篇文章以 docs/custom-observables.md 为核心脉络,讲解如何通过 createAtom 将任意数据源(如时钟、流、外部设备、WebSocket 订阅等)接入 MobX 的响应式系统,使其能够被 autorun、reaction 等派生计算自动追踪,并实现"被观察时才工作、无人观察时自动休眠"的惰性资源管理。读完本文你将掌握 Atom 的完整 API(reportObserved / reportChanged / 生命周期回调)及其底层实现原理,并能独立封装属于你自己的自定义可观察数据结构。
为什么需要自定义可观察对象
MobX 的标准可观察类型(数组、对象、Map、Set、原始值)覆盖了绝大多数应用状态管理的需求,但在某些场景下,你可能希望把并非普通数据容器的东西接入响应式系统,例如:
- 一个持续变化的时钟或计时器;
- 来自 WebSocket、SSE 或外部事件流的实时数据;
- 传感器读数、硬件设备状态;
- 任何"只有在被使用时才应该产生成本"的数据源。
MobX 为此提供了 Atom——它是 MobX 内部所有可观察数据类型(ObservableValue、ObservableArray、ObservableMap、ObservableSet 等)共同依赖的底层基类。通过 Atom,你可以向 MobX 发出两类信号:"这个数据源被读取了"(observed)与 "这个数据源变化了"(changed),同时 MobX 也会反过来通知你:它何时开始被使用、何时不再被使用。
Tip(来自官方文档):在很多情况下,你并不需要亲手创建 Atom——只需创建一个普通可观察对象,再用
onBecomeObserved工具函数在 MobX 开始追踪它时收到通知即可。这一点在本文末尾会专门展开对比。
Atom 的核心 API:createAtom
MobX 通过 createAtom 工厂函数创建 Atom,其完整签名在 docs/api.md 的 "Extending MobX" 一节中有正式说明:
createAtom(name, onBecomeObserved?, onBecomeUnobserved?)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string |
是 | Atom 的名称,主要用于调试(devtools、spy、错误信息中会展示) |
onBecomeObserved |
() => void |
否 | 当 Atom 从"未被观察"切换到"被观察"时触发的回调 |
onBecomeUnobserved |
() => void |
否 | 当 Atom 从"被观察"切换到"未被观察"时触发的回调 |
返回的 Atom 对象暴露两个核心 _report 方法(同样是 docs/api.md#createatom 中的官方语义):
reportObserved():向 MobX 声明"该 Atom 已被读取"。如果当前正处于某个派生(derivation,如autorun)的运行上下文中,该方法会把这个 Atom 注册为该派生的依赖,并返回true;若在反应之外被调用则返回false,表示"刚才这次读取没有产生任何依赖关系"。reportChanged():向 MobX 声明"该 Atom 的值已经变化",所有依赖它的派生(autorun、reaction、computed等)都会收到失效通知并被重新执行。
在 packages/mobx/src/mobx.ts 中,createAtom 与 onBecomeObserved、onBecomeUnobserved 等一起作为 MobX 的顶层 API 对外导出,也就是说你可以直接 import { createAtom } from "mobx" 使用。
实战:构建一个"被观察才跳动"的响应式时钟
下面这个示例来自官方文档 docs/custom-observables.md,完整地演示了 Atom 的全部 API 用法。它创建了一个可观察的 Clock,返回当前的日期时间,并且只有在被某人观察时才真正每秒滴答一次:
import { createAtom, autorun } from "mobx"
class Clock {
atom
intervalHandler = null
currentDateTime
constructor() {
// 创建一个 Atom,与 MobX 核心算法进行交互。
this.atom = createAtom(
// 第 1 个参数:
// - Atom 的名称,用于调试目的。
"Clock",
// 第 2 个(可选)参数:
// - 当该 Atom 从"未被观察"转变为"被观察"时的回调。
() => this.startTicking(),
// 第 3 个(可选)参数:
// - 当该 Atom 从"被观察"转变为"未被观察"时的回调。
() => this.stopTicking()
// 同一个 Atom 会在这两种状态之间多次切换。
)
}
getTime() {
// 让 MobX 知道这个可观察数据源被使用了。
//
// reportObserved 会在该 Atom 当前正被某个 reaction 观察时返回 true。
// 如有需要,它还会触发 onBecomeObserved 事件处理器(即 startTicking)。
if (this.atom.reportObserved()) {
return this.currentDateTime
} else {
// getTime 被调用了,但并不是在某个 reaction 运行期间,
// 因此没有人依赖这个值,startTicking(onBecomeObserved 处理器)不会被触发。
//
// 根据 Atom 的性质,在这种情况下它可能有不同的行为,
// 例如抛出错误、返回默认值等等。
return new Date()
}
}
tick() {
this.currentDateTime = new Date()
this.atom.reportChanged() // 让 MobX 知道这个数据源已经改变。
}
startTicking() {
this.tick() // 先立即触发一次 tick。
this.intervalHandler = setInterval(() => this.tick(), 1000)
}
stopTicking() {
clearInterval(this.intervalHandler)
this.intervalHandler = null
}
}
const clock = new Clock()
const disposer = autorun(() => console.log(clock.getTime()))
// 每秒打印一次时间。
// 停止打印。如果没有其他人使用同一个 clock,它也会停止滴答。
disposer()
逐步拆解:这个时钟是如何"活"起来的
- 构造时创建 Atom:
createAtom("Clock", onBecomeObserved, onBecomeUnobserved)注册了两个生命周期回调。此时时钟还处于休眠状态,intervalHandler为null,不会启动任何计时器。 autorun首次运行:autorun(() => console.log(clock.getTime()))执行时,函数体内读取clock.getTime()。getTime调用this.atom.reportObserved(),此时正处于派生上下文中,MobX 将 Atom 登记为该autorun的依赖,并触发onBecomeObserved回调 →startTicking()被调用:- 立即执行一次
tick(),把currentDateTime初始化为当前时间; - 启动
setInterval,此后每秒调用一次tick()。
- 立即执行一次
- 每次
tick():更新currentDateTime并调用this.atom.reportChanged(),MobX 据此使依赖它的autorun失效并重新执行,于是控制台每秒打印一次时间。 - 调用
disposer():autorun被销毁后不再依赖该 Atom,Atom 转入"未被观察"状态,触发onBecomeUnobserved回调 →stopTicking()清除setInterval,时钟停止滴答,不再占用任何系统资源。
值得注意的是 getTime() 中 reportObserved() 的返回值分支:如果 getTime 在反应之外被直接调用(例如普通的事件处理器里),reportObserved() 返回 false,说明本次读取不会建立任何依赖,Atom 也就不会开始滴答,此时直接返回 new Date() 作为即时值。正如代码注释所说,这个分支的行为完全取决于你的 Atom 语义——可以抛错、返回默认值,或做其他处理。
源码视角:Atom 是如何与 MobX 核心算法交互的
理解了用法之后,再看底层实现会让"为什么这样写"变得非常清晰。Atom 的完整定义位于 packages/mobx/src/core/atom.ts:
reportObserved() 的调用链
public reportObserved(): boolean {
return reportObserved(this)
}
它委托给 packages/mobx/src/core/observable.ts 中的核心函数 reportObserved,该函数做了三件关键的事:
- 调用
checkIfStateReadsAreAllowed(observable)——在严格模式(enforceActions)下校验当前读取是否被允许,这正是 Atom 读取也会受 MobX 配置约束的原因; - 读取
globalState.trackingDerivation判断当前是否处于某个派生(reaction/computed)的运行上下文中:如果存在,就把该 Atom 记入派生的依赖列表derivation.newObserving_(其中runId_与lastAccessedBy_的比较是一个去重优化,保证同一轮运行中同一个 Atom 只登记一次依赖); - 如果该 Atom 此前未被观察(
!observable.isBeingObserved),则置位"正在被观察"标志并调用observable.onBO(),从而触发你传入的onBecomeObserved回调。
从源码可以看到,createAtom 的 onBecomeObserved / onBecomeUnobserved 回调实际上是被存进了 Atom 的 onBOL / onBUOL 两个监听器集合中(见 packages/mobx/src/core/atom.ts,默认的 noop 处理器不会初始化集合,以节省内存)。
reportChanged() 与"未观察"的延迟处理
public reportChanged() {
startBatch()
propagateChanged(this)
endBatch()
}
reportChanged 通过 startBatch / endBatch 包裹 propagateChanged,把所有依赖该 Atom 的派生标记为需要重新执行。而"变成未被观察"这一事件并不是在最后一个观察者离开的瞬间立即触发的,而是在批处理结束时统一处理——见 packages/mobx/src/core/observable.ts 中 endBatch 对 pendingUnobservations 队列的遍历:只有当 observers_ 为空且此前处于被观察状态时,才清除 isBeingObserved 标志并调用 observable.onBUO()(即触发你的 onBecomeUnobserved 回调)。这也解释了文档中"同一个 Atom 会在被观察/未被观察两种状态之间多次切换"的注释——每次 autorun 的创建与销毁都可能引发一次状态跃迁。
Atom 在 MobX 内部的真实应用
Atom 并不是一个仅供用户使用的"玩具 API"——MobX 自己的数据结构就在使用它。例如 packages/mobx/src/types/observablemap.ts 中,ObservableMap 内部为 keys() 的枚举行为单独创建了一个 keysAtom_:
this.keysAtom_ = createAtom(__DEV__ ? `${this.name_}.keys()` : "ObservableMap.keys()")
由此可以推断:你在文档中看到的 createAtom 用法,与 MobX 内部实现 ObservableMap 枚举通知时使用的是完全相同的机制。
更省事的替代方案:onBecomeObserved / onBecomeUnobserved
官方文档在 custom-observables.md 的开头就给出了一个重要的 Tip:如果只是想给已有的可观察对象附加惰性行为,通常不需要自己创建 Atom。这正是 docs/lazy-observables.md 的主题,其用法为:
onBecomeObserved(observable, property?, listener: () => void): (() => void)onBecomeUnobserved(observable, property?, listener: () => void): (() => void)
它们会挂接到 MobX 的可观察性系统上,在某个可观察对象开始与停止被观察时通知你,并返回一个用于解除监听的 disposer 函数。文档中的 City 示例展示了如何用它实现"仅在温度值被使用时才轮询后端数据"的懒加载模式:
export class City {
location
temperature
interval
constructor(location) {
makeAutoObservable(this, {
resume: false,
suspend: false
})
this.location = location
// 仅在 temperature 真正被使用时才开始拉取数据!
onBecomeObserved(this, "temperature", this.resume)
onBecomeUnobserved(this, "temperature", this.suspend)
}
resume = () => {
log(`Resuming ${this.location}`)
this.interval = setInterval(() => this.fetchTemperature(), 5000)
}
suspend = () => {
log(`Suspending ${this.location}`)
this.temperature = undefined
clearInterval(this.interval)
}
fetchTemperature = flow(function* () {
// Data fetching logic...
})
}
其实现原理在 packages/mobx/src/api/become-observed.ts 中:interceptHook 通过 getAtom(thing, property) 解析出目标属性背后真正的 Atom,再把监听器加入该 Atom 的 onBOL / onBUOL 集合(与 createAtom 的回调共用同一套触发机制),返回的 disposer 负责从集合中移除监听器、并在集合清空时删除键以释放内存。
两者如何选择:createAtom 适合"从零打造全新数据源"(如本文件的 Clock);onBecomeObserved / onBecomeUnobserved 适合"给已有可观察对象注入生命周期副作用"(如 City.temperature)。从源码看,二者的底层机制完全一致——都是往 Atom 的 onBOL / onBUOL 里挂监听器。
设计自定义 Atom 的实用建议
结合文档示例与源码实现,封装自己的 Atom 时有几点值得注意:
- 给 Atom 起有意义的名称:
createAtom的第一个参数在调试器、spy事件和错误信息中都会出现,命名为"Clock"、"ObservableMap.keys()"这样的可读名称能显著降低排障成本。 - 把"读取"与"变化"分开处理:读取方(
reportObserved)决定依赖关系的建立,变化方(reportChanged)决定派生的失效。二者职责不要混淆。 - 正确处理非反应上下文中的读取:像
Clock.getTime()那样,当reportObserved()返回false时要有明确的降级行为(返回即时值 / 默认值 / 抛错),否则在事件处理器中读取你的自定义数据源时可能得到意外结果。 - 善用生命周期回调做资源管理:
onBecomeObserved中启动定时器、订阅、连接等昂贵操作,onBecomeUnobserved中对称地释放它们——这正是本文件时钟示例的核心价值:无人观察时零成本。 - 理解状态切换的多次性:Atom 的"被观察/未被观察"状态可以反复切换,回调也可能被多次触发,因此
startTicking/stopTicking这类处理器应当写得具备幂等性(例如重复clearInterval是安全的)。
延伸阅读
- API 参考:createAtom:Atom 工厂函数的正式签名与
reportObserved/reportChanged语义说明。 - 创建惰性可观察对象(Lazy observables):使用
onBecomeObserved/onBecomeUnobserved为已有可观察对象附加生命周期行为的完整指南。 - 深入了解响应式系统:理解派生(derivation)、依赖追踪与批处理机制的背景知识。
- 源码入口:Atom 核心实现、reportObserved 与批处理逻辑、onBecomeObserved 工具实现。