将TypeScript推断类型转换为JSON模式表示的编程指南

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

将TypeScript推断类型转换为JSON模式表示的编程指南

2025-10-11

浏览次数：次

返回列表

将TypeScript推断类型转换为JSON模式表示的编程指南

本文深入探讨如何利用typescript编译器api，将typescript文件中导出的常量对象的推断类型结构，以编程方式转换为json格式的类型模式表示。我们将详细讲解如何解析抽象语法树（ast）、获取精确的类型信息，并递归构建所需的类型描述json，从而实现对类型而非运行时值的结构化表示。

在TypeScript开发中，我们经常会遇到需要将代码中定义的类型结构，以某种标准化的数据格式（例如JSON）进行表示或传输的场景。这不同于简单地将一个J*aScript对象的运行时值转换为JSON字符串。用户期望的是一个反映类型名称（如"string"、"number"）的JSON结构，而非实际的字面量值。要实现这一目标，我们需要借助TypeScript编译器API来深入解析源代码，提取其类型元数据。

理解类型转换的核心挑战：类型与值的区分

考虑以下TypeScript文件 my-ts-file.ts：

// my-ts-file.ts
const inner = {
  hello: "world",
};

export const value = {
  prop1: "hello",
  prop2: "world",
  prop3: 42,
  prop4: inner,
};

当TypeScript编译器处理这段代码时，它会为 value 变量推断出如下类型：

const value: {
    prop1: string;
    prop2: string;
    prop3: number;
    prop4: {
        hello: string;
    };
}

用户希望得到的是一个JSON结构，其中每个属性的值是其对应的TypeScript类型名称，例如：

{
    "prop1": "string",
    "prop2": "string",
    "prop3": "number",
    "prop4": {
        "hello": "string"
    }
}

简单地使用 JSON.parse(JSON.stringify(value)) 只能将 value 的运行时值转换为JSON，其结果将是：

{
    "prop1": "hello",
    "prop2": "world",
    "prop3": 42,
    "prop4": {
        "hello": "world"
    }
}

这显然不符合将“推断类型”转换为JSON模式的需求。因此，我们需要一个能够访问和解释TypeScript类型系统的工具，即TypeScript编译器API。

借助TypeScript编译器API解析类型信息

TypeScript编译器API提供了一套强大的接口，允许我们以编程方式与TypeScript代码进行交互。它能够解析源代码文件，构建抽象语法树（AST），并执行类型检查，从而获取到变量、函数、类等的详细类型信息。

实现将推断类型转换为JSON模式的关键步骤如下：

创建TypeScript程序实例： 加载目标TypeScript文件并建立编译器上下文。
获取类型检查器： 类型检查器是访问所有类型信息的入口。
定位目标变量： 在AST中找到我们感兴趣的 export const value 变量声明。
提取变量类型： 使用类型检查器获取该变量的精确推断类型。
递归遍历类型结构： 将获取到的类型对象递归地转换为我们期望的JSON模式。

实现步骤详解

首先，确保你的项目中安装了 typescript 包：

秀脸FacePlay

一款集成AI换脸、照片跳舞等多种AI特效玩法的App

124 查看详情秀脸FacePlay

npm install typescript

接下来，我们将创建一个Node.js脚本（例如 type-extractor.ts）来实现上述逻辑。

1. 目标TypeScript文件 (my-ts-file.ts)

// my-ts-file.ts
const inner = {
  hello: "world",
};

export const value = {
  prop1: "hello",
  prop2: "world",
  prop3: 42,
  prop4: inner,
};

export const anotherValue = {
  items: [1, 2, 3],
  status: "active",
};

2. 类型提取脚本 (type-extractor.ts)

import * as ts from 'typescript';
import * as path from 'path';

/**
 * 将TypeScript类型对象转换为其对应的字符串名称。
 * @param typeChecker TypeScript类型检查器实例。
 * @param type TypeScript类型对象。
 * @returns 类型的字符串表示（如 "string", "number", "boolean", "object", "array"）。
 */
function getTypeString(typeChecker: ts.TypeChecker, type: ts.Type): string {
    if (type.flags & ts.TypeFlags.String) {
        return "string";
    }
    if (type.flags & ts.TypeFlags.Number) {
        return "number";
    }
    if (type.flags & ts.TypeFlags.Boolean) {
        return "boolean";
    }
    if (type.flags & ts.TypeFlags.Null) {
        return "null";
    }
    if (type.flags & ts.TypeFlags.Undefined) {
        return "undefined";
    }
    if (type.flags & ts.TypeFlags.Any) {
        return "any";
    }
    if (type.flags & ts.TypeFlags.Void) {
        return "void";
    }
    if (type.flags & ts.TypeFlags.Unknown) {
        return "unknown";
    }
    if (type.flags & ts.TypeFlags.BigInt) {
        return "bigint";
    }
    if (type.flags & ts.TypeFlags.ESSymbol) {
        return "symbol";
    }

    // 检查是否为数组类型
    if (typeChecker.isArrayLikeType(type)) {
        const elementType = typeChecker.getTypeArguments(type as ts.TypeReference)[0];
        if (elementType) {
            return getTypeString(typeChecker, elementType) + "[]";
        }
        return "any[]"; // 无法确定元素类型
    }

    // 检查是否为对象类型（包括字面量对象和接口）
    if (type.flags & ts.TypeFlags.Object || typeChecker.getPropertiesOfType(type).length > 0) {
        return "object";
    }

    // 默认返回类型文本，这对于更复杂的类型（如联合类型、字面量类型）可能更精确
    return typeChecker.typeToString(type);
}

/**
 * 递归地将TypeScript类型转换为JSON模式表示。
 * @param typeChecker TypeScript类型检查器实例。
 * @param type TypeScript类型对象。
 * @returns 对应的JSON模式对象。
 */
function convertTypeToJsonSchema(typeChecker: ts.TypeChecker, type: ts.Type): any {
    // 检查是否为原始类型
    const primitiveType = getTypeString(typeChecker, type);
    if (primitiveType !== "object" && !primitiveType.endsWith("[]")) {
        return primitiveType;
    }

    // 检查是否为数组类型
    if (typeChecker.isArrayLikeType(type)) {
        const elementType = typeChecker.getTypeArguments(type as ts.TypeReference)[0];
        return [elementType ? convertTypeToJsonSchema(typeChecker, elementType) : "any"];
    }

    // 处理对象类型
    const properties: { [key: string]: any } = {};
    const symbol = type.getSymbol();

    if (symbol && symbol.declarations && symbol.declarations.length > 0) {
        // 尝试从声明中获取属性（例如接口或类型别名）
        const declaration = symbol.declarations[0];
        if (ts.isInterfaceDeclaration(declaration) || ts.isTypeAliasDeclaration(declaration)) {
            typeChecker.getPropertiesOfType(type).forEach(prop => {
                const propType = typeChecker.getTypeOfSymbolAtLocation(prop, declaration);
                properties[prop.getName()] = convertTypeToJsonSchema(typeChecker, propType);
            });
            return properties;
        }
    }

    // 对于匿名对象字面量，直接获取其属性
    typeChecker.getPropertiesOfType(type).forEach(prop => {
        const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration || prop.declarations[0]);
        properties[prop.getName()] = convertTypeToJsonSchema(typeChecker, propType);
    });

    return properties;
}

/**
 * 提取指定文件中导出变量的类型并转换为JSON模式。
 * @param filePath 目标TypeScript文件的路径。
 * @param variableName 目标导出变量的名称。
 * @returns 包含类型模式的JSON对象，如果未找到则为null。
 */
function extractExportedVariableTypeAsJson(filePath: string, variableName: string): any | null {
    const program = ts.createProgram([filePath], {
        target: ts.ScriptTarget.ESNext,
        module: ts.ModuleKind.CommonJS,
        strict: true,
        // 如果你的项目有tsconfig.json，可以这样加载
        // project: path.dirname(filePath)
    });

    const sourceFile = program.getSourceFile(filePath);
    if (!sourceFile) {
        console.error(`Error: Could not find source file at ${filePath}`);
        return null;
    }

    const typeChecker = program.getTypeChecker();
    let result: any | null = null;

    ts.forEachChild(sourceFile, node => {
        // 查找 `export const variableName = ...`
        if (ts.isVariableStatement(node) && node.modifiers &&
            node.modifiers.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) {
            node.declarationList.declarations.forEach(declaration => {
                if (ts.isIdentifier(declaration.name) && declaration.name.text === variableName) {
                    const symbol = typeChecker.getSymbolAtLocation(declaration.name);
                    if (symbol) {
                        const type = typeChecker.getTypeOfSymbolAtLocation(symbol, declaration.name);
                        result = convertTypeToJsonSchema(typeChecker, type);
                    }
                }
            });
        }
    });

    return result;
}

// 示例用法
const tsFilePath = path.join(__dirname, 'my-ts-file.ts');

const valueTypeJson = extractExportedVariableTypeAsJson(tsFilePath, 'value');
if (valueTypeJson) {
    console.log(`Type schema for 'value':\n${JSON.stringify(valueTypeJson, null, 2)}`);
}

const anotherValueTypeJson = extractExportedVariableTypeAsJson(tsFilePath, 'anotherValue');
if (anotherValueTypeJson) {
    console.log(`\nType schema for 'anotherValue':\n${JSON.stringify(anotherValueTypeJson, null, 2)}`);
}

运行结果：

Type schema for 'value':
{
  "prop1": "string",
  "prop2": "string",
  "prop3": "number",
  "prop4": {
    "hello": "string"
  }
}

Type schema for 'anotherValue':
{
  "items": [
    "number"
  ],
  "status": "string"
}

代码解析

extractExportedVariableTypeAsJson 函数：
- 创建 ts.Program 实例来加载和编译TypeScript文件。
- 获取 ts.SourceFile 和 ts.TypeChecker，它们是进行AST遍历和类型检查的核心。
- 遍历源文件的AST，查找带有 export 关键字且名称匹配 variableName 的 const 变量声明。
- 通过 typeChecker.getSymbolAtLocation 获取变量的符号（Symbol），再通过 typeChecker.getTypeOfSymbolAtLocation 获取其完整的 ts.Type 对象。
- 将获取到的 ts.Type 对象传递给 convertTypeToJsonSchema 进行递归转换。
convertTypeToJsonSchema 函数：
- 这是核心的递归函数。它接收 ts.Type 对象并尝试将其转换为JSON模式。
- 首先通过 getTypeString 尝试识别基本类型（string, number, boolean等）和数组类型。
- 如果类型是对象（ts.TypeFlags.Object），它会获取该类型的所有属性 (typeChecker.getPropertiesOfType)。
- 对于每个属性，它递归调用 convertTypeToJsonSchema 来获取其子类型模式，并将其添加到结果对象中。
- 对于数组类型，它会尝试获取数组的元素类型 (typeChecker.getTypeArguments)，并递归处理元素类型。
getTypeString 函数：
- 这是一个辅助函数，用于将 ts.Type 对象映射到其常见的字符串表示。
- 它通过检查 ts.TypeFlags 来判断基本类型。
- 特别处理了数组类型 (typeChecker.isArrayLikeType)，以返回如 "string[]" 的格式。
- 对于复杂或无法直接映射为基本类型的对象，它会返回 "object" 或通过 typeChecker.typeToString 返回其文本表示。

注意事项与进阶考量

复杂类型处理： 上述示例主要处理了基本类型、对象字面量和数组。对于更复杂的TypeScript类型，例如：
- 联合类型 (string | number)： 需要在JSON模式中表示为 ["string", "number"] 或 { "oneOf": ["string", "number"] }。
- 交叉类型 (TypeA & TypeB)： 可能需要合并属性。
- 泛型 (Array)、接口 (interface MyInterface)、类型别名 (type MyType = ...)： 需要更复杂的逻辑来解析和展开这些类型。
- 枚举 (enum MyEnum)： 可以表示为字符串或数字的列表。
- 字面量类型 ("hello", 42)： 可以直接表示为对应的字符串或数字。这些情况需要扩展 convertTypeToJsonSchema 函数，根据 ts.Type 对象的更多属性和 ts.TypeFlags 来判断和处理。
性能考量： 对于大型项目，使用TypeScript编译器API进行完整的程序解析和类型检查可能是一个耗时的操作。如果只需要处理少量文件或特定类型的导出，可以考虑优化程序创建和文件解析的策略。
错误处理： 在实际应用中，需要增加健壮的错误处理机制，例如文件不存在、语法错误、变量未找到等情况。
JSON Schema标准： 如果目标是生成符合JSON Schema标准的输出，那么上述 convertTypeToJsonSchema 函数需要进一步扩展，以包含 type, properties, items, required, enum 等JSON Schema关键字。例如，数组类型应表示为 { "type": "array", "items": { "type": "number" } }。
现有工具： 对于生成JSON Schema的需求，社区中已有成熟的工具，如 ts-json-schema-generator，它们提供了更全面、更符合JSON Schema规范的解决方案。本文提供的方案更侧重于展示如何从底层利用TypeScript编译器API实现这一过程。

总结

通过TypeScript编译器API，我们可以深入到源代码的抽象语法树和类型系统中，以编程方式提取并分析类型信息。本文详细介绍了如何加载TypeScript文件、获取类型检查器、定位目标变量并递归地将其推断类型转换为自定义的JSON模式表示。理解并掌握这一过程，对于构建代码分析工具、类型文档生成器或动态表单生成器等场景具有重要的意义。虽然处理所有复杂的TypeScript类型需要更精细的逻辑，但本文提供的基础框架为进一步的扩展和定制奠定了坚实的基础。

以上就是将TypeScript推断类型转换为JSON模式表示的编程指南的详细内容，更多请关注其它相关文章！

# 加载 # 营销网站搭建seo优化 # 麦当劳网络营销和推广 # 抖音怎样看关键词排名 # 服装营销推广方案策划书 # 北大青鸟seo # 短视频营销推广模板范文 # 万象台内容营销推广策略 # 外贸网站 seo 插件 # 网站推广试卷怎么做的 # 京东社交媒体营销推广 # 将其 # 子类 # 源代码 # 这一 # javascript # 它会 # 的是 # 遍历 # 转换为 # 递归 # 递归函数 # 工具 # typescript # node # json # node.js # js # java # word