前端框架文档新思路：基于源码解析的自动化方案

项目背景

最近我们团队自研了一个基于 React 的 H5 前端框架，领导让我来负责编写框架的使用文档。我选择了 dumi 来搭建文档站点，大部分内容都是手动写 Markdown 来介绍各种功能，包括：初始化、目录结构、生命周期、状态管理、插件系统 等等。
框架里有个很重要的子包，主要负责多个 App 的桥接能力，深度集成了各端环境的监测和桥接逻辑。这个子包对外提供了一个 App 实例对象，里面封装了很多原生能力，比如： 设置导航栏、录音、保存图片到相册 等
这些 API 代码格式都比较统一，领导希望避免在框架源码和文档里重复定义相同的接口，最好能直接从源代码自动生成文档内容。需要提取的信息包括：API支持的App版本、功能描述、开发状态、使用方式，如果是函数的话还要有参数说明和返回值说明。
我的解决方案

经过一番思考，我想到了一个方案：
核心思路：在不改动源代码逻辑的前提下，通过增加注释信息来补充文档需要的元数据
具体实现路径：

• 定义一套规范的注释标签
  
• 编写解析脚本提取信息，生成 JSON 文件
  
• 在文档项目中读取 JSON，动态渲染成 API 文档
  

定义注释规范

我定义了一系列标准的注释标签：

• @appVersion —— 支持该API的App版本
  
• @description —— API的功能描述
  
• @apiType —— API类型，默认是函数，可选property（属性）和function（函数）
  
• @usage —— 使用示例
  
• @param —— 函数参数说明（只有函数类型需要）
  
• @returns —— 函数返回值说明（只有函数类型需要）
  
• @status —— 发布状态
  

在实际代码中这样使用，完全不会影响原来的业务逻辑：

1. const app = {
2.   /**
3.    * @appVersion 1.0.0
4.    * @description 判断设备类型
5.    * @apiType property
6.    * @usage app.platform // notInApp | ios | android | HarmonyOS
7.    * @status 已上线
8.    */
9.    platform: getPlatform(),
10.    
11.    /**
12.    * @appVersion 1.0.6
13.    * @description 注册事件监听
14.    * @param {Object} options - 配置选项
15.    * @param {string} options.title - 事件名称
16.    * @param {Function} options.callback - 注册事件时的处理函数逻辑
17.    * @param {Function} options.onSuccess - 设置成功的回调函数（可选）
18.    * @param {Function} options.onFail - 设置失败的回调函数（可选）
19.    * @param {Function} options.onComplete - 无论成功失败都会执行的回调函数（可选）
20.    * @usage app.monitor({ eventName: 'onOpenPage', callback: (data)=>{ console.log('端上push消息', data ) } })
21.    * @returns {String} id - 绑定事件的id
22.    * @status 已上线
23.    */
24.         monitor: ({ onSuccess, onFail, onComplete, eventName = "", callback = () => { } }) => {
25.                 let _id = uuid();
26.                 // 业务代码省略
27.                 return _id;
28.         },
29. }

复制代码

解析脚本

接下来要写一个解析脚本，把注释内容提取成键值对格式，主要用正则表达式来解析注释：

1. const fs = require('fs');
2. const path = require('path');
4. /**
5. * 解析参数或返回值标签
6. * @param {string} content - 标签内容
7. * @param {string} type - 类型 ('param' 或 'returns')
8. * @returns {Object} 解析后的参数或返回值对象
9. */
10. function parseParamOrReturn(content, type = 'param') {
11.   const match = content.match(/{([^}]+)}\s+(\w+)(?:\.(\w+))?\s*-?\s*(.*)/);
12.   if (!match) return null;
14.   const paramType = match[1];
15.   const parentName = match[2];
16.   const childName = match[3];
17.   const description = match[4].trim();
18.   const isParam = type === 'param';
20.   if (childName) {
21.     // 嵌套参数或返回值 (options.title 或 data.result 格式)
22.     return {
23.       name: parentName,
24.       type: 'Object',
25.       description: isParam ? `${parentName} 配置对象` : `${parentName} 返回对象`,
26.       required: isParam ? true : undefined,
27.       children: [{
28.         name: childName,
29.         type: paramType,
30.         description: description,
31.         required: isParam ? (!paramType.includes('?') && !description.includes('可选')) : undefined
32.       }]
33.     };
34.   } else {
35.     // 普通参数或返回值
36.     return {
37.       name: parentName,
38.       type: paramType,
39.       description: description,
40.       required: isParam ? (!paramType.includes('?') && !description.includes('可选')) : undefined
41.     };
42.   }
43. }
45. /**
46. * 合并嵌套对象
47. * @param {Array} items - 参数或返回值数组
48. * @returns {Array} 合并后的数组
49. */
50. function mergeNestedItems(items) {
51.   const merged = {};
53.   items.forEach(item => {
54.     if (item.children) {
55.       // 嵌套对象
56.       if (!merged[item.name]) {
57.         merged[item.name] = { ...item };
58.       } else {
59.         // 合并子元素
60.         if (!merged[item.name].children) merged[item.name].children = [];
61.         merged[item.name].children.push(...item.children);
62.       }
63.     } else {
64.       // 普通参数
65.       if (!merged[item.name]) {
66.         merged[item.name] = item;
67.       }
68.     }
69.   });
71.   return Object.values(merged);
72. }
74. /**
75. * 保存标签内容到注解对象
76. */
77. function saveTagContent(annotation, tag, content) {
78.   // 确保 parameters 和 returns 数组存在
79.   if (!annotation.parameters) annotation.parameters = [];
80.   if (!annotation.returns) annotation.returns = [];
82.   switch (tag) {
83.     case 'appVersion':
84.       annotation.appVersion = content;
85.       break;
86.     case 'sxzVersion':
87.       annotation.sxzVersion = content;
88.       break;
89.     case 'mddVersion':
90.       annotation.mddVersion = content;
91.       break;
92.     case 'description':
93.       annotation.description = content;
94.       break;
95.     case 'status':
96.       annotation.status = content;
97.       break;
98.     case 'usage':
99.       annotation.usage = content.trim();
100.       break;
101.     case 'apiType':
102.       // 解析类型：property 或 method
103.       annotation.type = content.toLowerCase();
104.       break;
105.     case 'param':
106.       const param = parseParamOrReturn(content, 'param');
107.       if (param) {
108.         annotation.parameters.push(param);
109.         // 合并嵌套对象
110.         annotation.parameters = mergeNestedItems(annotation.parameters);
111.       }
112.       break;
113.     case 'returns':
114.       const returnItem = parseParamOrReturn(content, 'returns');
115.       if (returnItem) {
116.         annotation.returns.push(returnItem);
117.         // 合并嵌套对象
118.         annotation.returns = mergeNestedItems(annotation.returns);
119.       }
120.       break;
121.   }
122. }
124. /**
125. * 解析 JSDoc 注释中的注解信息 - 逐行解析
126. */
127. function parseJSDocAnnotation(comment) {
128.   if (!comment) return null;
130.   const annotation = {};
132.   // 按行分割注释
133.   const lines = comment.split('\n');
134.   
135.   let currentTag = '';
136.   let currentContent = '';
138.   for (const line of lines) {
139.     // 清理行内容，移除 * 和首尾空格，但保留内部的换行意图
140.     const cleanLine = line.replace(/^\s*\*\s*/, '').trimRight();
141.    
142.     // 跳过空行和注释开始结束标记
143.     if (!cleanLine || cleanLine === '/' || cleanLine === '*/') continue;
144.    
145.     // 检测标签开始
146.     const tagMatch = cleanLine.match(/^@(\w+)\s*(.*)$/);
147.     if (tagMatch) {
148.       // 保存前一个标签的内容
149.       if (currentTag) {
150.         saveTagContent(annotation, currentTag, currentContent);
151.       }
152.       
153.       // 开始新标签
154.       currentTag = tagMatch[1];
155.       currentContent = tagMatch[2];
156.     } else if (currentTag) {
157.       // 继续当前标签的内容，但保留换行
158.       // 对于 @usage 标签，我们保留原始格式
159.       if (currentTag === 'usage') {
160.         currentContent += '\n' + cleanLine;
161.       } else {
162.         currentContent += ' ' + cleanLine;
163.       }
164.     }
165.   }
166.   
167.   // 保存最后一个标签的内容
168.   if (currentTag) {
169.     saveTagContent(annotation, currentTag, currentContent);
170.   }
172.   // 确保 parameters 和 returns 数组存在（即使为空）
173.   if (!annotation.parameters) annotation.parameters = [];
174.   if (!annotation.returns) annotation.returns = [];
176.   return Object.keys(annotation).length > 0 ? annotation : null;
177. }
179. /**
180. * 使用 @apiType 标签指定类型
181. */
182. function extractAnnotationsFromSource(sourceCode) {
183.   const annotations = { properties: {}, methods: {} };
185.   // 使用更简单的逻辑：按行分析
186.   const lines = sourceCode.split('\n');
188.   for (let i = 0; i < lines.length; i++) {
189.     const line = lines[i].trim();
191.     // 检测 JSDoc 注释开始
192.     if (line.startsWith('/**')) {
193.       let jsdocContent = line + '\n';
194.       let j = i + 1;
196.       // 收集完整的 JSDoc 注释
197.       while (j < lines.length && !lines[j].trim().startsWith('*/')) {
198.         jsdocContent += lines[j] + '\n';
199.         j++;
200.       }
202.       if (j < lines.length) {
203.         jsdocContent += lines[j] + '\n'; // 包含结束的 */
205.         // 查找注释后面的代码行
206.         for (let k = j + 1; k < lines.length; k++) {
207.           const codeLine = lines[k].trim();
208.           if (codeLine && !codeLine.startsWith('//') && !codeLine.startsWith('/*')) {
209.             // 解析注解
210.             const annotation = parseJSDocAnnotation(jsdocContent);
211.             if (annotation) {
212.               // 从注解中获取类型（property 或 method）
213.               let itemType = annotation.type;
214.               let name = null;
216.               // 如果没有明确指定类型，默认设为 method
217.               if (!itemType) {
218.                 itemType = 'method';
219.               }
221.               // 提取名称
222.               const nameMatch = codeLine.match(/^(\w+)\s*[:=]/);
223.               if (nameMatch) {
224.                 name = nameMatch[1];
225.               } else {
226.                 // 如果没有匹配到名称，尝试其他模式
227.                 const funcMatch = codeLine.match(/^(?:async\s+)?(\w+)\s*\(/);
228.                 if (funcMatch) {
229.                   name = funcMatch[1];
230.                 }
231.               }
233.               if (name) {
234.                 if (itemType === 'property') {
235.                   annotations.properties[name] = annotation;
236.                 } else if (itemType === 'method') {
237.                   annotations.methods[name] = annotation;
238.                 } else {
239.                   console.warn(`未知的类型: ${itemType}，名称: ${name}`);
240.                 }
241.               } else {
242.                 console.warn(`无法提取名称: ${codeLine.substring(0, 50)}`);
243.               }
244.             }
245.             break;
246.           }
247.         }
249.         i = j; // 跳过已处理的行
250.       }
251.     }
252.   }
254.   return annotations;
255. }
257. /**
258. * 从文件提取注解
259. */
260. function extractAnnotationsFromFile(filePath) {
261.   if (!fs.existsSync(filePath)) {
262.     console.error('文件不存在:', filePath);
263.     return { properties: {}, methods: {} };
264.   }
266.   const sourceCode = fs.readFileSync(filePath, 'utf-8');
267.   return extractAnnotationsFromSource(sourceCode);
268. }
270. /**
271. * 提取所有文件的注解
272. */
273. function extractAllAnnotations(filePaths) {
274.   const allAnnotations = {};
276.   filePaths.forEach(filePath => {
277.     if (fs.existsSync(filePath)) {
278.       const fileName = path.basename(filePath, '.js');
279.       console.log(`\n=== 处理文件: ${fileName} ===`);
281.       const annotations = extractAnnotationsFromFile(filePath);
283.       if (Object.keys(annotations.properties).length > 0 ||
284.         Object.keys(annotations.methods).length > 0) {
285.         allAnnotations[fileName] = {
286.           fileName,
287.           ...annotations
288.         };
289.       }
290.     }
291.   });
293.   return allAnnotations;
294. }
296. module.exports = {
297.   parseJSDocAnnotation,
298.   extractAnnotationsFromSource,
299.   extractAnnotationsFromFile,
300.   extractAllAnnotations
301. };

复制代码

集成到构建流程

然后创建一个脚本，指定要解析的源文件，把生成的 JSON 文件 输出到 build 目录里：

1. const { extractAllAnnotations } = require('./jsdoc-annotations');
2. const fs = require('fs');
3. const path = require('path');
5. /**
6. * 主函数 - 提取注解并生成JSON文件
7. */
8. function main() {
9.   const filePaths = [
10.     path.join(process.cwd(), './app.js'),
11.     path.join(process.cwd(), './xxx.js'),
12.     path.join(process.cwd(), './yyy.js'),
13.   ].filter(fs.existsSync);
15.   if (filePaths.length === 0) {
16.     console.error('未找到任何文件，请检查文件路径');
17.     return;
18.   }
20.   const annotations = extractAllAnnotations(filePaths);
21.   const outputPath = path.join(process.cwd(), './build/api-annotations.json');
23.   // 保存为JSON文件
24.   fs.writeFileSync(outputPath, JSON.stringify(annotations, null, 2));
25. }
27. main();

复制代码

在 package.json 里定义构建指令，确保 build 的时候自动运行解析脚本：

1. {
2.     "scripts": {
3.       "build:annotations": "node scripts/extract-annotations.js",
4.       "build": "(cd template/main-app && npm run build) && npm run build:annotations"
5.   },
6. }

复制代码

执行效果：运行 npm run build 后，会生成结构化的 JSON 文件：

在文档中展示

框架项目和文档项目是分开的，把 JSON 文件生成到 build 文件夹，上传到服务器后提供固定访问路径。
有了结构化的 JSON 数据，生成文档页面就很简单了。在 dumi 文档里，把解析逻辑封装成组件：

1. ---
2. title: xxx
3. order: 2
4. ---
6. ```jsx
7. /**
8. * inline: true
9. */
10. import JsonToApi from '/components/jsonToApi/index.jsx';
12. export default () => <JsonToApi type="app" title="xxx" desc="App原生 api 对象"/>;
13. ```

复制代码

渲染效果如图所示

在将 JSON 数据解析并渲染到页面的过程中，有两个关键的技术点需要特别关注：
要点一：优雅的代码展示体验
直接使用 dangerouslySetInnerHTML 来呈现代码片段会导致页面样式简陋、缺乏可读性。我们需要借助代码高亮工具来提升展示效果，同时添加便捷的复制功能，让开发者能够轻松复用示例代码。
[code]import React from 'react';import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';const CodeBlock = ({  children,  language = 'javascript',  showLineNumbers = true,  highlightLines = []}) => {  const [copied, setCopied] = React.useState(false);  // 可靠的复制方法  const copyToClipboard = async (text) => {    try {      // 方法1: 使用现代 Clipboard API      if (navigator.clipboard && window.isSecureContext) {        await navigator.clipboard.writeText(text);        return true;      } else {        // 方法2: 使用传统的 document.execCommand（兼容性更好）        const textArea = document.createElement('textarea');        textArea.value = text;        textArea.style.position = 'fixed';        textArea.style.left = '-999999px';        textArea.style.top = '-999999px';        document.body.appendChild(textArea);        textArea.focus();        textArea.select();        const success = document.execCommand('copy');        document.body.removeChild(textArea);        return success;      }    } catch (err) {      console.error('复制失败:', err);      // 方法3: 备用方案 - 提示用户手动复制      prompt('请手动复制以下代码:', text);      return false;    }  };  const handleCopy = async () => {    const text = String(children).replace(/\n$/, '');    const success = await copyToClipboard(text);    if (success) {      setCopied(true);      setTimeout(() => setCopied(false), 2000);    }  };  return (          {/* 语言标签 */}              {language}                  {copied ? '✅ 已复制' : '
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

前排留名，哈哈哈