当前位置：首页 > news >正文

前端工程规范落地：从 ESLint 到架构约束的代码洁癖体系

news 2026/6/26 21:26:39

前端工程规范落地：从 ESLint 到架构约束的代码洁癖体系

一、规范形同虚设的根源：工具链与架构的断层

每个前端团队都有规范文档，但真正落地的不到两成。问题不在规范本身写得不好，而在于规范与工具链之间存在断层。文档写的是"组件职责单一，禁止跨层级状态访问"，但 ESLint 配置的只有no-console和semi。架构层面的约束完全没有工具化保障，全靠人自觉。

更深层的问题是：规范只覆盖了代码风格，没有覆盖架构边界。一个组件同时负责数据获取、状态管理、UI 渲染和路由跳转，ESLint 不会报任何错——因为语法完全合法。但架构上这已经是一个"上帝组件"，后续维护成本指数级增长。

代码洁癖不是强迫症，而是一套可度量、可执行、可自动化的工程约束体系。它的核心目标是用工具替代人工审查，让违反规范的代码在提交阶段就被拦截，而不是上线后才发现。

二、分层约束体系：从风格到架构的四级防线

代码规范不是单一层面的配置，而是一个从风格到架构的分层约束体系。每一层解决不同维度的问题，工具链也不同。

flowchart LR subgraph L1["第一层：代码风格"] A[ESLint + Prettier] --> B[自动格式化<br/>零人工介入] end subgraph L2["第二层：模式约束"] C[自定义 ESLint 规则] --> D[禁止反模式<br/>如 God Component] end subgraph L3["第三层：架构边界"] E[依赖方向检测<br/>Module Boundaries] --> F[禁止跨层直接引用<br/>如组件直接调 API] end subgraph L4["第四层：性能预算"] G[Bundle Size 阈值<br/>+ CI 门禁] --> H[超限阻断合并<br/>强制优化] end L1 --> L2 --> L3 --> L4

第一层解决"代码看起来一致"的问题，Prettier 自动格式化，无需讨论。第二层解决"代码写法正确"的问题，通过自定义 ESLint 规则禁止已知的反模式。第三层解决"代码架构合理"的问题，通过模块边界检测工具约束依赖方向。第四层解决"代码性能达标"的问题，通过 CI 门禁拦截体积超标的合并请求。

四层约束逐级递进，越往上约束越强，工具链越复杂，但收益也越大。前两层是基线，后两层是进阶。

三、生产级规范工具链的配置与实现

3.1 自定义 ESLint 规则：检测上帝组件

import type { Rule } from 'eslint'; import type { ArrowFunctionExpression, FunctionExpression } from 'estree'; /** * 自定义 ESLint 规则：检测组件函数体行数是否超过阈值。 * 上帝组件的核心特征是代码行数过多，职责混杂。 * 阈值默认 150 行，可根据项目实际情况调整。 * 为什么用行数而非 AST 节点数？因为行数与可读性直接相关， * AST 节点数对嵌套层级不敏感，一个深层嵌套的三元表达式 * 节点数很多但行数很少，反而比扁平的长函数更难读。 */ const noGodComponentRule: Rule.RuleModule = { meta: { type: 'suggestion', docs: { description: '禁止超过指定行数的组件函数', category: 'Best Practices', }, schema: [ { type: 'object', properties: { maxLines: { type: 'number', default: 150 }, }, additionalProperties: false, }, ], messages: { tooLong: '组件 "{{name}}" 函数体共 {{lines}} 行，超过阈值 {{maxLines}} 行。请拆分职责。', }, }, create(context) { const maxLines = (context.options[0] as { maxLines?: number })?.maxLines ?? 150; return { 'ArrowFunctionExpression, FunctionExpression'(node: ArrowFunctionExpression | FunctionExpression) { // 只检测 React 组件：名称大写开头 const parent = node.parent; if (parent?.type === 'VariableDeclarator' && parent.id?.type === 'Identifier') { const name = parent.id.name; if (!/^[A-Z]/.test(name)) return; // 非组件，跳过 const startLine = node.loc?.start.line ?? 0; const endLine = node.loc?.end.line ?? 0; const lines = endLine - startLine + 1; if (lines > maxLines) { context.report({ node, messageId: 'tooLong', data: { name, lines, maxLines }, }); } } }, }; }, }; export default noGodComponentRule;

3.2 模块边界检测：约束依赖方向

import type { Rule } from 'eslint'; import path from 'path'; /** * 模块边界规则：禁止组件直接调用 API 层。 * 架构约定：组件 -> Hooks -> Services -> API * 如果组件直接 import API 模块，说明缺少 Hooks 层封装， * 数据获取逻辑与 UI 耦合，后续无法复用和测试。 */ const moduleBoundaryRule: Rule.RuleModule = { meta: { type: 'error', docs: { description: '约束模块依赖方向，禁止跨层直接引用', }, messages: { crossLayerImport: '"{{importer}}" 位于 {{importerLayer}} 层，不允许直接引用 {{importeeLayer}} 层的 "{{importee}}"。请通过中间层封装。', }, schema: [ { type: 'object', properties: { layers: { type: 'array', items: { type: 'string' }, }, rules: { type: 'array', items: { type: 'object', properties: { from: { type: 'string' }, disallow: { type: 'array', items: { type: 'string' } }, }, }, }, }, }, ], }, create(context) { const options = context.options[0] ?? {}; const layers: string[] = options.layers ?? ['components', 'hooks', 'services', 'api']; const rules: Array<{ from: string; disallow: string[] }> = options.rules ?? [ { from: 'components', disallow: ['api'] }, { from: 'components', disallow: ['services'] }, ]; // 从文件路径推断所属层级 function inferLayer(filePath: string): string | null { const normalized = filePath.replace(/\\/g, '/'); for (const layer of layers) { if (normalized.includes(`/${layer}/`)) return layer; } return null; } return { ImportDeclaration(node) { const importPath = (node.source.value as string); if (!importPath.startsWith('.') && !importPath.startsWith('@/')) return; // 忽略外部依赖 const importerLayer = inferLayer(context.filename); if (!importerLayer) return; // 解析被导入模块的绝对路径以推断层级 const importeeAbs = path.resolve(path.dirname(context.filename), importPath); const importeeLayer = inferLayer(importeeAbs); if (!importeeLayer) return; // 检查是否违反依赖规则 const matchedRule = rules.find(r => r.from === importerLayer); if (matchedRule?.disallow.includes(importeeLayer)) { context.report({ node, messageId: 'crossLayerImport', data: { importer: path.basename(context.filename), importerLayer, importee: importPath, importeeLayer, }, }); } }, }; }, }; export default moduleBoundaryRule;

3.3 CI 门禁：Bundle Size 预算硬约束

# .github/workflows/budget-guard.yml name: Performance Budget Guard on: pull_request: paths: - 'src/**' - 'package.json' jobs: budget-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 cache: 'pnpm' - run: pnpm install --frozen-lockfile - run: pnpm build # 使用 bundlesize 检查产物体积 - name: Bundle Size Check run: npx bundlesize env: BUNDLESIZE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 自定义阈值检查：主入口 JS 不超过 200KB (gzip) - name: Custom Budget Validation run: | SIZE=$(gzip -c dist/assets/index-*.js | wc -c) THRESHOLD=204800 # 200KB if [ "$SIZE" -gt "$THRESHOLD" ]; then echo "::error::主入口 JS 体积 $(($SIZE / 1024))KB 超过预算 $(($THRESHOLD / 1024))KB" exit 1 fi echo "主入口 JS 体积 $(($SIZE / 1024))KB，在预算范围内"