AI 生成前端架构文档：ADL 与 C4 模型自动绘制
一、架构文档的维护黑洞：代码先行，文档永远滞后
架构文档是团队共识的载体，但在实践中，它总是滞后于代码实现。一个典型的大型前端项目，架构文档的更新频率约为每季度一次，而代码架构的实际变更频率约为每周一次。这种滞后导致新加入团队的成员对架构的理解停留在过时文档描述的状态，做出的技术决策可能违反当前架构的真实约束。
更深的问题是架构文档的"失真"。手写文档倾向于描述设计意图而非实际实现。例如，文档写着"子应用通过事件总线通信"，但实际代码中仍有 20 处直接引用了全局状态。文档写着"所有 API 请求通过统一中间层"，但实际代码中有 15 处绕过中间层直接调用 fetch。这种设计与实现的偏差，在缺乏自动化验证的情况下几乎无法被发现。
AI 生成架构文档的核心思路是：从代码仓库和运行时数据中自动提取架构信息，结合 ADL（Architecture Description Language）和 C4 模型生成结构化文档，并持续验证文档描述与代码实现的一致性。
二、ADL 与 C4 模型：架构文档的结构化表达
ADL（Architecture Description Language）和 C4 模型是两种互补的架构描述方法。ADL 侧重于组件间的逻辑关系和约束规则，适合表达架构的"为什么"（设计意图）；C4 模型侧重于系统的分层视图和物理部署，适合表达架构的"是什么"（实际结构）。AI 生成架构文档需要结合两者：用代码分析推导 C4 视图，用设计意图文档补充 ADL 约束。
flowchart TB
A[代码仓库 + 运行时数据] –> B[架构信息提取层]
B –> B1[静态分析: 导入关系/依赖图/模块边界]
B –> B2[动态分析: 运行时调用链/数据流/组件嵌套]
B –> B3[配置分析: 构建配置/路由配置/部署配置]
B1 –> C1[C4 Context 视图: 系统与外部交互]
B2 –> C2[C4 Container 视图: 应用容器与部署单元]
B3 –> C3[C4 Component 视图: 内部组件与模块关系]
C1 –> D[ADL 约束层]
C2 –> D
C3 –> D
D –> D1[连接器规则: 子应用间通信方式约束]
D –> D2[组件约束: 模块职责与依赖方向约束]
D –> D3[质量属性: 性能/安全/可维护性约束]
D1 –> E[文档生成引擎]
D2 –> E
D3 –> E
E –> E1[Markdown 文档: 架构概述与约束规则]
E –> E2[Mermaid 图: C4 各层视图的代码化表达]
E –> E3[ADR 集合: 关键决策的记录与追溯]
E1 –> F[一致性验证]
E2 –> F
F –> F1[文档描述 vs 代码实现: 违规检测]
F –> F2[文档更新触发: 代码变更时自动重新生成]
style B fill:#e8f5e9
style D fill:#fff3e0
style E fill:#e3f2fd
上图展示了从代码到文档的完整生成链路。静态分析提取模块依赖图，动态分析提取运行时调用链，配置分析提取部署拓扑。三者共同构建 C4 的三层视图（Context → Container → Component），ADL 约束层补充设计意图和架构规则。文档生成引擎将两者结合输出结构化文档，一致性验证层持续检测文档与代码的偏差。
2.1 静态分析：从代码推导架构拓扑
// architecture-analyzer.ts — 代码静态架构分析器
// 设计意图：从代码仓库的文件结构和导入关系中推导架构拓扑，
// 识别模块边界、依赖方向和职责分区
interface ArchitectureTopology {
modules: ModuleInfo[];
connections: Connection[];
violations: ArchitectureViolation[];
}
interface ModuleInfo {
name: string;
path: string;
type: 'feature' | 'shared' | 'infra' | 'shell';
responsibilities: string[];
inwardDeps: string[]; // 依赖的上游模块
outwardDeps: string[]; // 被依赖的下游模块
}
interface Connection {
from: string;
to: string;
type: 'import' | 'event' | 'api-call' | 'shared-state';
strength: 'strong' | 'weak'; // 强依赖(编译时) vs 弱依赖(运行时)
}
interface ArchitectureViolation {
type: 'cross-boundary' | 'circular' | 'wrong-direction';
description: string;
modules: string[];
}
function analyzeCodeArchitecture(
fileGraph: Map<string, Set<string>>, // 文件→导入文件的映射
moduleMapping: Map<string, string> // 文件→所属模块的映射
): ArchitectureTopology {
const modules = new Map<string, ModuleInfo>();
const connections: Connection[] = [];
const violations: ArchitectureViolation[] = [];
// 构建模块依赖图
for (const [file, imports] of fileGraph) {
const sourceModule = moduleMapping.get(file) || 'unknown';
if (!modules.has(sourceModule)) {
modules.set(sourceModule, {
name: sourceModule,
path: file,
type: inferModuleType(sourceModule),
responsibilities: [],
inwardDeps: [],
outwardDeps: [],
});
}
for (const importedFile of imports) {
const targetModule = moduleMapping.get(importedFile) || 'unknown';
if (sourceModule !== targetModule) {
connections.push({
from: sourceModule,
to: targetModule,
type: 'import',
strength: 'strong',
});
// 记录模块间依赖关系
modules.get(sourceModule)!.inwardDeps.push(targetModule);
if (!modules.has(targetModule)) {
modules.set(targetModule, {
name: targetModule,
path: importedFile,
type: inferModuleType(targetModule),
responsibilities: [],
inwardDeps: [],
outwardDeps: [],
});
}
modules.get(targetModule)!.outwardDeps.push(sourceModule);
}
}
}
// 检测架构违规：跨层依赖
for (const conn of connections) {
const fromType = modules.get(conn.from)?.type;
const toType = modules.get(conn.to)?.type;
// feature 模块不应直接依赖其他 feature 模块
if (fromType === 'feature' && toType === 'feature') {
violations.push({
type: 'cross-boundary',
description: `feature模块 ${conn.from} 直接依赖 feature模块 ${conn.to}，应通过 shared 或 event 间接通信`,
modules: [conn.from, conn.to],
});
}
// infra 模块不应依赖 feature 模块（依赖方向反转）
if (fromType === 'infra' && toType === 'feature') {
violations.push({
type: 'wrong-direction',
description: `infra模块 ${conn.from} 依赖了 feature模块 ${conn.to}，违反了依赖方向规则`,
modules: [conn.from, conn.to],
});
}
}
// 检测循环依赖
const circularDeps = detectCircularDependencies(modules);
for (const cycle of circularDeps) {
violations.push({
type: 'circular',
description: `循环依赖: ${cycle.join(' → ')} → ${cycle[0]}`,
modules: cycle,
});
}
return {
modules: […modules.values()],
connections,
violations,
};
}
function inferModuleType(moduleName: string): ModuleInfo['type'] {
if (moduleName.includes('shell') || moduleName.includes('host')) return 'shell';
if (moduleName.includes('shared') || moduleName.includes('common')) return 'shared';
if (moduleName.includes('infra') || moduleName.includes('core')) return 'infra';
return 'feature';
}
function detectCircularDependencies(modules: Map<string, ModuleInfo>): string[][] {
const cycles: string[][] = [];
const visited = new Set<string>();
for (const [name] of modules) {
const path: string[] = [];
dfs(name, modules, visited, path, cycles);
}
return cycles;
}
function dfs(
current: string,
modules: Map<string, ModuleInfo>,
globalVisited: Set<string>,
path: string[],
cycles: string[][]
): void {
if (path.includes(current)) {
const cycleStart = path.indexOf(current);
cycles.push(path.slice(cycleStart).concat(current));
return;
}
if (globalVisited.has(current)) return;
path.push(current);
const deps = modules.get(current)?.inwardDeps || [];
for (const dep of deps) {
dfs(dep, modules, globalVisited, path, cycles);
}
path.pop();
globalVisited.add(current);
}
三、生产级实现：C4 模型自动绘制与文档生成
3.1 C4 模型各层视图生成
// c4-generator.ts — C4 模型自动绘制
// 设计意图：将代码分析结果转换为 C4 各层视图的 Mermaid 代码，
// 每层视图聚焦不同的抽象粒度，避免单一视图的信息过载
interface C4View {
level: 'context' | 'container' | 'component';
mermaidCode: string;
description: string;
}
// C4 Level 1: Context 视图 — 系统与外部实体的交互
function generateContextView(topology: ArchitectureTopology): C4View {
const externalEntities = topology.connections
.filter(c => c.type === 'api-call')
.map(c => c.to);
const uniqueExternals = […new Set(externalEntities)];
const mermaidCode = `flowchart LR
User[用户/浏览器] –> FE[前端系统]
FE –> API[后端 API 服务]
FE –> CDN[CDN 静态资源]
FE –> Auth[认证服务]
${uniqueExternals.map(e => `FE –> ${e}[${e}]`).join('\\n ')}
style FE fill:#4A90D9,color:#fff
style User fill:#6C5CE7,color:#fff`;
return {
level: 'context',
mermaidCode,
description: 'Context 视图展示前端系统与外部实体的交互关系',
};
}
// C4 Level 2: Container 视图 — 应用容器与部署单元
function generateContainerView(topology: ArchitectureTopology): C4View {
const containers = topology.modules.filter(m =>
m.type === 'shell' || m.type === 'feature'
);
const shared = topology.modules.filter(m => m.type === 'shared');
const infra = topology.modules.filter(m => m.type === 'infra');
const mermaidCode = `flowchart TB
subgraph 主应用Shell
Shell[路由分发 + 全局状态]
end
${containers.filter(c => c.type === 'feature').map(c =>
`subgraph ${c.name}
${c.name}_App[${c.name} 子应用]
end`
).join('\\n ')}
subgraph 共享层
${shared.map(s => `${s.name}[${s.name}]`).join('\\n ')}
end
subgraph 基础设施层
${infra.map(i => `${i.name}[${i.name}]`).join('\\n ')}
end
Shell –> ${containers.filter(c => c.type === 'feature').map(c => `${c.name}_App`).join('\\n Shell –> ')}
${containers.filter(c => c.type === 'feature').map(c =>
`${c.name}_App –> 共享层`
).join('\\n ')}`;
return {
level: 'container',
mermaidCode,
description: 'Container 视图展示应用容器、共享层和基础设施层的分层关系',
};
}
// C4 Level 3: Component 视图 — 单个容器内部的组件关系
function generateComponentView(
topology: ArchitectureTopology,
targetModule: string
): C4View {
const module = topology.modules.find(m => m.name === targetModule);
if (!module) {
return { level: 'component', mermaidCode: '', description: `模块 ${targetModule} 不存在` };
}
const internalConnections = topology.connections
.filter(c => c.from === targetModule || c.to === targetModule);
const upstreamModules = module.inwardDeps;
const downstreamModules = module.outwardDeps;
const mermaidCode = `flowchart TB
subgraph ${targetModule}内部组件
${targetModule}_Router[路由模块]
${targetModule}_Store[状态管理]
${targetModule}_Components[UI组件集]
${targetModule}_Services[服务层/API]
${targetModule}_Utils[工具函数]
end
${targetModule}_Router –> ${targetModule}_Components
${targetModule}_Components –> ${targetModule}_Store
${targetModule}_Components –> ${targetModule}_Services
${targetModule}_Services –> API[后端API]
${upstreamModules.map(m => `${targetModule}_Services –> ${m}[${m}]`).join('\\n ')}
style ${targetModule}_Router fill:#e8f5e9
style ${targetModule}_Store fill:#fff3e0
style ${targetModule}_Services fill:#e3f2fd`;
return {
level: 'component',
mermaidCode,
description: `Component 视图展示 ${targetModule} 内部的组件结构和依赖关系`,
};
}
3.2 AI 增强的文档叙述生成
// doc-narrator.ts — AI 增强的架构文档叙述生成
// 设计意图：将 C4 视图和架构违规信息转换为自然语言叙述，
// 大模型补充代码分析无法提取的设计意图和决策背景
async function generateArchitectureNarrative(
topology: ArchitectureTopology,
c4Views: C4View[],
existingADRs: string[],
llmClient: { chat: (prompt: string) => Promise<string> }
): Promise<string> {
const violationsStr = topology.violations
.map(v => `- [${v.type}] ${v.description}`)
.join('\\n');
const adrStr = existingADRs.join('\\n—\\n');
const prompt = `你是一个前端架构文档专家。请基于以下架构分析结果，生成完整的架构文档叙述。
**架构拓扑摘要**:
– 模块总数: ${topology.modules.length}
– 连接总数: ${topology.connections.length}
– 违规项: ${topology.violations.length}
**架构违规详情**:
${violationsStr || '无违规项'}
**已有的架构决策记录(ADR)**:
${adrStr || '暂无 ADR'}
**文档结构要求**:
1. 架构概述：系统的整体分层和模块划分
2. 各层职责说明：shell/shared/infra/feature 各层的职责边界
3. 通信机制：模块间的通信方式与约束规则
4. 架构违规说明：当前发现的违规项及其影响
5. 改进建议：基于违规项的架构优化方向
请输出中文 Markdown 格式的架构文档。`;
const response = await llmClient.chat(prompt);
return response;
}
四、边界分析与架构权衡
静态分析的粒度限制：文件级的导入分析无法识别运行时的动态依赖（如 import() 懒加载、事件总线订阅、条件性导入）。这些弱依赖在代码中不明显，但在运行时影响架构拓扑。解决方案是结合动态分析（运行时调用链追踪）补充静态分析的盲区，但动态分析需要在生产环境埋点，成本和隐私风险需要评估。
C4 视图的信息过载：大型项目的 Component 视图可能包含上百个组件节点，Mermaid 图的可读性急剧下降。需要提供"聚焦视图"——只展示用户选中模块的内部结构，而非全量渲染。交互式文档平台（如 Structurizr）比静态 Markdown 更适合呈现 C4 视图，但部署成本更高。
AI 叙述的准确性偏差：大模型生成的架构叙述可能包含"听起来合理但与实际不符"的描述。例如，AI 可能推断"所有子应用通过 Module Federation 共享依赖"，但实际代码中仍有子应用使用 iframe 隔离。必须将 AI 生成的叙述与代码分析结果进行交叉验证，不一致处标注为"待人工确认"。
文档更新的触发时机：代码变更时自动触发文档重新生成，但并非每次变更都影响架构拓扑。频繁重新生成文档会增加 API 调用成本，且文档的频繁变更让团队失去稳定参考。建议只在架构级变更（新增模块、变更模块边界、修改路由策略）时触发文档重新生成，功能级变更（新增页面、修改样式）不影响架构文档。
五、总结
AI 生成前端架构文档，将文档维护从"人工季度更新"推进到"代码驱动自动生成"阶段。静态分析从代码中提取模块拓扑，C4 模型将拓扑转换为分层视图，ADL 约束补充设计意图，AI 叙述将结构化信息转换为可读文档，一致性验证持续检测文档与代码的偏差。落地建议：第一步部署代码静态分析工具，自动提取模块依赖图和架构拓扑；第二步实现 C4 三层视图的自动绘制，生成 Mermaid 图代码；第三步引入大模型生成架构叙述，补充代码分析无法提取的设计意图；第四步在 CI 中集成一致性验证，代码变更触发文档更新但仅在架构级变更时重新生成全文。关键原则是：架构文档不是独立于代码的"说明文件"，而是代码架构的结构化映射——文档的准确性取决于它与代码实现的一致性，而非编写者的叙述水平。
