本文深入探讨如何利用typescript编译器api，将typescript文件中导出的常量对象的推断类型结构，以编程方式转换为json格式的类型模式表示。我们将详细讲解如何解析抽象语法树（ast）、获取精确的类型信息，并递归构建所需的类型描述json，从而实现对类型而非运行时值的结构化表示。
在TypeScript开发中，我们经常会遇到需要将代码中定义的类型结构，以某种标准化的数据格式（例如JSON）进行表示或传输的场景。这不同于简单地将一个JavaScript对象的运行时值转换为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 包：
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类型需要更精细的逻辑，但本文提供的基础框架为进一步的扩展和定制奠定了坚实的基础。
