TypeScript Compiler API：如何在构造函数与属性前添加注释

嘿，看来你在TypeScript Compiler API的注释添加功能上卡壳在构造函数和属性声明了——我之前也踩过类似的坑，给你分享下解决思路和可落地的代码！

首先得明确TS Compiler API里对应这两个实体的节点类型：构造函数是ConstructorDeclaration，类属性是PropertyDeclaration。之前没成功大概率是节点识别或者注释添加的方式不对，下面直接上方案：

1. 核心转换逻辑（Transformer实现） #

用官方推荐的Transformer模式处理AST，确保注释被正确插入到目标节点的前置位置：

import * as ts from 'typescript';

// 封装生成JSDoc注释的工具函数
function generateJSDoc(text: string): string {
  // 返回JSDoc内部的内容，addSyntheticLeadingComment会自动包裹成/** ... */格式
  return `* ${text}\n `;
}

// 自定义转换器
const commentTransformer: ts.TransformerFactory<ts.SourceFile> = (context) => {
  const visitor: ts.Visitor = (node) => {
    // 处理构造函数
    if (ts.isConstructorDeclaration(node)) {
      return ts.addSyntheticLeadingComment(
        node,
        ts.SyntaxKind.MultiLineCommentTrivia,
        generateJSDoc('自动生成：类构造函数'),
        true // 注释后换行，保证格式整洁
      );
    }

    // 处理类属性声明
    if (ts.isPropertyDeclaration(node)) {
      const propName = node.name.getText();
      return ts.addSyntheticLeadingComment(
        node,
        ts.SyntaxKind.MultiLineCommentTrivia,
        generateJSDoc(`自动生成：类属性 ${propName}`),
        true
      );
    }

    // 保留你已实现的其他节点处理逻辑（函数声明、类方法等）
    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
      const funcName = node.name?.getText() || '匿名函数';
      return ts.addSyntheticLeadingComment(
        node,
        ts.SyntaxKind.MultiLineCommentTrivia,
        generateJSDoc(`自动生成：${ts.isMethodDeclaration(node) ? '类方法' : '函数'} ${funcName}`),
        true
      );
    }

    // 递归遍历所有子节点，别遗漏类内部的元素
    return ts.visitEachChild(node, visitor, context);
  };

  return (sourceFile) => ts.visitNode(sourceFile, visitor);
};

2. 集成到编译流程 #

把转换器加入TS编译的before阶段（在TS自身转换前处理AST）：

// 初始化TS Program
const inputFiles = ['your-target-file.ts'];
const program = ts.createProgram(inputFiles, {
  target: ts.ScriptTarget.ESNext,
  module: ts.ModuleKind.CommonJS
});

// 执行转换并输出结果
const emitResult = program.emit(undefined, undefined, undefined, undefined, {
  transformers: {
    before: [commentTransformer]
  }
});

// 检查转换错误
if (emitResult.emitSkipped) {
  console.error('转换失败，错误信息：');
  program.getDiagnostics().forEach(diag => console.error(diag.messageText));
} else {
  console.log('转换完成，注释已成功添加！');
}

3. 关键注意事项 #

• 节点识别要精准：别依赖ts.isFunctionLike(node)覆盖构造函数——虽然构造函数属于FunctionLike，但如果你的逻辑有额外过滤，很容易漏掉。直接用ts.isConstructorDeclaration更稳妥。
• 用官方API添加注释：别手动修改节点的leadingComments属性（它是只读的），必须用ts.addSyntheticLeadingComment，它会自动处理注释与节点的位置关系，避免格式混乱。
• 递归遍历不能少：类内部的构造函数和属性是类节点的子节点，一定要用ts.visitEachChild递归遍历，否则会跳过这些节点。

效果示例 #

输入代码：

class Product {
  sku: string;
  price: number;

  constructor(sku: string, price: number) {
    this.sku = sku;
    this.price = price;
  }

  getPrice() {
    return this.price;
  }
}

转换后输出：

class Product {
  /** 自动生成：类属性 sku */
  sku: string;
  /** 自动生成：类属性 price */
  price: number;

  /** 自动生成：类构造函数 */
  constructor(sku: string, price: number) {
    this.sku = sku;
    this.price = price;
  }

  /** 自动生成：类方法 getPrice */
  getPrice() {
    return this.price;
  }
}

内容的提问来源于stack exchange，提问作者Radu Szasz