Babel自動生成Attribute文檔實(shí)現(xiàn)詳解

更新時(shí)間：2022年11月03日 16:36:16 作者：小鑫同學(xué)

這篇文章主要為大家介紹了Babel自動生成Attribute文檔實(shí)現(xiàn)示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪

1. 前言

利用Babel自動解析源碼屬性上的注釋生成對應(yīng)Markdown文檔，這個(gè)場景的應(yīng)用主要包括在組件庫文檔對組件屬性的介紹中，這一篇就通過編寫一個(gè)Babel插件來實(shí)現(xiàn)這個(gè)功能~

2. 開發(fā)自動生成屬性文檔插件

2.1 生成Babel插件模板：

2.1.1 創(chuàng)建babel-plugin-auto-attr-doc文件夾；
2.1.2 安裝npm i -g yo generator-babel-plugin-x；
2.1.3 在新建目錄下執(zhí)行 yo babel-plugin-x:v7-ts；

生成的插件模板如下：

babel-plugin-auto-attr-doc  
├─ lib                      
│  └─ index.js              
├─ src                      
│  └─ index.ts              
├─ __tests__                
│  ├─ fixtures              
│  │  └─ example            
│  │     ├─ actual.ts       
│  │     └─ expected.ts     
│  └─ index.js              
├─ package-lock.json        
├─ package.json             
├─ README.md                
└─ tsconfig.json

2.2 轉(zhuǎn)換思路詳解：

轉(zhuǎn)換過程：利用Babel將Typescript腳本解析為AST，通過對AST結(jié)構(gòu)分析抽離對應(yīng)的注釋部分，再拼接Markdown表格風(fēng)格的語法；

源碼要求：**我們應(yīng)該將組件涉及到對外提供的屬性統(tǒng)一到對應(yīng)的types.ts文件管理，分別導(dǎo)出對應(yīng)的type字段；

注釋要求：**分別定義字段描述、類型、可選項(xiàng)、默認(rèn)值4項(xiàng)，由于解析器關(guān)鍵詞沖突原因，我們應(yīng)該盡量避免；

/**
  * @cDescribe 類型
  * @cType string
  * @cOptions 
  * @cDefault 
  */
 export type IType = "primary" | "success" | "warning" | "danger" | "info";
 /**
  * @cDescribe 圖標(biāo)組件
  * @cType string
  * @cOptions 
  * @cDefault 
  */
 export type IIcon = string;
 /**
  * @cDescribe 是否為樸素按鈕
  * @cType boolean
  * @cOptions 
  * @cDefault false
  */
 export type IPlain = boolean;

Markdown表格：**展示組件的屬性、描述、類型、可選值和默認(rèn)值這幾項(xiàng)；

2.3 單元測試用例：

準(zhǔn)備插件待解析源碼文件source-code.ts；
準(zhǔn)備實(shí)際生成MD后應(yīng)該顯示的內(nèi)容文件actual.md；

| 屬性名 | 說明 | 類型 | 可選值	| 默認(rèn)值 |
| ------ | ---- | ---- | ----- | ----- |
| type | 類型 | string |  |  |
| icon | 圖標(biāo)組件 | string |  |  |
| plain | 是否為樸素按鈕 | boolean |  | false |

調(diào)整單元測試文件讀取：

it(`should ${caseName.split("-").join(" ")}`, () => {
  const actualPath = path.join(fixtureDir, "source-code.ts");
  // 對源碼進(jìn)行加載解析
  transformFileSync(actualPath);
  // 讀取我們準(zhǔn)備好的md文件
  const actual = fs
    .readFileSync(path.join(fixtureDir, "actual.md"))
    .toString();
  // 讀取插件解析生成的md文件
  const expected = fs
    .readFileSync(path.join(fixtureDir, "api-doc.md"))
    .toString();
  // diff
  const diff = diffChars(actual, expected);
  diff.length > 1 && _print(diff);
  expect(diff.length).toBe(1);
});

2.4 AST分析詳解：

通過在AST explorer的源碼分析，我們在Babel中可以通過遍歷ExportNamedDeclaration（命名導(dǎo)出聲明）；
在leadingComments數(shù)組中可以取出所有注釋文本的集合，在Babel處理時(shí)我們需要依次處理每一塊注釋后增加標(biāo)記來避免重復(fù)處理；
在(path.node.declaration as t.TypeAlias).id.name中取屬性名稱；

將注釋文本通過doctrine模塊解析為對象后和屬性名合并對轉(zhuǎn)換Markdown所需要的所有數(shù)據(jù)~

2.5 插件開發(fā)過程：

2.5.1 定義Comment、ApiTable類型對象：

type Comment =
  | {
      describe: string;
      type: any;
      options?: any;
      default?: any;
    }
  | undefined;

type ApiTable = {
  attributeName: any;
  attributeDescribe: any;
  attributeType: any;
  attributeOptions: any;
  attributeDefault: any;
};

2.5.2 插件主邏輯分析：

pre：初始化存放apidoc容器，避免在存放時(shí)找不到容器；
visitor：解析源碼并獲取組織MD內(nèi)容數(shù)據(jù)暫存到apidoc中；
post：取出所有的apidoc內(nèi)容解析并輸出到本地文件中；

export default declare(
  (api: BabelAPI, options: Record<string, any>, dirname: string) => {
    api.assertVersion(7);
    return {
      name: "auto-attr-doc",
      pre(this: PluginPass, file: BabelFile) {
        this.set("api-doc", []);
      },
      visitor: {
        ExportNamedDeclaration(
          path: NodePath<t.ExportNamedDeclaration>,
          state: PluginPass
        ) {
          const apidoc = state.get("api-doc");
          // 處理 path.node.leadingComments 中未處理的數(shù)據(jù)后塞到apidoc中
          state.set("api-doc", apidoc);
        },
      },
      post(this: PluginPass, file: BabelFile) {
        const apidoc = this.get("api-doc");
        const output = generateMD(apidoc);
        const root = path.parse(file.opts.filename || "./").dir;
        fs.writeFileSync(path.join(root, "api-doc.md"), output, {
          encoding: "utf-8",
        });
      },
    } as PluginObj<PluginPass>;
  }
);

2.5.3 主邏輯實(shí)現(xiàn)：

leadingComments數(shù)組會在依次訪問ExportNamedDeclaration時(shí)不停增加，我們在處理掉當(dāng)前索引的對象后增加一個(gè)處理過的標(biāo)記skip，下次循環(huán)直接跳過；

通過parseComment函數(shù)解析后的對象可以通過tags數(shù)組獲取到所有的注釋項(xiàng)目，通過對應(yīng)的title得到對應(yīng)description內(nèi)容；

在往apidoc存放數(shù)據(jù)時(shí)需要處理屬性名稱符合一定的規(guī)則，并將apidoc對象存放到原容器中；

{
  ExportNamedDeclaration(
    path: NodePath<t.ExportNamedDeclaration>,
    state: PluginPass
  ) {
    const apidoc = state.get("api-doc");
    let _comment: Comment = undefined;
    path.node.leadingComments?.forEach((comment) => {
      if (!Reflect.has(comment, "skip")) {
        const tags = parseComment(comment.value)?.tags;
        _comment = {
          describe:
            tags?.find((v) => v.title === "cDescribe")?.description || "",
          type: tags?.find((v) => v.title === "cType")?.description || "",
          options:
            tags?.find((v) => v.title === "cOptions")?.description || "",
          default:
            tags?.find((v) => v.title === "cDefault")?.description || "",
        };
        Reflect.set(comment, "skip", true);
      }
    });
    apidoc.push({
      attributeName: (path.node.declaration as t.TypeAlias).id.name.substr(1).toLocaleLowerCase(),
      attributeDescribe: _comment!.describe,
      attributeType: _comment!.type,
      attributeOptions: _comment!.options,
      attributeDefault: _comment!.default,
    } as ApiTable);
    state.set("api-doc", apidoc);
  },
}

2.5.4 注釋解析函數(shù)：

const parseComment = (comment: string) => {
  if (!comment) {
    return;
  }
  return doctrine.parse(comment, {
    unwrap: true,
  });
};

2.5.5 Markdown表格拼裝：

const generateMD = (apidoc: Array<ApiTable>) => {
  let raw = `| 屬性名 | 說明 | 類型 | 可選值	| 默認(rèn)值 |\n| ------ | ---- | ---- | ----- | ----- |\n`;
  apidoc.forEach((item) => {
    raw += `| ${item.attributeName} | ${item.attributeDescribe} | ${item.attributeType} | ${item.attributeOptions} | ${item.attributeDefault} |\n`;
  });
  return raw;
};