MobX 自定义可观察对象(Custom Observables)实战:用 Atom 构建你自己的响应式数据源

原创2026-09-18 12:55:411,714 阅读
文章标签:状态管理前端

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()

逐步拆解:这个时钟是如何"活"起来的

  1. 构造时创建 Atom:createAtom("Clock", onBecomeObserved, onBecomeUnobserved) 注册了两个生命周期回调。此时时钟还处于休眠状态,intervalHandler 为 null,不会启动任何计时器。
  2. autorun 首次运行:autorun(() => console.log(clock.getTime())) 执行时,函数体内读取 clock.getTime()。getTime 调用 this.atom.reportObserved(),此时正处于派生上下文中,MobX 将 Atom 登记为该 autorun 的依赖,并触发 onBecomeObserved 回调 → startTicking() 被调用:
    • 立即执行一次 tick(),把 currentDateTime 初始化为当前时间;
    • 启动 setInterval,此后每秒调用一次 tick()。
  3. 每次 tick():更新 currentDateTime 并调用 this.atom.reportChanged(),MobX 据此使依赖它的 autorun 失效并重新执行,于是控制台每秒打印一次时间。
  4. 调用 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,该函数做了三件关键的事:

  1. 调用 checkIfStateReadsAreAllowed(observable)——在严格模式(enforceActions)下校验当前读取是否被允许,这正是 Atom 读取也会受 MobX 配置约束的原因;
  2. 读取 globalState.trackingDerivation 判断当前是否处于某个派生(reaction/computed)的运行上下文中:如果存在,就把该 Atom 记入派生的依赖列表 derivation.newObserving_(其中 runId_ 与 lastAccessedBy_ 的比较是一个去重优化,保证同一轮运行中同一个 Atom 只登记一次依赖);
  3. 如果该 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 是安全的)。

延伸阅读

登录后查看全文
mobx