智能技术架构文档自动生成：保持文档与代码同步

智能技术架构文档自动生成：保持文档与代码同步

大家好，我是蔓蔓。做独立产品最大的感受之一是：文档永远是滞后于代码的。每次重构完一个模块，就面临更新 README、API 文档、架构图的庞大工作量。更糟糕的是，过三个月回来看，文档已经和实际代码对不上了。这次我设计了一套智能文档自动生成系统，让文档随代码一起演进。今天和大家分享这套方案。

一、文档与代码的"时序错位"问题

传统技术文档面临的核心矛盾是：代码的演化是持续的、高频的，而文档的更新是离散的、低优先级的。

文档失效的四个阶段

代码修改 → 文档过时但未察觉 → 新成员按文档开发踩坑 → 信任崩塌 → 文档被放弃

这种恶性循环的根源在于：文档的维护成本被低估了。以一个有 50 个 API 接口的后端项目为例：

二、自动化文档生成的系统架构

核心设计原则：凡是可以从代码推导的信息，就不应该由人来维护。

flowchart TB subgraph 代码源 C1[TypeScript 类型定义] C2[JSDoc 注释] C3[Prisma/Drizzle Schema] C4[OpenAPI/路由定义] C5[测试用例] C6[Git 提交历史] end subgraph 文档生成引擎 C1 --> E1[类型分析器] C2 --> E1 C3 --> E2[Schema 分析器] C4 --> E3[API 分析器] C5 --> E4[行为分析器] C6 --> E5[变更分析器] E1 --> M[合并与去重] E2 --> M E3 --> M E4 --> M E5 --> M end subgraph AI 处理层 M --> A1[架构意图推断] M --> A2[自然语言生成] M --> A3[图表自动绘制] M --> A4[变更摘要生成] end subgraph 输出 A1 --> O1[架构决策记录 ADR] A2 --> O2[API 文档<br/>组件文档] A3 --> O3[Mermaid 架构图] A4 --> O4[CHANGELOG<br/>迁移指南] end

类型驱动的 API 文档生成

// docs/generator/api-doc.ts import ts from 'typescript'; interface EndpointDoc { method: string; path: string; description: string; requestBody?: TypeDoc; queryParams?: Record<string, TypeDoc>; response: TypeDoc; errors: ErrorDoc[]; example?: string; } interface TypeDoc { type: string; description: string; required: boolean; properties?: Record<string, TypeDoc>; enum?: string[]; } function generateApiDocs(sourceFiles: string[]): EndpointDoc[] { const program = ts.createProgram(sourceFiles, { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, }); const endpoints: EndpointDoc[] = []; function visit(node: ts.Node, sourceFile: ts.SourceFile) { // 识别路由定义模式 if (ts.isCallExpression(node)) { const expr = node.expression; // 匹配 app.get('/api/users', handler) 模式 if ( ts.isPropertyAccessExpression(expr) && ['get', 'post', 'put', 'patch', 'delete'].includes(expr.name.text) ) { const method = expr.name.text.toUpperCase(); const pathArg = node.arguments[0]; const handlerArg = node.arguments[1]; if (ts.isStringLiteral(pathArg) && handlerArg) { const path = pathArg.text; const handlerType = program .getTypeChecker() .getTypeAtLocation(handlerArg); const doc = extractEndpointDoc( method, path, handlerType, program.getTypeChecker(), sourceFile ); endpoints.push(doc); } } } ts.forEachChild(node, (child) => visit(child, sourceFile)); } for (const sourceFile of sourceFiles) { visit(program.getSourceFile(sourceFile)!, sourceFile); } return endpoints; }

从 JSDoc 和类型推导生成文档描述

// 输入代码示例 /** * 获取用户文章列表 * @description 支持按状态和标签过滤，默认返回最近更新的 20 篇 * @param userId - 用户 ID * @param filters.status - 文章状态，可选 'published' | 'draft' * @param filters.page - 页码，从 1 开始 * @returns 分页的文章列表 * @throws {404} 用户不存在 * @throws {403} 无权访问该用户的文章 */ async function getUserPosts( userId: number, filters?: { status?: 'published' | 'draft'; page?: number; } ): Promise<PaginatedResponse<Post>> { // ... }

文档生成器可以从这些注释中提取出完整的 API 文档，包括参数说明、返回值类型和错误码。

踩坑：TypeScript AST 解析的边界情况与 JSDoc 缺失

在实际使用中，generateApiDocs有两个容易踩坑的边界情况：

第一，路由定义不总是app.get(path, handler)的形式。当项目使用路由注册表模式（如router.register('GET', '/api/users', handler)）或装饰器模式（如@Get('/api/users')）时，AST 解析器的isCallExpression匹配逻辑无法识别。解决方案是为每种路由注册模式编写独立的识别规则，或在项目中统一使用一种路由声明方式。

第二，缺少 JSDoc 时生成的文档只有类型信息而无语义描述。如果开发者没有为getUserPosts添加@description和@param注释，生成的文档将只包含参数名和类型（userId: number），缺少"用户 ID"这样的语义说明。这会让文档对新人毫无帮助。建议在 CI 中增加 JSDoc 覆盖率检查，对缺失注释的公共函数发出警告：

// docs/validator/jsdoc-coverage.ts function checkJSDocCoverage(sourceFiles: string[]): CoverageReport { const program = ts.createProgram(sourceFiles, { target: ts.ScriptTarget.ES2022 }); const missing: string[] = []; for (const file of sourceFiles) { const sf = program.getSourceFile(file)!; ts.forEachChild(sf, (node) => { if (ts.isFunctionDeclaration(node) && node.name) { const jsDoc = ts.getJSDocCommentsAndTags(node); if (jsDoc.length === 0 && isExported(node, sf)) { missing.push(`${file}: ${node.name.text}`); } } }); } return { total: 0, missing, coverage: 0 }; }

Mermaid 架构图的自动生成

// docs/generator/architecture-diagram.ts interface ModuleNode { name: string; dependencies: string[]; type: 'service' | 'component' | 'database' | 'external'; } function generateArchitectureDiagram(modules: ModuleNode[]): string { const lines: string[] = ['```mermaid', 'flowchart TB']; // 按类型分组 const services = modules.filter((m) => m.type === 'service'); const databases = modules.filter((m) => m.type === 'database'); const externals = modules.filter((m) => m.type === 'external'); // 生成子图 if (services.length > 0) { lines.push(' subgraph 业务服务'); services.forEach((s) => { lines.push(` ${s.name}[${s.name}]`); }); lines.push(' end'); } if (databases.length > 0) { lines.push(' subgraph 数据层'); databases.forEach((d) => { lines.push(` ${d.name}[(${d.name})]`); }); lines.push(' end'); } // 生成连接线 for (const mod of modules) { for (const dep of mod.dependencies) { lines.push(` ${mod.name} --> ${dep}`); } } lines.push('```'); return lines.join('\n'); }

三、AI 增强的架构意图推断

类型推导可以生成 API 文档，但架构决策背后的"为什么"（ADR）需要 AI 的推理能力。

基于 Git 历史的意图推断

// docs/generator/adr-generator.ts interface CommitContext { hash: string; message: string; files: string[]; diff: string; timestamp: string; } async function generateADR( commits: CommitContext[], currentArchitecture: string ): Promise<string> { const prompt = `你是一位技术架构分析师。请根据以下 Git 提交历史和当前代码架构，生成一份架构决策记录（ADR）。 ## 提交历史分析 ${commits.map(c => `- [${c.timestamp.slice(0, 10)}] ${c.message} 影响文件：${c.files.slice(0, 5).join(', ')}`).join('\n')} ## 当前架构 ${currentArchitecture} 请按以下格式生成 ADR： ### 标题 ### 背景与问题 ### 决策内容 ### 备选方案 ### 后果（正面和负面） `; const response = await callAI({ prompt }); return response; }

变更摘要的自动生成

// docs/generator/changelog.ts async function generateChangelog( fromRef: string, toRef: string ): Promise<string> { const commits = await getCommitsBetween(fromRef, toRef); // 按类型分组 const groups = { feat: [] as string[], fix: [] as string[], refactor: [] as string[], docs: [] as string[], breaking: [] as string[], }; for (const commit of commits) { const match = commit.message.match( /^(feat|fix|refactor|docs|chore)(?:\(.+\))?!?: (.+)/ ); if (match) { const [, type, desc] = match; const isBreaking = commit.message.includes('!'); if (isBreaking) { groups.breaking.push(desc); } else { groups[type as keyof typeof groups]?.push(desc); } } } // 使用 AI 整合为可读的变更说明 const prompt = `请将以下 Git 提交记录整合为结构化的 CHANGELOG： ## 新功能 ${groups.feat.map(f => `- ${f}`).join('\n')} ## 缺陷修复 ${groups.fix.map(f => `- ${f}`).join('\n')} ## Breaking Changes ${groups.breaking.map(b => `- ${b}`).join('\n')} 请为每个条目添加影响范围和迁移建议。`; return await callAI({ prompt }); }

四、文档与代码的持续同步机制

Git Hook 驱动的增量更新

#!/bin/sh # .git/hooks/pre-push — 每次 push 前自动更新文档 echo "正在检查文档同步状态..." # 检查是否有 API 变更但未更新文档 git diff --name-only origin/main | while read file; do case "$file" in src/routes/*.ts) # 路由文件变更，触发 API 文档重新生成 npx tsx scripts/generate-api-docs.ts ;; prisma/schema.prisma) # Schema 变更，触发数据库文档重新生成 npx tsx scripts/generate-schema-docs.ts ;; src/components/*/index.tsx) # 组件变更，触发组件文档重新生成 npx tsx scripts/generate-component-docs.ts ;; esac done # 自动提交文档变更 if [ -n "$(git diff --name-only docs/)" ]; then git add docs/ git commit -m "docs: 自动更新 API/Schema 文档 [skip ci]" fi

文档时效性检查

// docs/validator/staleness-check.ts interface DocumentState { path: string; lastGenerated: number; sourceFiles: string[]; currentHash: string; isStale: boolean; } async function checkStaleness(): Promise<DocumentState[]> { const docs = await loadDocumentManifest(); const results: DocumentState[] = []; for (const doc of docs) { // 计算源文件当前的哈希值 const currentHash = await hashFiles(doc.sourceFiles); const isStale = currentHash !== doc.currentHash; results.push({ ...doc, currentHash, isStale, lastGenerated: doc.lastGenerated, }); if (isStale) { console.warn( `⚠️ 文档已过期: ${doc.path}\n` + ` 最后生成: ${new Date(doc.lastGenerated).toISOString()}\n` + ` 变更文件: ${await findChangedFiles(doc.sourceFiles, doc.currentHash).then(r => r.join(', '))}` ); } } return results; } // 集成到 CI，过期文档的 PR 标记为警告 // 超过 7 天未更新的文档直接阻断 merge const MAX_STALE_DAYS = 7;

五、总结

智能技术文档自动生成的核心价值不是"完全替代人工"，而是"大幅降低维护文档的边际成本"。四个关键设计原则：

第一，代码即真相源。类型定义、路由声明、数据库 Schema 这些已经有严格格式的信息，不需要人工再次转录为文档。自动化生成消除了转录错误和同步延迟。

第二，AI 负责推理和表达。技术决策的"为什么"无法从代码自动推导，但 AI 可以基于代码变更、Git 历史和项目结构进行合理推断，生成可供审阅的初稿。

第三，CI 集成是持续同步的保障。将文档生成集成到 Git Hook 和 CI 流水线中，让文档更新成为提交代码的"副作用"，而非额外的工作项。

第四，时效性检查防止信任崩塌。定期检查文档的源文件哈希值，主动标记过期文档，比等待读者发现文档错误后再修复的代价小得多。

推荐实施路径：先从 API 文档的自动生成开始（ROI 最高），再扩展到 Schema 文档和 CHANGELOG，最后引入 AI 辅助的架构决策记录生成。

你的项目中文档维护情况如何？有没有试过自动生成的方案？欢迎在评论区交流～