AI 生成 UI 的代码质量度量：从圈复杂度到可维护性指数的自动化评估

一、"AI 写的代码能跑，但你看一眼就知道是 AI 写的"

用 GPT 生成了一个后台表单页面，功能正常——输入框、下拉、日期选择器、提交按钮，全部能工作。但细看代码：一个 200 行的组件没有拆分、Props 全部用any、useEffect 里嵌套了 3 层条件判断、硬编码了 17 个颜色值。功能正确，但质量灾难。

AI 生成代码的质量是不可信的问题。如果让 AI 直接输出代码到生产环境而不经过质量评估，三个月后你会得到一个"功能完整但无法维护"的前端项目。代码质量度量就是这道防线：对 AI 输出的代码，用机器可执行的指标做自动打分，低于阈值的退回重做。

二、代码质量的多维评估模型

该评估模型将 AI 生成的代码输入到一个多维评估体系中，主要从结构、设计规范、可维护性和性能四个维度进行拆解：

• 结构维度：重点考察圈复杂度（Cyclomatic Complexity）、组件行数（Lines per Component）以及嵌套深度（Nesting Depth）。
• 设计规范维度：关注 Token 合规率（Token Compliance）、颜色硬编码率（Hardcoded Colors）及间距标准化率（Standard Spacing）。
• 可维护性维度：涵盖可维护性指数（Maintainability Index）、代码注释率（Comment Ratio）和 Props 类型覆盖率（Type Coverage）。
• 性能维度：评估 useMemo/useCallback 使用率及重渲染风险（Re-render Risk）。

所有维度的指标经过加权评分后汇总为总分。若总分大于等于 75 分，则判定通过并合入代码库；否则退回 AI 重新生成，并附带具体的改进建议。

三、质量度量引擎实现

// code-quality/code-quality-evaluator.ts // AI 生成代码的质量评估引擎 import ts from 'typescript'; import { ESLint } from 'eslint'; interface QualityMetrics {

/** 圈复杂度/
cyclomaticComplexity: {
average: number; // 平均圈复杂度（目标 < 10）
max: number; // 最大圈复杂度（目标 < 15）
score: number; // 0~100
};
/* 可维护性指数/
maintainabilityIndex: {
value: number; // 0~100（越高越好，> 65 为合格）
score: number;
};
/* Token 合规率/
tokenCompliance: {
rate: number; // 0~1（1 = 所有颜色都使用 Token）
violations: Array<{ file: string; line: number; value: string }>;
score: number;
};
/* 代码结构/
structure: {
maxFunctionLines: number; // 最大函数行数（目标 < 80）
maxNestingDepth: number; // 最大嵌套深度（目标 < 4）
componentCount: number; // 组件数量
score: number;
};
/* 综合评分（加权平均） */
overall: number;
}

/**

• AI 代码质量评估器
• 对 AI 生成的代码做多维度评估，输出结构化评分和改进建议
  */
  class CodeQualityEvaluator {
  private designTokens: Map<string, string>;

constructor(tokenJsonPath: string) {
this.designTokens = this.loadTokens(tokenJsonPath);
}

/**

• 计算代码的圈复杂度
• 圈复杂度 = 决策点数量 + 1
• 决策点：if, else if, for, while, &&, ||, ?:, ?.(), switch case
  */
  private calcCyclomaticComplexity(source: string): { average: number; max: number } {
  const functions = this.extractFunctions(source);

if (functions.length === 0) { return { average: 0, max: 0 }; } const complexities = functions.map((fn) => { let complexity = 1; // 基础值 // 统计决策点 const patterns = [ /\bif\b/g, /\belse\s+if\b/g, /\bfor\b/g, /\bwhile\b/g, /\bcase\b/g, /\?\s*:/g, // 三元运算符 /&&/g, /\|\|/g, /\?\./g, // 可选链 ]; for (const pattern of patterns) { const matches = fn.match(pattern); if (matches) complexity += matches.length; } return complexity; }); return { average: complexities.reduce((a, b) => a + b, 0) / complexities.length, max: Math.max(...complexities) };

}

/**

• 提取所有函数体（用于圈复杂度计算）
  */
  private extractFunctions(source: string): string[] {
  const functions: string[] = [];
  const sourceFile = ts.createSourceFile(
  'temp.tsx', source, ts.ScriptTarget.Latest, true
  );

function visit(node: ts.Node) { if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) { functions.push(node.getText(source)); } ts.forEachChild(node, visit); } visit(sourceFile); return functions;

}

/**

• 计算可维护性指数
• 公式（简化版，近似于 Visual Studio 的 MI 计算）：
• MI = max(0, (171 - 5.2ln(HV) - 0.23CC - 16.2*ln(LOC)) * 100 / 171)
• 其中：
• • HV: Halstead Volume（程序容量）
• • CC: 圈复杂度
• • LOC: 代码行数
    */
    private calcMaintainabilityIndex(source: string): number {
    const lines = source.split('\n').filter(l => l.trim().length > 0);

const loc = lines.length; const cc = this.calcCyclomaticComplexity(source); // Halstead Volume 简化计算 const operators = source.match(/[+\-*\/=<>!&|?:]+/g)?.length || 0; const operands = source.match(/\b[a-zA-Z_]\w*\b/g)?.length || 0; const vocabulary = operators + operands; const length = operators + operands; const volume = vocabulary > 0 ? length * Math.log2(vocabulary) : 0; const mi = Math.max( 0, (171 - 5.2 * Math.log(Math.max(volume, 1)) - 0.23 * cc.max - 16.2 * Math.log(Math.max(loc, 1))) * 100 / 171 ); return Math.min(100, Math.round(mi));

}

/**

• 计算 Token 合规率
• 扫描代码中所有颜色/间距值，检查是否使用设计 Token
  */
  private calcTokenCompliance(source: string): {
  rate: number;
  violations: Array<{ file: string; line: number; value: string }>;
  } {
  const violations: Array<{ file: string; line: number; value: string }> = [];

// 匹配所有硬编码的颜色值（排除 var() 和 Token 引用） const colorRegex = /(?<!var\(|--)(#[0-9a-fA-F]{3,8}\b|rgba?\([^)]+\))/g; let match; const allColorValues: string[] = []; const tokenColorValues: string[] = []; while ((match = colorRegex.exec(source)) !== null) { const color = match[0].toLowerCase(); // 跳过允许的基本颜色 if (['#fff', '#ffffff', '#000', '#000000', 'transparent', 'inherit'].includes(color)) { continue; } allColorValues.push(color); // 检查是否匹配设计 Token const isToken = Array.from(this.designTokens.values()) .some(tokenValue => tokenValue.toLowerCase() === color); if (isToken) { tokenColorValues.push(color); } else { violations.push({ file: 'generated.tsx', line: 0, // 略去行号计算 value: color }); } } return { rate: allColorValues.length > 0 ? tokenColorValues.length / allColorValues.length : 1, violations };

}

/**

• 综合评估——所有维度的入口
  */
  evaluate(source: string): QualityMetrics {
  const cc = this.calcCyclomaticComplexity(source);
  const mi = this.calcMaintainabilityIndex(source);
  const tokenCompliance = this.calcTokenCompliance(source);

// 圈复杂度评分 const ccScore = Math.max(0, 100 - cc.max * 5); // 可维护性评分 const miScore = Math.min(100, mi); // Token 合规评分 const tokenScore = tokenCompliance.rate * 100; // 结构评分 const lines = source.split('\n'); const maxFunctionLines = this.calcMaxFunctionLines(source); const maxNesting = this.calcMaxNesting(source); const structScore = Math.max(0, 100 - Math.max(0, maxFunctionLines - 80) * 0.5 - maxNesting * 10 ); // 综合评分（加权） const overall = ( ccScore * 0.25 + miScore * 0.25 + tokenScore * 0.25 + structScore * 0.25 ); return { cyclomaticComplexity: { average: Math.round(cc.average * 10) / 10, max: cc.max, score: Math.round(ccScore) }, maintainabilityIndex: { value: mi, score: Math.round(miScore) }, tokenCompliance: { rate: Math.round(tokenCompliance.rate * 100) / 100, violations: tokenCompliance.violations, score: Math.round(tokenScore) }, structure: { maxFunctionLines, maxNestingDepth: maxNesting, componentCount: 0, score: Math.round(structScore) }, overall: Math.round(overall) };

}

private calcMaxFunctionLines(source: string): number {
const functions = this.extractFunctions(source);
return Math.max(0, ...functions.map(fn => fn.split('\n').length));
}

private calcMaxNesting(source: string): number {
const lines = source.split('\n');
let currentDepth = 0;
let maxDepth = 0;

for (const line of lines) { const trimmed = line.trim(); // 统计缩进层级 const indent = line.length - line.trimStart().length; const depth = Math.floor(indent / 2); // 假设 2 空格缩进 if (trimmed.startsWith('if ') || trimmed.startsWith('for ') || trimmed.startsWith('while ') || trimmed.startsWith('switch ')) { currentDepth = depth + 1; maxDepth = Math.max(maxDepth, currentDepth); } } return maxDepth;

}

private loadTokens(path: string): Map<string, string> {
// 加载设计 Token 文件
return new Map();
}
}

## 四、AI 代码质量的独特挑战 **AI 倾向于"过度实现"**。人的代码倾向于"先做最小可用"，AI 倾向于"把能想到的都写进去"。这导致 AI 生成的组件 Props 数量远超实际需求（平均 15+ 个 Props 而人类平均 7 个）。度量需要加入"Props 使用率"指标。 **AI 缺乏"项目上下文"**。AI 不知道项目中已有 `Button` 组件，可能会生成一个新的 `<button>` 标签。度量需要检测"重复实现"——检查 AI 生成的代码是否重复了已有组件库的功能。 **格式化不等于质量**。AI 输出的代码通常会过 Prettier 格式化——看起来工整。但格式化的整洁掩盖了结构的混乱。质量度量关注的是"代码说了什么"，而不是"代码好不好看"。 ## 五、总结 AI 生成 UI 代码的质量度量是一个**门禁系统**，在代码合入前自动评估： 1. **圈复杂度**（< 10 平均，< 15 最大）——控制决策分支密度 2. **可维护性指数**（> 65）——综合代码健康度的通用指标 3. **Token 合规率**（> 90%）——硬编码值的使用比例 4. **结构质量**（函数 < 80 行，嵌套 < 4 层）——代码的可读性基线 阈值不是铁律——优秀的代码可能因为"必要的复杂性"而超标。但 AI 不应该享受这个例外：当 AI 生成的代码质量不达标时，应该退回让 AI 重新生成（附带具体的改进建议），而不是人工去修。