技术文章

三年老鸟折腾文档工具的那些破事

晚上11点40，老二终于不闹腾了，打着小呼噜睡熟。我轻手轻脚地退出儿童房，顺手带上门，给自己泡了杯浓茶。自从当了两个娃的奶爸，咖啡是彻底戒了，怕晚上失眠，毕竟半夜要是娃醒了还得起来哄。

坐在电脑前，看着屏幕上密密麻麻的代码，我忍不住叹了口气。在公司待了三年多，业务逻辑闭着眼睛都能画出来，但技术成长总感觉遇到了天花板。最近大环境虽然卷得飞起，但我还是想换个环境，看看外面的机会。

打开文档准备更新简历，我发现了个致命问题：项目经验太干瘪了。这三年我主要负责C端活动页和后台管理系统，为了迎合现在前端卷交互的趋势，我搞了不少基于GSAP和Lottie的复杂动画，首屏加载性能也优化了一大波。但是！这些亮点全在代码和线上环境里，根本没有文档沉淀啊！

面试的时候，人家面试官问“你们核心组件库是怎么维护和迭代的”，我总不能说“靠老员工口口相传和脑子记”吧？平时产品经理天天催着上需求，测试小姐姐天天提一些“按钮在特定分辨率下点不动”的奇葩Bug，我哪有时间写文档？

不行，必须得搞个文档工具，把项目经验好好包装……哦不，是沉淀下来。

选型的纠结与妥协

说干就干。文档工具选型，Vue生态肯定首选 VitePress。这玩意儿启动快，热更新基本是秒级，对我这种只有半夜有一两个小时学习时间的奶爸来说，太友好了。要是选 Docusaurus，那冷启动速度能让我在等的时候去给娃换个尿布。

但问题来了，写文档是个极其反人类的事情。尤其是给那些祖传的、连注释都没有的业务组件写API文档。看着那个 ComplexFormGenerator 组件里密密麻麻的几十个 Props，我当时真的想砸电脑。

这时候，我的“左膀右臂”就该出场了。作为一个重度依赖AI辅助开发的程序员，没有 GitHub Copilot 和 通义千问，我估计连一行注释都憋不出来。

被AI“毒打”与反杀的日常

先说 Copilot。在 VSCode 里，我直接对着组件源码，让 Copilot 帮我补全 JSDoc 注释。讲真，这玩意儿写正则和基础类型推导简直神了，但遇到复杂的业务逻辑，它偶尔也会“幻觉”，给你生成一段看似合理实则狗屁不通的注释。

比如我们有个 DataGrid 组件，里面有个 renderCell 的插槽。Copilot 给我生成的注释是：“用于渲染单元格内容”。废话！我需要它告诉我这个插槽接收哪些参数，返回什么结构，以及有没有默认的回退内容！

这时候就得请出 通义千问 了。我习惯把组件源码和 Copilot 生成的半成品注释扔给通义千问，让它帮我“说人话”，并且按照标准的 API 文档格式输出。

这里分享个我摸索出来的 Prompt 技巧：千万别只说“帮我写文档”，你要给它设定角色和限制。

“你是一个资深前端架构师，请根据以下 Vue3 组件源码，提取 Props、Events、Slots。用 Markdown 表格形式输出，要求描述准确、通俗易懂。警告：绝对不要使用‘赋能、抓手、闭环’等互联网黑话，说点人类能听懂的技术语言！”

（被那种满篇“底层逻辑”的阿里味文档毒打过的痛，谁懂？）

自动化才是王道

光靠手动复制粘贴还是太慢，而且容易漏。我花了两个晚上，写了个 Node.js 脚本，结合 vue-docgen-api 解析组件 AST，再调用 AI 接口自动生成 Markdown 文档。

核心逻辑其实不复杂，主要是处理各种边界情况：

const fs = require('fs');
const path = require('path');
const { parse } = require('vue-docgen-api');
// 这里省略了通义千问 API 的封装，大家可以直接用官方 SDK

async function generateComponentDoc(componentPath) {
  try {
    // 1. 解析组件 AST，提取基础信息
    const docInfo = await parse(componentPath);
    
    // 2. 处理 <script setup> 语法下 defineExpose 丢失的问题
    // 这是一个大坑，vue-docgen-api 有时候解析不到暴露的方法
    const sourceCode = fs.readFileSync(componentPath, 'utf-8');
    const exposeRegex = /defineExpose\(\s*\{([^}]+)\}\s*\)/g;
    const match = exposeRegex.exec(sourceCode);
    if (match) {
      docInfo.exposedMethods = match[1].split(',').map(m => m.trim());
    }

    // 3. 构建 Prompt 扔给通义千问
    const prompt = `
      组件名称: ${docInfo.displayName}
      组件描述: ${docInfo.description || '无'}
      Props 列表: ${JSON.stringify(docInfo.props)}
      Events 列表: ${JSON.stringify(docInfo.events)}
      Slots 列表: ${JSON.stringify(docInfo.slots)}
      暴露方法: ${docInfo.exposedMethods ? docInfo.exposedMethods.join(', ') : '无'}
      
      请根据以上信息，生成一份标准的 Vue3 组件 API 文档。
      要求：
      1. 包含“基础用法”代码示例。
      2. Props、Events、Slots 使用 Markdown 表格展示。
      3. 语言通俗易懂，拒绝互联网黑话。
    `;

    // 4. 调用 AI 生成文档 (伪代码)
    const markdownContent = await callQwenAPI(prompt);
    
    // 5. 写入文件
    const outputPath = path.join(__dirname, `../docs/components/${docInfo.displayName}.md`);
    fs.writeFileSync(outputPath, markdownContent);
    console.log(`✅ 成功生成 ${docInfo.displayName} 文档`);
    
  } catch (error) {
    console.error(`❌ 生成文档失败: ${error.message}`);
  }
}

// 批量跑一下 src/components 下的所有组件
const componentsDir = path.join(__dirname, '../src/components');
fs.readdirSync(componentsDir).forEach(file => {
  if (file.endsWith('.vue')) {
    generateComponentDoc(path.join(componentsDir, file));
  }
});

跑这个脚本的时候，我盯着控制台，看着一个个 .md 文件生成，那种多巴胺分泌的感觉，简直比喝了三罐红牛还提神。

加点前端特有的“花活”

文档是生成了，但默认的 VitePress 主题太素了。既然我对前端动画和交互比较感兴趣，不加点“花活”怎么对得起我半夜熬的夜？

我利用 VitePress 的 enhanceApp.js 钩子，引入了 @vueuse/motion。给文档里的代码块加了个展开/收起的平滑过渡动画，给侧边栏的激活项加了个类似 macOS 的弹性跟随效果。

优化项	优化前体验	优化后体验	耗时
代码块折叠	瞬间出现，生硬	0.3s 缓动展开，带阴影渐变	2小时
侧边栏滚动	直接跳转	弹性滚动，高亮块平滑跟随	3小时
页面切换	白屏闪烁	骨架屏 + 淡入淡出	1.5小时

虽然这些交互在业务里不一定用得上，但在文档里展示出来，面试的时候给面试官演示一下，绝对是个加分项。毕竟，谁不喜欢丝滑的交互呢？

简历大改造

文档工具搞定后，最大的受益者其实是我的简历。

以前写项目经验，只能干巴巴地写“负责XX模块开发，使用Vue3+TS”。现在，我直接把文档里提炼出来的亮点复制过去，稍微润色一下：

• 主导搭建基于 VitePress 的组件库文档系统，编写 Node.js 脚本结合 AST 解析与 AI 大模型，实现组件 API 文档 80% 自动化生成，将文档维护成本降低 60%。
• 深度优化 C 端活动页交互体验，引入 GSAP 实现复杂路径动画，结合 requestAnimationFrame 和 IntersectionObserver 进行性能调优，使低端机型帧率稳定在 55fps 以上。
• 封装高扩展性的 DataGrid 虚拟滚动组件，支持十万级数据流畅渲染，通过 Web Worker 处理数据分片，彻底解决主线程阻塞导致的卡顿问题。

看着改造后的简历，我自己都忍不住想给自己投个简历。

奶爸程序员的碎碎念

折腾完这些，已经是凌晨2点了。我伸了个懒腰，骨头咔咔作响。

说实话，在公司待了三年，每天被业务需求推着走，很容易变成“代码机器”。但当你静下心来，用工具把杂乱的经验梳理成体系，看着那些原本只存在于脑子里的“坑”变成实实在在的文档和简历亮点时，那种成就感是无可替代的。

AI 工具确实强大，GitHub Copilot 帮我少写了无数行 boilerplate 代码，通义千问帮我理顺了无数篇文档。但它们终究只是工具，真正核心的，还是你对业务的理解、对技术的思考，以及那份在深夜里依然愿意折腾的心气儿。

不说了，老二好像翻身了，我得去瞅一眼。希望这篇文章能给同样在业务泥潭里挣扎、又想寻求突破的兄弟们一点启发。咱们顶峰相见，或者，面试场上见！