前端工程规范与代码洁癖养成：可维护性体系搭建实战-171主机测评

前端工程规范与代码洁癖养成：可维护性体系搭建实战

cover

一、规范的"形同虚设"：写了文档，没人遵守

前端团队最常见的问题是"有规范但不执行"。ESLint 配置了 200 条规则，但 CI 没有门禁，PR 照样合入；代码评审规范写了 10 页文档，但 Review 时只看逻辑不看风格；Git 提交信息格式约定了 Conventional Commits，但历史记录里全是"fix"和"update"。规范形同虚设的根源是"靠人执行"——人是最不可靠的执行者。

代码洁癖不是天生的，是工具链强制养成的。ESLint 报错阻断提交、Prettier 自动格式化、Husky 钩子拦截不合规的 commit message——当规范由工具强制执行时，团队自然养成洁癖习惯。

二、工程规范体系架构

graph TB
subgraph 代码规范
A[ESLint 语法+最佳实践]
B[Prettier 格式化]
C[TypeScript严格模式 类型安全]
end

subgraph 提交规范
D[Commitlint 提交信息格式]
E[Conventional Commits feat/fix/docs/chore]
F[Commitizen 交互式提交]
end

subgraph 评审规范
G[PR模板 变更说明+测试计划]
H[自动化检查 CI门禁]
I[Review Checklist 必检项清单]
end

subgraph 强制执行
J[Husky pre-commit ESLint+Prettier]
K[Husky commit-msg Commitlint]
L[CI Pipeline 全量检查+门禁]
end

A –> J
B –> J
C –> L
D –> K
E –> K
G –> H
H –> L

规范体系的核心是"工具强制执行"：pre-commit 钩子确保提交前代码合规，commit-msg 钩子确保提交信息合规，CI 门禁确保合并前全量检查通过。三层防线，任何一层不通过都无法进入代码库。

三、规范体系实现

3.1 ESLint + Prettier 配置

// eslint.config.mjs
import js from '@eslint/js';
import tsPlugin from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';
import reactPlugin from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import prettier from 'eslint-config-prettier';

export default [
js.configs.recommended,
{
files: ['**/*.{ts,tsx}'],
languageOptions: {
parser: tsParser,
parserOptions: {
ecmaVersion: 2024,
sourceType: 'module',
ecmaFeatures: { jsx: true },
},
},
plugins: {
'@typescript-eslint': tsPlugin,
'react': reactPlugin,
'react-hooks': reactHooks,
},
rules: {
// TypeScript 严格规则
'@typescript-eslint/no-explicit-any': 'error',
'@typescript-eslint/no-unused-vars': ['error', {
argsIgnorePattern: '^_',
}],
'@typescript-eslint/consistent-type-imports': ['error', {
prefer: 'type-imports',
}],

// React 规则
'react/react-in-jsx-scope': 'off',
'react-hooks/rules-of-hooks': 'error',
'react-hooks/exhaustive-deps': 'warn',

// 代码质量规则
'no-console': ['warn', { allow: ['warn', 'error'] }],
'max-lines-per-function': ['warn', {
max: 80,
skipBlankLines: true,
skipComments: true,
}],
'complexity': ['warn', { max: 10 }],
},
},
prettier, // Prettier 规则放在最后，覆盖格式相关的 ESLint 规则
];

3.2 Husky + lint-staged 配置

// package.json
{
"scripts": {
"lint": "eslint . –ext .ts,.tsx",
"lint:fix": "eslint . –ext .ts,.tsx –fix",
"format": "prettier –write .",
"typecheck": "tsc –noEmit",
"prepare": "husky"
},
"lint-staged": {
"*.{ts,tsx}": [
"eslint –fix",
"prettier –write"
],
"*.{json,md,css}": [
"prettier –write"
]
}
}

# Husky 钩子设置
npx husky init
echo 'npx lint-staged' > .husky/pre-commit
echo 'npx commitlint –edit $1' > .husky/commit-msg

3.3 Commitlint 配置

// commitlint.config.js
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', [
'feat', // 新功能
'fix', // Bug 修复
'docs', // 文档变更
'style', // 代码格式（不影响逻辑）
'refactor', // 重构（不是新功能也不是修复）
'perf', // 性能优化
'test', // 测试
'chore', // 构建或辅助工具
'revert', // 回退
]],
'scope-case': [2, 'always', 'lower-case'],
'subject-max-length': [2, 'always', 72],
'body-max-line-length': [2, 'always', 100],
},
};

3.4 PR 模板与自动化检查

<!– .github/pull_request_template.md –>
## 变更说明
<!– 简要描述本次变更的内容和原因 –>

## 变更类型
– [ ] 新功能 (feat)
– [ ] Bug 修复 (fix)
– [ ] 重构 (refactor)
– [ ] 性能优化 (perf)
– [ ] 文档 (docs)

## 测试计划
– [ ] 单元测试已通过
– [ ] 手动测试已验证
– [ ] 无破坏性变更

## 性能影响
– [ ] 无性能影响
– [ ] 有性能影响（请说明）

## 检查清单
– [ ] 代码符合 ESLint 规则
– [ ] TypeScript 类型检查通过
– [ ] 无 console.log 残留
– [ ] 新增代码有注释说明设计意图

# .github/workflows/code-quality.yml
name: Code Quality

on:
pull_request:
branches: [main]

jobs:
quality:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v4
– run: npm ci

– name: ESLint
run: npm run lint

– name: TypeScript
run: npm run typecheck

– name: Unit Tests
run: npm run test — –coverage

– name: Bundle Size Check
run: npm run size-check

四、规范体系的 Trade-offs 分析

规范严格度与开发体验：过严的 ESLint 规则（如禁止 any、强制每函数 50 行以内）会频繁阻断开发流程，尤其在项目初期。建议分阶段收紧：初始阶段只启用 error 级规则，稳定后逐步添加 warn 规则，最后收紧到最严格级别。

lint-staged 的性能：lint-staged 只检查暂存文件，速度快。但如果修改了公共类型定义，可能需要全量检查才能发现类型错误。建议 lint-staged 做快速检查，CI 做全量检查，两者互补。

Commitlint 的灵活性：严格的 commit message 格式有时显得多余——修个拼写错误也要写"fix: correct typo in README"。但格式化的提交信息是自动化 changelog 的基础，长期收益远大于短期不便。

团队认同：规范体系需要团队共同维护。如果只有部分人遵守，规范就会逐渐失效。建议在团队内建立"规范评审会"，定期讨论和调整规则，让每个人都有参与感。

五、总结

前端工程规范的核心是"工具强制执行，习惯自然养成"。ESLint + Prettier 管代码风格，Commitlint 管提交信息，Husky 钩子做强制执行，CI 门禁做最终兜底。四层防线，确保规范不只是文档，而是可执行的约束。

落地建议：先从最基础的规范开始（ESLint 推荐规则 + Prettier + Commitlint），在 CI 中设置门禁；然后根据团队反馈逐步收紧规则；最后建立 PR 模板和 Review Checklist，将规范内化为团队习惯。全程保持规则可调整，避免"规范僵化"导致团队抵触。

前端工程规范与代码洁癖养成：可维护性体系搭建实战