企业官网建设流程全解析

• 前端
• UI组件

导读

本文聚焦 Formily 响应式内核 @formily/reactive 提供的三个类型检查 API——isObservable、isAnnotation与isSupportObservable。它们在响应式体系中扮演"门卫"角色：判断一个值是否已经是可观察对象、是否携带注解标记、以及是否具备被包装为可观察对象的能力。读完本文，你将理解这三个 API 的精确语义、底层实现原理、典型使用场景，以及如何配合markRaw/markObservable控制"哪些对象可以被响应式化"。

文档与源码对照

本文对应的官方 API 文档位于 typeChecker.md，文档给出了三个 API 的签名与功能描述。其真实实现位于 externals.ts，并通过 index.ts 统一导出。在深入源码之前，先回顾文档给出的 API 轮廓：

isObservable：判断对象是否已是响应式代理

语义与签名

interface isObservable { (target: any): boolean }

isObservable(target)接收任意值，返回boolean，用于回答"这个对象是否已经被 Formily 的响应式系统接管"。

底层实现

在 externals.ts 中，其实现为：

export const isObservable = (target: any) => { return ProxyRaw.has(target) || !!target?.[ObModelSymbol] }

判断条件包含两个分支：

1. ProxyRaw.has(target)：ProxyRaw是定义在 environment.ts 中的WeakMap，保存了"代理对象 → 原始对象"的映射。凡是通过 Proxy 方式创建的响应式对象，都会登记在该表中，因此查表即可判定。
2. target?.[ObModelSymbol]：ObModelSymbol（Symbol('ObModelSymbol')，见 environment.ts）是挂在对象上的响应式标记。像ref、computed这类"盒子"（box）对象在创建时会显式设置proxy[ObModelSymbol] = store（见 ref.ts、computed.ts），因此无需经过 WeakMap 也能被识别。

也就是说，无论对象是通过observable()函数创建的 Proxy 代理，还是通过注解创建的带符号标记的盒子，isObservable都能准确识别。

使用示例

import { observable, isObservable } from '@formily/reactive' const obs = observable({ name: 'Formily' }) console.log(isObservable(obs)) // true const plain = { name: 'plain' } console.log(isObservable(plain)) // false const boxed = observable.box(1) console.log(isObservable(boxed)) // true（ref/box 类型同样可被识别）

这一判断在 model.ts 中被用于幂等保护：define()在入口处先执行if (isObservable(target)) return target，避免对已响应式化的对象重复包装。

isAnnotation：识别响应式注解

语义与签名

interface isAnnotation { (target: any): boolean }

isAnnotation(target)判断传入值是否为 Formily 的注解（Annotation）函数。注解是响应式系统用来声明"如何观察某个属性"的元数据，例如observable.ref、observable.deep、observable.shallow、observable.computed、observable.box。

底层实现

在 externals.ts 中：

export const isAnnotation = (target: any): target is Annotation => { return target && !!target[MakeObModelSymbol] }

其原理是检查对象上是否存在MakeObModelSymbol（Symbol('MakeObModelSymbol')，见 environment.ts）标记。查看 observable.ts 可以发现，observable对象在挂载注解时统一设置了该标记：

export function observable<T extends object>(target: T): T { return createObservable(null, null, target) } observable.box = annotations.box observable.ref = annotations.ref observable.deep = annotations.observable observable.shallow = annotations.shallow observable.computed = annotations.computed observable[MakeObModelSymbol] = annotations.observable

注意isAnnotation返回的是 TypeScript 类型守卫（target is Annotation），Annotation类型在 types.ts 中被定义为(...args: any[]) => any。因此经过isAnnotation判定后的值，在类型上可以直接作为函数使用。

使用示例

import { observable, isAnnotation } from '@formily/reactive' console.log(isAnnotation(observable.ref)) // true console.log(isAnnotation(observable.computed)) // true console.log(isAnnotation(() => {})) // false，普通函数不是注解

在 model.ts 中，define()遍历用户传入的注解配置时，正是用isAnnotation(annotation)过滤出合法注解，再交由getObservableMaker(annotation)生成实际的观察器，从而支持"在类字段上按属性声明响应式策略"的编程模型：

for (const key in annotations) { const annotation = annotations[key] if (isAnnotation(annotation)) { getObservableMaker(annotation)({ target, key }) } }

isSupportObservable：判断值是否可被响应式化

语义与签名

interface isSupportObservable { (target: any): boolean }

isSupportObservable(target)判断一个值是否具备被包装为可观察对象的能力。这是三者中逻辑最复杂、也最体现工程考量的 API：它不仅要识别"哪些类型可以观察"，还要主动排除"哪些对象不应该被观察"。

底层实现

完整实现位于 externals.ts：

export const isSupportObservable = (target: any) => { if (!isValid(target)) return false if (isArr(target)) return true if (isPlainObj(target)) { if (target[RAW_TYPE]) return false if (target[OBSERVABLE_TYPE]) return true if ('$$typeof' in target && '_owner' in target) return false if (target['_isAMomentObject']) return false if (target['_isJSONSchemaObject']) return false if (isFn(target['toJS'])) return false if (isFn(target['toJSON'])) return false return true } if (isMap(target) || isWeakMap(target) || isSet(target) || isWeakSet(target)) return true return false }

可以按判断顺序拆解为五层规则：

1. 基础值排除

if (!isValid(target)) return false

isValid定义于 checkers.ts，即val !== null && val !== undefined。null/undefined以及所有非引用类型的原始值（数字、字符串、布尔等）都无法被响应式化，直接返回false。

2. 数组与普通对象放行

if (isArr(target)) return true if (isPlainObj(target)) { ... }

数组（Array.isArray）无条件支持；普通对象（Object.prototype.toString为[object Object]）进入后续黑名单检查。注意这里的isPlainObj与 checkers.ts 的定义一致，只认纯对象字面量。

3. 用户显式标记优先

if (target[RAW_TYPE]) return false if (target[OBSERVABLE_TYPE]) return true

这两个标记分别由markRaw与markObservable设置，说明用户可以通过显式标记"越权"覆盖默认的类型推断——详见下文"markRaw 与 markObservable：人为控制可观察性"小节。

4. 框架对象黑名单

if ('$$typeof' in target && '_owner' in target) return false // React 元素 if (target['_isAMomentObject']) return false // moment 实例 if (target['_isJSONSchemaObject']) return false // JSON Schema 对象 if (isFn(target['toJS'])) return false // MobX 等库的 toJS if (isFn(target['toJSON'])) return false // 序列化对象

这部分是 Formily 跨框架设计的关键体现：

• $$typeof+_owner是 React 元素（ReactElement）的内部标记，React 元素应保持不可变，不应被响应式化；
• _isAMomentObject是 moment.js 时间对象的标记，日期对象参与响应式化会引发不可预期行为；
• _isJSONSchemaObject是 Formily 自身 json-schema 包中 JSON Schema 对象的标记，Schema 元数据不应被观察；
• 具备toJS/toJSON方法的对象，通常是其他库（如 MobX）的响应式对象或自带序列化契约的类型，交由原库管理更安全。

5. 集合类型放行

if (isMap(target) || isWeakMap(target) || isSet(target) || isWeakSet(target)) return true

Map、WeakMap、Set、WeakSet四种集合类型均被支持，这与checkers.ts中isCollectionType的判定范围一致。

测试用例佐证

externals.spec.ts 完整验证了上述规则：

expect(isSupportObservable(obs)).toBe(true) expect(isSupportObservable(new Class())).toBe(true) expect(isSupportObservable(null)).toBe(false) expect(isSupportObservable([])).toBe(true) expect(isSupportObservable({})).toBe(true) expect(isSupportObservable({ $$typeof: {}, _owner: {} })).toBe(false) expect(isSupportObservable({ _isAMomentObject: {} })).toBe(false) expect(isSupportObservable({ _isJSONSchemaObject: {} })).toBe(false) expect(isSupportObservable({ toJS: () => {} })).toBe(false) expect(isSupportObservable({ toJSON: () => {} })).toBe(false) expect(isSupportObservable(new Map())).toBe(true) expect(isSupportObservable(new WeakMap())).toBe(true) expect(isSupportObservable(new Set())).toBe(true) expect(isSupportObservable(new WeakSet())).toBe(true)

同时在 annotations.spec.ts 中对isObservable的各种 Proxy / 盒子 / 原始对象组合进行了断言，确保判断结果在不同创建路径下保持一致。

使用示例

import { observable, isSupportObservable } from '@formily/reactive' isSupportObservable({ a: 1 }) // true isSupportObservable([1, 2, 3]) // true isSupportObservable(new Map()) // true isSupportObservable(null) // false isSupportObservable(<div />) // false（React 元素）

在 model.ts 中，define()会先执行if (!isSupportObservable(target)) return target，对不满足条件的对象直接原样返回，避免对类实例、框架对象等做无意义的包装。

markRaw 与 markObservable：人为控制可观察性

isSupportObservable的判定并非只能被动接受，Formily 还提供了两个配套 API 让开发者主动干预：

• markRaw(target)：为对象（或函数的prototype）打上RAW_TYPE标记，使其永远不被响应式化；
• markObservable(target)：为对象打上OBSERVABLE_TYPE标记，强制其可以被响应式化。

两者实现于 externals.ts：

export const markRaw = <T>(target: T): T => { if (!target) return if (isFn(target)) { target.prototype[RAW_TYPE] = true } else { target[RAW_TYPE] = true } return target } export const markObservable = <T>(target: T): T => { if (!target) return if (isFn(target)) { target.prototype[OBSERVABLE_TYPE] = true } else { target[OBSERVABLE_TYPE] = true } return target }

两个 API 均支持函数与普通对象两种形态：传入函数时标记落在其prototype上，从而对"该类的所有实例"生效；传入对象时标记直接落在对象自身。由于isSupportObservable中 RAW_TYPE 的排除检查优先于 OBSERVABLE_TYPE 的放行检查，markRaw的优先级更高——这在"类实例默认被排除、个别实例被标记可观察"等复杂场景下提供了清晰的裁决顺序。

典型场景：如果你有一个第三方类的实例，Formily 默认不观察它（避免误伤框架对象），但你又确实需要它参与响应式，可以调用markObservable(instance)显式放行；反之，如果某个普通对象包含不宜观察的内容（如大体积二进制数据），markRaw(obj)可将其永久排除在响应式系统之外。

三者协同：响应式系统中的"门卫"分工

从 model.ts 中define()的实现，可以清晰看到三个 API 在真实代码中的协作关系：

export function define<Target extends object = any>( target: Target, annotations?: Annotations<Target> ): Target { if (isObservable(target)) return target // 已响应式化则直接返回 if (!isSupportObservable(target)) return target // 不支持则原样返回 target[ObModelSymbol] = target buildDataTree(undefined, undefined, target) for (const key in annotations) { const annotation = annotations[key] if (isAnnotation(annotation)) { // 校验注解合法性 getObservableMaker(annotation)({ target, key }) } } return target }

处理流程呈现典型的三道门卫：

1. isObservable（幂等检查）：对象已是响应式代理 → 直接返回，不做重复包装；
2. isSupportObservable（资格检查）：对象类型不允许 / 属于框架黑名单 / 被markRaw排除 → 原样返回；
3. isAnnotation（注解校验）：遍历注解配置时，只把真正的注解函数交给getObservableMaker执行。

而在model()（model.ts）中，类字段的默认注解策略也依赖类型判断：getter 属性映射为observable.computed、函数字段映射为action、其余字段映射为observable，最终统一交给define()处理——这套"字段类型 → 响应式策略"的自动推导，正是构建 Formily 表单模型（FormModel / FieldModel）的基础设施。

总结

Formily Reactive 的三个类型检查 API 构成了响应式对象的"准入与识别"机制：

• isObservable：通过ProxyRawWeakMap 与ObModelSymbol双重机制，识别已响应式化的 Proxy 代理与盒子对象；
• isAnnotation：通过MakeObModelSymbol标记识别响应式注解函数，并利用 TypeScript 类型守卫提供编译期类型收窄；
• isSupportObservable：层层过滤原始值、框架对象黑名单（React 元素、moment、JSON Schema、toJS/toJSON 对象），放行数组、普通对象与四种集合类型，并尊重markRaw/markObservable的显式标记。

这三个 API 的组合使用，既保证了 Formily 在 React / React Native / Vue 2 / Vue 3 等跨框架场景下的安全响应式化，也避免了库与库之间的相互干扰。若要深入理解其行为，建议结合 externals.ts、model.ts 以及 externals.spec.ts 中的测试用例进行验证。

• 前端
• UI组件