发布于 由admin

Vue组件的API类型生成：从源代码中自动提取类型信息

Vue 组件 API 类型生成：从源代码中自动提取类型信息

大家好！今天我们来探讨一个在 Vue 组件开发中非常实用且能显著提升开发效率的话题：Vue 组件 API 类型生成，特别是从源代码中自动提取类型信息。

手动维护 Vue 组件的 API 文档和类型定义是一项繁琐且容易出错的工作。随着组件数量和复杂度的增加，维护成本会越来越高。而自动提取类型信息，能够保证文档的准确性，减少手动维护的工作量，并能在开发过程中提供更好的类型提示和校验，从而提高代码质量和开发效率。

为什么要自动生成 API 类型

在深入细节之前，我们先来明确一下自动生成 API 类型的重要性：

  1. 提升开发效率: 类型提示和自动补全可以减少查阅文档的时间，加快开发速度。

  2. 减少人为错误: 自动生成的类型定义可以避免手动编写时可能出现的错误，提高代码质量。

  3. 保持文档同步: 自动提取类型信息可以确保文档与代码保持同步，避免文档过时。

  4. 增强代码可维护性: 明确的类型定义可以提高代码的可读性和可维护性，方便团队协作。

方案选择：基于 TypeScript 和 AST

目前，比较成熟的方案是基于 TypeScript 和 AST（Abstract Syntax Tree，抽象语法树）。

  • TypeScript: Vue 3 本身就是使用 TypeScript 构建的，它提供了强大的类型系统，非常适合用来定义组件的 API 类型。

  • AST: AST 是源代码的抽象语法结构的树状表示。通过解析 TypeScript 源代码生成 AST，我们可以方便地提取出组件的 props、events、slots 等信息，并生成相应的类型定义。

实现步骤：从代码到类型定义

接下来，我们详细介绍如何使用 TypeScript 和 AST 实现 Vue 组件 API 类型的自动生成。

1. 安装必要的依赖

首先，我们需要安装一些必要的依赖：

npm install typescript vue @vue/compiler-sfc ts-morph --save-dev
  • typescript: TypeScript 编译器。
  • vue: Vue 框架。
  • @vue/compiler-sfc: Vue 单文件组件编译器，用于解析 .vue 文件。
  • ts-morph: 一个 TypeScript 编译器 API 的封装库，提供了更友好的接口来操作 AST。

2. 解析 Vue 单文件组件

我们需要解析 .vue 文件，提取出 <script> 标签中的 TypeScript 代码。@vue/compiler-sfc 提供了 parse 函数来完成这个任务。

import { parse } from '@vue/compiler-sfc';
import * as fs from 'fs';

function parseVueFile(filePath: string): string | null {
  const source = fs.readFileSync(filePath, 'utf-8');
  const { descriptor, errors } = parse(source);

  if (errors.length) {
    console.error('Failed to parse Vue file:', errors);
    return null;
  }

  const scriptContent = descriptor.scriptSetup?.content || descriptor.script?.content;

  return scriptContent || null;
}

const vueFilePath = './src/components/MyComponent.vue'; // 替换为你的 Vue 文件路径
const scriptContent = parseVueFile(vueFilePath);

if (scriptContent) {
  console.log('Extracted script content:', scriptContent);
} else {
  console.error('No script content found in Vue file.');
}

3. 使用 ts-morph 分析 TypeScript 代码

接下来，我们使用 ts-morph 来分析提取出的 TypeScript 代码，并生成 AST。

import { Project } from 'ts-morph';

function analyzeTypeScriptCode(code: string): Project {
  const project = new Project({
    compilerOptions: {
      declaration: true, // 生成 .d.ts 文件
    },
    useInMemoryFileSystem: true, // 不写入磁盘，使用内存文件系统
  });

  project.createSourceFile('temp.ts', code);
  return project;
}

if (scriptContent) {
  const project = analyzeTypeScriptCode(scriptContent);
  const sourceFile = project.getSourceFile('temp.ts');

  if (sourceFile) {
    // 在这里对 sourceFile 进行进一步的分析
    console.log('TypeScript project created successfully.');
  } else {
    console.error('Failed to create TypeScript source file.');
  }
}

4. 提取 Props 类型

Vue 组件的 props 可以通过 defineProps 宏定义或者 props 选项来声明。我们需要提取出这些 props 的类型信息。

  • defineProps 宏定义: 如果使用了 <script setup> 语法，props 通常通过 defineProps 宏定义来声明。我们可以找到 defineProps 的调用，并提取其参数类型。
import { Node, SyntaxKind, Type } from 'ts-morph';

function extractPropsTypeFromDefineProps(sourceFile: any): Type | null {
  const definePropsCall = sourceFile.getDescendants()
    .find(node => Node.isCallExpression(node) && node.getExpression().getText() === 'defineProps');

  if (definePropsCall && Node.isCallExpression(definePropsCall)) {
    const argument = definePropsCall.getArguments()[0];

    if (argument) {
      return argument.getType();
    }
  }

  return null;
}

if (scriptContent) {
  const project = analyzeTypeScriptCode(scriptContent);
  const sourceFile = project.getSourceFile('temp.ts');

  if (sourceFile) {
    const propsType = extractPropsTypeFromDefineProps(sourceFile);
    if (propsType) {
      console.log("Props Type:", propsType.getText());
      // 你可以进一步处理 propsType，提取出每个 prop 的名称、类型和描述
    } else {
      console.log("No props defined using defineProps.");
    }
  } else {
    console.error('Failed to create TypeScript source file.');
  }
}
  • props 选项: 在传统的组件定义中，props 可以通过 props 选项来声明。我们可以找到 props 选项，并提取其类型信息。
import { Node, SyntaxKind, Type } from 'ts-morph';

function extractPropsTypeFromOptionsAPI(sourceFile: any): Type | null {
    const componentOptions = sourceFile.getDescendants()
        .find(node => Node.isObjectLiteralExpression(node)); // 找到组件选项对象

    if (componentOptions && Node.isObjectLiteralExpression(componentOptions)) {
        const propsProperty = componentOptions.getProperty("props"); // 查找名为 'props' 的属性

        if (propsProperty) {
            // 'props' 属性存在
            if (Node.isPropertyAssignment(propsProperty)) {
                // 属性赋值
                const initializer = propsProperty.getInitializer();

                if (Node.isObjectLiteralExpression(initializer)) {
                    // 'props' 是一个对象字面量
                    return initializer.getType(); // 返回 'props' 对象的类型
                } else if (Node.isArrayLiteralExpression(initializer)) {
                    // 如果是数组形式的 props，比如 ['propA', 'propB']
                    // 这种情况无法直接提取类型信息，需要手动处理或忽略
                    console.warn("Props defined as array is not supported for type extraction.");
                    return null;
                }
            } else if (Node.isMethodDeclaration(propsProperty)) {
                // 如果 'props' 是一个方法
                // 这种情况通常是使用了函数形式的 props 验证，需要手动处理或忽略
                console.warn("Function-based props validation is not supported for type extraction.");
                return null;
            }
        }
    }

    return null;
}

if (scriptContent) {
    const project = analyzeTypeScriptCode(scriptContent);
    const sourceFile = project.getSourceFile('temp.ts');

    if (sourceFile) {
        const propsType = extractPropsTypeFromOptionsAPI(sourceFile);
        if (propsType) {
            console.log("Props Type (Options API):", propsType.getText());
            // 你可以进一步处理 propsType，提取出每个 prop 的名称、类型和描述
        } else {
            console.log("No props defined using Options API.");
        }
    } else {
        console.error('Failed to create TypeScript source file.');
    }
}

5. 提取 Events 类型

Vue 组件可以通过 $emit 方法触发事件。我们可以通过分析 $emit 的调用，提取出事件的名称和参数类型。

import { Node, SyntaxKind, Type } from 'ts-morph';

interface EventInfo {
  name: string;
  argumentTypes: string[];
}

function extractEventsType(sourceFile: any): EventInfo[] {
  const emitCalls = sourceFile.getDescendants()
    .filter(node => Node.isCallExpression(node) &&
      Node.isPropertyAccessExpression(node.getExpression()) &&
      node.getExpression().getName() === '$emit');

  const events: EventInfo[] = [];

  emitCalls.forEach(call => {
    if (Node.isCallExpression(call)) {
      const args = call.getArguments();
      if (args.length > 0) {
        const eventName = args[0].getText().replace(/['"]/g, ''); // 去除引号
        const argumentTypes: string[] = [];

        for (let i = 1; i < args.length; i++) {
          argumentTypes.push(args[i].getType().getText());
        }

        events.push({
          name: eventName,
          argumentTypes: argumentTypes,
        });
      }
    }
  });

  return events;
}

if (scriptContent) {
  const project = analyzeTypeScriptCode(scriptContent);
  const sourceFile = project.getSourceFile('temp.ts');

  if (sourceFile) {
    const events = extractEventsType(sourceFile);
    if (events.length > 0) {
      console.log("Events:", events);
      // 你可以进一步处理 events，生成事件类型定义
    } else {
      console.log("No events emitted.");
    }
  } else {
    console.error('Failed to create TypeScript source file.');
  }
}

6. 提取 Slots 类型

Vue 组件可以定义 slots，允许父组件插入内容。我们可以通过分析 v-slot 指令的使用情况，提取出 slots 的名称和参数类型。 但是，v-slot 指令是在模板中使用的，因此我们需要分析 .vue 文件的 <template> 部分。这需要更复杂的 AST 分析，并且通常需要结合 Vue 的模板编译器。 一个简化的方式是，如果组件使用了 TypeScript 的 defineExpose 宏，并且暴露了对 slot 内容的操作，我们可能可以间接推断出 slot 的类型。

// 示例，需要根据实际情况进行调整和完善
// 这只是一个占位符，实际提取 Slot 类型需要分析模板内容或 defineExpose 的用法

function extractSlotsType(sourceFile: any): any {
    // 实际的 slot 类型提取逻辑会很复杂，需要分析模板内容
    // 这是一个简化示例，返回一个占位符
    return {
        default: {
            type: 'any',
            description: 'Default slot'
        }
    };
}

7. 生成类型定义文件

最后，我们将提取出的 props、events、slots 类型信息，生成 .d.ts 类型定义文件。

function generateDTSFile(
  componentName: string,
  propsType: string | null,
  events: EventInfo[],
  slots: any
): string {
  let dtsContent = `import type { DefineComponent } from 'vue';nn`;

  if (propsType) {
    dtsContent += `export interface ${componentName}Props extends ${propsType} {}nn`;
  }

  if (events.length > 0) {
    dtsContent += `export interface ${componentName}Emits {n`;
    events.forEach(event => {
      const argumentTypes = event.argumentTypes.join(', ');
      dtsContent += `  (e: '${event.name}', ${argumentTypes}): void;n`;
    });
    dtsContent += `}nn`;
  }

  dtsContent += `declare const ${componentName}: DefineComponent<${propsType ? `${componentName}Props` : 'object'}, {}, any>;n`;
  dtsContent += `export default ${componentName};n`;

  return dtsContent;
}

// 示例用法
if (scriptContent) {
  const project = analyzeTypeScriptCode(scriptContent);
  const sourceFile = project.getSourceFile('temp.ts');

  if (sourceFile) {
    const propsType = extractPropsTypeFromDefineProps(sourceFile)?.getText() || null;
    const events = extractEventsType(sourceFile);
    const slots = extractSlotsType(sourceFile); // 提取 Slots 类型

    const componentName = 'MyComponent'; // 替换为你的组件名称
    const dtsContent = generateDTSFile(componentName, propsType, events, slots);

    fs.writeFileSync(`./dist/${componentName}.d.ts`, dtsContent, 'utf-8');
    console.log(`Generated ${componentName}.d.ts`);
  } else {
    console.error('Failed to create TypeScript source file.');
  }
}

代码示例

以下是一个完整的示例代码，演示了如何从 Vue 单文件组件中提取 props 类型并生成 .d.ts 文件：

import { parse } from '@vue/compiler-sfc';
import * as fs from 'fs';
import { Project, Node, SyntaxKind, Type } from 'ts-morph';

interface EventInfo {
  name: string;
  argumentTypes: string[];
}

function parseVueFile(filePath: string): string | null {
  const source = fs.readFileSync(filePath, 'utf-8');
  const { descriptor, errors } = parse(source);

  if (errors.length) {
    console.error('Failed to parse Vue file:', errors);
    return null;
  }

  const scriptContent = descriptor.scriptSetup?.content || descriptor.script?.content;

  return scriptContent || null;
}

function analyzeTypeScriptCode(code: string): Project {
  const project = new Project({
    compilerOptions: {
      declaration: true, // 生成 .d.ts 文件
    },
    useInMemoryFileSystem: true, // 不写入磁盘，使用内存文件系统
  });

  project.createSourceFile('temp.ts', code);
  return project;
}

function extractPropsTypeFromDefineProps(sourceFile: any): Type | null {
  const definePropsCall = sourceFile.getDescendants()
    .find(node => Node.isCallExpression(node) && node.getExpression().getText() === 'defineProps');

  if (definePropsCall && Node.isCallExpression(definePropsCall)) {
    const argument = definePropsCall.getArguments()[0];

    if (argument) {
      return argument.getType();
    }
  }

  return null;
}

function extractEventsType(sourceFile: any): EventInfo[] {
  const emitCalls = sourceFile.getDescendants()
    .filter(node => Node.isCallExpression(node) &&
      Node.isPropertyAccessExpression(node.getExpression()) &&
      node.getExpression().getName() === '$emit');

  const events: EventInfo[] = [];

  emitCalls.forEach(call => {
    if (Node.isCallExpression(call)) {
      const args = call.getArguments();
      if (args.length > 0) {
        const eventName = args[0].getText().replace(/['"]/g, ''); // 去除引号
        const argumentTypes: string[] = [];

        for (let i = 1; i < args.length; i++) {
          argumentTypes.push(args[i].getType().getText());
        }

        events.push({
          name: eventName,
          argumentTypes: argumentTypes,
        });
      }
    }
  });

  return events;
}

function generateDTSFile(
  componentName: string,
  propsType: string | null,
  events: EventInfo[],
  slots: any
): string {
  let dtsContent = `import type { DefineComponent } from 'vue';nn`;

  if (propsType) {
    dtsContent += `export interface ${componentName}Props extends ${propsType} {}nn`;
  }

  if (events.length > 0) {
    dtsContent += `export interface ${componentName}Emits {n`;
    events.forEach(event => {
      const argumentTypes = event.argumentTypes.join(', ');
      dtsContent += `  (e: '${event.name}', ${argumentTypes}): void;n`;
    });
    dtsContent += `}nn`;
  }

  dtsContent += `declare const ${componentName}: DefineComponent<${propsType ? `${componentName}Props` : 'object'}, {}, any>;n`;
  dtsContent += `export default ${componentName};n`;

  return dtsContent;
}

// 示例用法
const vueFilePath = './src/components/MyComponent.vue'; // 替换为你的 Vue 文件路径
const scriptContent = parseVueFile(vueFilePath);

if (scriptContent) {
  const project = analyzeTypeScriptCode(scriptContent);
  const sourceFile = project.getSourceFile('temp.ts');

  if (sourceFile) {
    const propsType = extractPropsTypeFromDefineProps(sourceFile)?.getText() || null;
    const events = extractEventsType(sourceFile);
    const slots = {}; // 提取 Slots 类型

    const componentName = 'MyComponent'; // 替换为你的组件名称
    const dtsContent = generateDTSFile(componentName, propsType, events, slots);

    fs.writeFileSync(`./dist/${componentName}.d.ts`, dtsContent, 'utf-8');
    console.log(`Generated ${componentName}.d.ts`);
  } else {
    console.error('Failed to create TypeScript source file.');
  }
}

优缺点分析

特性 优点 缺点
自动化程度 高，可以自动提取类型信息，减少手动维护的工作量。 需要编写代码来实现类型提取逻辑，对于复杂的组件可能需要更复杂的 AST 分析。
准确性 高，可以保证类型定义与代码保持同步。 对于一些特殊情况，可能无法准确提取类型信息，例如使用了复杂的类型推断或者动态类型。
易用性 可以集成到构建流程中，自动生成类型定义文件。 需要一定的 TypeScript 和 AST 知识。
可维护性 可以提高代码的可读性和可维护性。 如果类型提取逻辑过于复杂，可能会降低代码的可维护性。

未来发展方向

  • 更智能的类型推断: 利用机器学习等技术，可以实现更智能的类型推断，提高类型提取的准确性。

  • 更全面的 API 支持: 可以支持提取 Vue 组件的更多 API 信息，例如 methods、computed properties 等。

  • 更好的集成: 可以与现有的 Vue 开发工具集成，提供更便捷的类型生成和管理功能。

使用工具简化流程

虽然上述步骤展示了从头开始实现自动类型提取的原理，但在实际项目中，我们可以利用一些现有的工具来简化这个流程。 诸如 vue-docgen-cli 这样的工具，已经封装了大部分的 AST 解析和类型提取逻辑，我们只需要简单配置即可使用。

总结

自动生成 Vue 组件 API 类型是一个非常有价值的技术，可以显著提高开发效率和代码质量。通过 TypeScript 和 AST，我们可以从源代码中提取出 props、events、slots 等信息，并生成相应的类型定义文件。 虽然实现过程可能比较复杂，但它可以帮助我们更好地管理 Vue 组件的 API，并提高代码的可维护性。

希望今天的分享对大家有所帮助！

更多IT精英技术系列讲座，到智猿学院

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注