前端技术债治理的年度复盘：从积重难返到有序偿还的系统化方法-平芜编程栈

前端技术债治理的年度复盘：从积重难返到有序偿还的系统化方法

技术债是每个长期维护的前端项目都无法回避的话题。这一年的治理过程，从一个濒临失控的中型项目起步，逐步建立了一套可复用的治理框架。复盘的意义不是展示成果，而是沉淀那些"回头看很简单、当时没想到"的方法论教训。

一、治理前的状态

年初盘点时，项目面临一个典型的技术债雪球：

代码层面。3.2万行TypeScript代码中，绕过strict: true的// @ts-ignore有47处，any类型847处。核心业务逻辑分散在12个超过500行的巨型组件中，圈复杂度最高的函数达到38。

依赖层面。package.json中有11个已废弃的npm包、3个不同版本的moment（dependencies和devDependencies中存在版本冲突）。

测试层面。测试覆盖率21%，但大量测试是"渲染不出错就行"的快照测试，几乎不具备回归保护能力。

二、治理策略：先止血，后拆弹，再还债

技术债治理最忌讳"全面开战"。同时修复所有问题意味着同时引入所有风险。一年的实践验证了三阶段策略的有效性。

第一阶段：止血（第1个月）。停止新增技术债。这一阶段不做修复，只做规则堵漏。在CI中加入自动化检查，禁止新增any类型、禁止合并超过500行的组件、禁止引入已废弃的依赖包。

第二阶段：拆弹（第2-4月）。处理高风险技术债。优先级排序不是按"最容易修"，而是按"修坏了影响最小"。封装隔离风险区域的API，为核心业务路径补上集成测试。

第三阶段：还债（第5-12月）。系统性地偿还存量技术债。按模块逐个还清，每次只选择一个模块，避免上下文切换。

// 技术债自动化拦截：CI中的代码质量门禁 import { execSync } from 'node:child_process'; import fs from 'node:fs'; import path from 'node:path'; interface DebtRule { name: string; description: string; check: () => DebtCheckResult; severity: 'block' | 'warn'; } interface DebtCheckResult { passed: boolean; message: string; baseline: number; // 当前存量 diff: number; // 本次PR新增量（正数为新增债） } // 规则1：禁止新增 any 类型 const anyTypeRule: DebtRule = { name: 'no-new-any', description: 'PR中禁止新增any类型声明', severity: 'block', check(): DebtCheckResult { // 对比PR分支和main分支的any数量 try { const mainAny = countAnyInBranch('origin/main'); const prAny = countAnyInBranch('HEAD'); const diff = prAny - mainAny; return { passed: diff <= 0, message: diff > 0 ? `新增了 ${diff} 处any类型声明，请使用具体类型替代` : `any类型数量不变或减少(-${Math.abs(diff)}处)`, baseline: mainAny, diff }; } catch (error) { return { passed: true, message: 'any类型检查跳过（分支获取失败）', baseline: 0, diff: 0 }; } } }; // 规则2：禁止超过500行的组件文件 const fileSizeRule: DebtRule = { name: 'max-file-lines', description: '组件文件不得超过500行', severity: 'block', check(): DebtCheckResult { // 获取PR新增或修改的组件文件 const changedFiles = execSync( 'git diff --name-only --diff-filter=AM origin/main...HEAD', { encoding: 'utf-8' } ).split('\n').filter(f => f.match(/\.(tsx|jsx)$/)); const violations: string[] = []; for (const file of changedFiles) { if (!fs.existsSync(file)) continue; const lines = fs.readFileSync(file, 'utf-8').split('\n').length; if (lines > 500) { violations.push(` ${file}: ${lines}行 (限制500行)`); } } return { passed: violations.length === 0, message: violations.length > 0 ? `以下文件超过行数限制:\n${violations.join('\n')}` : '所有组件文件行数合规', baseline: 0, diff: violations.length }; } }; // 规则3：禁止引入废弃依赖 const deprecatedDepRule: DebtRule = { name: 'no-deprecated-deps', description: '禁止安装已知的废弃npm包', severity: 'block', // 已知废弃/不推荐使用的包列表 deprecatedPackages: [ 'moment', 'request', 'left-pad', 'core-js@2', 'babel-eslint', 'tslint', '@types/tslint' ], check(): DebtCheckResult { // 检查新增的依赖 const mainPkg = JSON.parse( execSync('git show origin/main:package.json', { encoding: 'utf-8' }) ); const prPkg = JSON.parse(fs.readFileSync('package.json', 'utf-8')); const mainDeps = new Set([ ...Object.keys(mainPkg.dependencies || {}), ...Object.keys(mainPkg.devDependencies || {}) ]); const prDeps = [ ...Object.keys(prPkg.dependencies || {}), ...Object.keys(prPkg.devDependencies || {}) ]; const newDeps = prDeps.filter(d => !mainDeps.has(d)); const deprecatedFound = newDeps.filter(d => this.deprecatedPackages.some(dp => d === dp || d.startsWith(dp + '@')) ); return { passed: deprecatedFound.length === 0, message: deprecatedFound.length > 0 ? `新增了废弃依赖: ${deprecatedFound.join(', ')}` : '依赖检查通过', baseline: 0, diff: deprecatedFound.length }; } }; // 辅助函数：统计分支中的any数量 function countAnyInBranch(ref: string): number { try { const output = execSync( `git grep -c ': any' ${ref} -- '*.ts' '*.tsx' | grep -v node_modules | grep -v '.d.ts'`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] } ); return output .split('\n') .filter(line => line.includes(':')) .reduce((sum, line) => { const count = parseInt(line.split(':').pop() || '0', 10); return sum + (isNaN(count) ? 0 : count); }, 0); } catch { return 0; } } // 导出规则集 export const debtGateRules: DebtRule[] = [ anyTypeRule, fileSizeRule, deprecatedDepRule ];