如何用TypeScript递归类型为JSON对象做深度类型校验

假设你正在对接一个外部数据平台，返回的配置对象里有超过六层的嵌套结构，既包含数组又包含对象，字段还经常变更。如果每个层级都单独声明一个interface，维护成本会随嵌套深度线性上升；如果直接标注成any，TypeScript的静态检查就会完全失效，一个深层的undefined可能在用户点击按钮时才暴露出来。解决这个问题的关键，不是逐层手写类型，而是让类型系统自己描述任意深度的JSON结构。

一、从固定结构到递归模型：为什么interface不够用

一个简单的JSON对象通常可以用interface来声明。例如一个用户信息结构可以写成interface User { name: string; age: number; }。这种写法在字段结构稳定、层级不超过两三层时非常直观，编辑器也能给出完整的补全提示。但是当数据来自开放平台、第三方接口或者用户自定义配置时，结构往往不再固定。一个字段可能有时返回字符串，有时返回数字，有时返回一个包含任意键值对的对象。这种情况下，如果继续使用interface，就必须为每一种可能的形状都声明一套类型，甚至把不稳定的字段直接弱化成any。

更重要的是，JSON规范允许数据以任意深度嵌套。一个对象的值可以是数组，数组里的元素又可以是对象，对象里再包含数组。这样的结构如果逐层定义，会出现LevelOne、LevelTwo、LevelThree这样的接口名称，而且稍一调整层级，就必须新增或修改大量类型声明。对于需要处理通用JSON数据的工具函数来说，这种维护方式显然不可持续。

递归类型定义恰好解决了这个矛盾。它不像普通interface那样描述某一层固定的形状，而是描述一种规则：一个合法的JSON值要么是原始类型，要么是键值对集合，其中的值仍然是合法的JSON值，要么是数组，数组元素也仍然是合法的JSON值。这种自引用的描述方式能够让TypeScript精确覆盖任意深度的JSON结构，同时保留类型检查能力。下面就来一步步实现这套递归模型。

二、递归类型定义：JSONValue、JSONObject与JSONArray

要描述JSON结构，首先需要明确JSON规范中允许出现哪些数据类型。根据标准，合法的JSON值包括字符串、数字、布尔值、null、对象和数组。对象是由字符串键映射到JSON值的集合，数组是JSON值的有序列表。这三者可以形成一个递归定义。

type JSONValue =
  | string
  | number
  | boolean
  | null
  | JSONObject
  | JSONArray;

interface JSONObject {
  [key: string]: JSONValue;
}

interface JSONArray extends Array<JSONValue> {}

这里的JSONValue是联合类型，它把原始类型和两个结构化类型组合在一起。JSONObject使用索引签名表示任意字符串键都对应一个JSONValue。JSONArray则通过继承Array<JSONValue>来表明数组元素也必须是合法JSON值。由于JSONValue中引用了JSONObject和JSONArray，而这两个类型又反过来引用JSONValue，所以整个定义形成了递归闭环。

需要说明的是，TypeScript对类型别名的递归引用有一定限制。直接写type JSONObject = { [key: string]: JSONValue }没有问题，但如果把JSONObject和JSONArray都定义为type而不是interface，编译器有时会提示循环引用错误。使用interface来定义结构化类型是更稳妥的选择，因为接口可以延迟解析内部属性。另外，这个递归类型只约束了字段值的类型，并不会限制对象的深度，因此可以精确表示任意层级的JSON数据。

有了编译期的类型定义之后，接下来要解决的问题是：运行时拿到的数据并不天然满足这个类型。网络请求返回的内容在TypeScript眼中通常只是unknown或any，只有经过校验之后，才能安全地把它们当成JSONValue来使用。这就需要运行时类型守卫来配合。

三、运行时深度校验：类型守卫与错误路径收集

类型定义只负责编译期的静态检查，但真实数据在运行时可能来自不可信的外部来源。浏览器不会因为你声明了JSONValue就自动拦截一个带有函数属性或undefined的对象。因此，必须编写递归的类型守卫函数，在数据进入业务逻辑之前进行真实的运行时校验。

首先要实现一个能区分普通对象和数组的基础判断函数。typeof value === 'object'对数组也会返回true，所以需要排除数组。同时null虽然类型是object，但不是合法JSON对象，也必须排除。这个函数通常命名为isPlainObject。

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function isJSONObject(value: unknown): value is JSONObject {
  if (!isPlainObject(value)) {
    return false;
  }
  return Object.values(value).every(isJSONValue);
}

function isJSONArray(value: unknown): value is JSONArray {
  return Array.isArray(value) && value.every(isJSONValue);
}

function isJSONValue(value: unknown): value is JSONValue {
  if (value === null) {
    return true;
  }
  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
    return true;
  }
  if (Array.isArray(value)) {
    return isJSONArray(value);
  }
  if (isPlainObject(value)) {
    return isJSONObject(value);
  }
  return false;
}

这段代码使用value is JSONObject这种类型谓词写法，让TypeScript在条件分支内自动缩小变量类型。当isJSONValue返回true时，调用方就可以把参数当作JSONValue来使用。校验逻辑本身是递归的：对象需要检查每个值，数组需要检查每个元素，原始类型和null直接通过。这样就能保证嵌套层级再多，也会被逐层检查到。

不过，上面的校验函数只能返回一个布尔值，业务方无法知道究竟是哪个字段出了问题。对于大型JSON配置来说，报错时只说一句“格式不对”几乎没有可操作性。因此可以在递归过程中收集错误路径，形成更友好的提示信息。

interface ValidationResult {
  valid: boolean;
  errors: string[];
}

function validateJSON(value: unknown, path = '$'): ValidationResult {
  const errors: string[] = [];

  if (value === null) {
    return { valid: true, errors };
  }

  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
    return { valid: true, errors };
  }

  if (Array.isArray(value)) {
    value.forEach((item, index) => {
      const child = validateJSON(item, `${path}[${index}]`);
      if (!child.valid) {
        errors.push(...child.errors);
      }
    });
    return { valid: errors.length === 0, errors };
  }

  if (isPlainObject(value)) {
    Object.entries(value).forEach(([key, childValue]) => {
      const child = validateJSON(childValue, `${path}.${key}`);
      if (!child.valid) {
        errors.push(...child.errors);
      }
    });
    return { valid: errors.length === 0, errors };
  }

  errors.push(`${path}: 不支持的类型 ${typeof value}`);
  return { valid: false, errors };
}

这个validateJSON函数在遍历数组和对象时会拼接路径，例如$.users[0].profile.settings，一旦遇到函数、undefined、Symbol等非法类型，就会把具体路径和类型记录下来。调用方可以一次性拿到所有错误位置，而不用反复调试定位。配合前面的类型谓词，校验通过后的数据可以直接标注为JSONValue，从而同时获得运行时安全和编译期安全。

四、条件类型与映射类型：静态层面的深度变换

递归类型不仅能用来校验，还能结合条件类型和映射类型对深层结构做静态变换。例如你想把某个JSON配置对象的所有属性都变成只读，普通的Readonly<T>只会处理第一层，嵌套对象内部的属性依然可变。此时可以定义一个深度只读类型。

type DeepReadonly<T> =
  T extends JSONArray ? ReadonlyArray<DeepReadonly<T[number]>> :
  T extends JSONObject ? { readonly [K in keyof T]: DeepReadonly<T[K]> } :
  T;

type DeepPartial<T> =
  T extends JSONArray ? Array<DeepPartial<T[number]>> :
  T extends JSONObject ? { [K in keyof T]?: DeepPartial<T[K]> } :
  T;

DeepReadonly首先判断传入类型是否为数组。如果是，则返回一个只读数组类型，同时用T[number]取出元素类型继续递归处理。如果传入类型是对象，则遍历所有键，将每个属性递归应用DeepReadonly。如果既不是数组也不是对象，说明已经到达叶子节点，直接返回原类型即可。同理，DeepPartial可以把每一层属性都变成可选，适合处理不完整配置或增量更新场景。

这类深度变换类型在实际项目中有很多应用。比如从服务端获取一份默认可选配置，前端需要在不修改原对象的情况下合并用户输入，此时所有层级都标记为只读能够避免误操作。再比如一个表单草稿功能，需要允许用户只修改部分字段，DeepPartial可以让编译器自动接受不完整的深层对象。相比手动写一堆局部只读或局部可选接口，递归条件类型更加通用，也更容易维护。

需要注意的是，深度变换类型在实例化时会消耗更多的编译器资源。对于非常大的对象结构，递归映射类型可能让类型检查时间变长。同时，TypeScript对递归类型的实例化深度也有默认限制，通常是50层左右。虽然实际JSON数据很少达到这个深度，但了解这个限制有助于在遇到相关报错时快速定位原因。

五、工程实践与性能考量

递归类型定义和深度校验函数非常适合处理通用JSON数据，但在实际工程中还是需要结合具体场景来权衡。如果数据来源完全可控，比如前后端约定稳定、由同一团队维护，那么可以直接使用手写interface，获得更好的精确提示。如果数据来自开放平台、用户上传的配置文件或第三方回调，那么递归JSON类型和校验函数就非常有必要。

对于特别复杂的JSON Schema，手动递归定义可能会变得繁琐。不少团队会使用工具从JSON Schema自动生成TypeScript类型定义，这样既能保证类型准确，又能减少手写成本。自动生成的类型往往包含递归引用，原理与本文介绍的JSONValue模型类似，只是结构更复杂。理解递归类型的工作方式，有助于阅读和调试这些自动生成的类型声明。

另外，深度校验函数虽然能发现大多数形状问题，但并不能检查业务规则，例如某个字段是否在指定枚举范围内、某个数字是否大于零。这些约束需要额外的业务校验逻辑来补充。通常的做法是先用通用JSON结构校验保证数据形状合法，再用具体interface和业务规则进行二次校验。将通用递归校验与领域模型约束分层处理，可以让代码保持清晰，也不会把所有校验责任都堆在一个函数里。

总结来说，递归类型让TypeScript具备了描述任意深度JSON结构的能力，类型守卫则把这种能力延伸到运行时。通过JSONValue、JSONObject和JSONArray三个核心类型，再配合递归校验函数和深度变换类型，可以构建出一套既安全又灵活的JSON处理方案。当你在项目中再次遇到深层嵌套数据时，不必再为每一层手写interface，也不要轻易退回any，递归类型会是一个更可靠的选择。

TypeScript递归类型JSON深度校验类型安全修改时间：2026-08-26 15:32:26