如何利用 isRef 和 isReactive 编写通用的工具函数？类型守卫实战

如何利用 isRef 和 isReactive 编写通用的工具函数？类型守卫实战

直接使用 isRef 和 isReactive 来构建工具函数，其核心目标在于让函数能够智能地适应不同的输入类型。这样一来，就能有效避免手动进行类型断言、防止因误判而导致的 .value 访问错误，同时也能巧妙地绕过 Proxy 对象的递归陷阱。本质上，它们并非简单的“开关”，而是 TypeScript 类型推理过程中不可或缺的“引路牌”。

统一取值：safeUnref —— 安全解包任意输入

在开发组合式函数时，我们常常会遇到一个典型场景：函数既要能处理 ref 包装的值，也要能接受原始值（比如普通的 number 或 string）。这时候，如果直接硬编码 .value 肯定会出错，但盲目调用 Vue 内置的 unref() 函数也有其局限——虽然它对非 ref 输入是安全的，但在类型推导层面，有时无法提供精准的类型缩小。怎么办呢？用 isRef 作为类型守卫，TypeScript 编译器就能在条件分支里明确识别出 val 是 Ref 类型，从而允许我们安全地访问其 .value 属性：

function safeUnref(val: T | Ref): T {
  if (isRef(val)) {
    return val.value; // 此时 TS 明确知道 val 是 Ref，.value 的类型就是 T
  }
  return val; // 在此分支，TS 则知道 val 已经是原始类型 T
}

不妨对比一下内置的 unref()：它有时会返回 unknown 类型，或者泛型推导不够稳定。而 safeUnref 在函数被调用时，能保留完整的类型信息，非常适合作为参数预处理的步骤，封装在各类 useXXX 函数内部。

响应式对象校验与降级：toRawIfReactive

有些特定的逻辑，比如进行 JSON 序列化，或者初始化某些第三方库，它们要求操作必须是原始数据对象。然而，传入的参数很可能是一个已经被 reactive 包裹的响应式对象。这时，利用 isReactive 进行判断，再决定是否调用 toRaw 来“降级”对象，同时还能确保类型的精准无误：

function toRawIfReactive(obj: T): T {
  if (isReactive(obj)) {
    return toRaw(obj) as T; // toRaw 返回原始对象，但我们仍将其类型标注为 T
  }
  return obj;
}

这里有几个关键点值得注意：

• 全程避免使用 any 断言，也无需借助 @ts-ignore 来忽略类型检查。
• 函数的签名始终保持为 T → T，这意味着调用方完全无需关心函数内部是否执行了 toRaw 转换。
• 得益于 isReactive 提供的类型守卫，TypeScript 能够百分百确认 toRaw 只会在 reactive 对象的分支中被调用，绝不会误用于普通对象。

混合 props 处理：extractValueFromProp

在 Vue 组件中，当我们使用 defineProps 并配合解构语法后，某个 prop 的实际形态可能会变得复杂：它可能是 ref，可能是 reactive 对象，也可能就是一个普通值（在使用泛型组件时尤其常见）。我们需要一个函数，能统一提取出它的“实质值”，并让后续的代码拥有明确的类型：

function extractValueFromProp(
  prop: T | Ref | Reactive
): T {
  if (isRef(prop)) {
    return prop.value;
  }
  if (isReactive(prop)) {
    return { ...prop } as T; // 通过展开运算符进行浅拷贝，适用于结构简单的对象
  }
  return prop;
}

需要说明的是，这里的 Reactive 是一个自定义类型（例如可以定义为 type Reactive = T & { __v_isReactive?: true }），在实际应用中，可以通过泛型约束结合类型谓词来进一步增强其准确性。这类函数在封装表单控件、状态同步钩子等场景中非常常见，能有效避免在每个组件里重复编写繁琐的三重类型判断逻辑。

调试辅助：logReactivityStatus

在开发阶段，我们经常需要快速定位响应式行为异常的问题，比如 watch 监听器没有触发，或者 computed 计算属性的缓存意外失效——这些问题，很多时候都是因为传递了错误类型的值。一个带有清晰类型提示的日志函数，此时就显得非常实用：

function logReactivityStatus(val: unknown, label: string = 'value') {
  console.group(`${label}:`);
  console.log('isRef:', isRef(val));
  console.log('isReactive:', isReactive(val));
  console.log('isReadonly:', isReadonly(val));
  console.log('type:', typeof val, val?.constructor?.name);
  console.groupEnd();
}

这个函数本身不改变任何程序逻辑，但每次调用它，都能帮你快速确认：当前的这个值，到底是不是你“以为”的那种响应式形态。将其与 watch 的回调函数或者 onMounted 生命周期钩子结合使用，排查问题的效率能获得显著提升。