1 / 4概念
Code Quality
代码质量工具把“可维护性”拆成可重复检查的信号:格式、规则违规、类型错误、重复度、覆盖率和安全热点。判断标准不是告警数量,而是哪些告警真的能阻止缺陷进入主干。
1 概念
1.1 一句话定义
代码质量是一组可度量的属性——正确性、可读性、可维护性、安全性和性能——以及用来守住这些属性的静态检查、格式化和质量门禁。工具只提供信号,门禁才决定信号是否阻断合并。
1.2 它解决什么问题
- 格式争论消耗评审时间:缩进、引号、换行本可以自动统一。
- 低级缺陷重复出现:未处理的 Promise、悬空变量、危险的正则。
- 质量随版本漂移:没有门禁时,规则会逐渐被忽略或关闭。
没有这些工具,评审靠个人习惯,缺陷靠线上发现,债务靠感觉。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 打包、测试运行器与类型检查命令 | JavaScript / TypeScript Toolchain |
| 流水线阶段、缓存与门禁执行 | CI/CD |
| 依赖漏洞、SBOM 与签名 | Supply Chain Security |
| 代码评审的沟通与设计取舍 | Code Review / Architecture |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 规则(rule) | 对 AST 的一次断言 | 不是格式化偏好 |
| 严重级别 | off/warn/error 或 blocker/critical | 决定是否阻断 |
| 自动修复 | 工具直接改写源码 | 不是所有规则都安全 |
| 技术债 | 为短期交付留下的可量化维护成本 | 不是“代码丑” |
| 质量门禁 | 进入下一阶段的条件集合 | 不是报告本身 |
| 误报 | 规则报告了实际不存在的问题 | 不是“我不想改” |
| 基线 | 存量问题的冻结快照 | 不是永久豁免 |
2 机制
2.1 心智模型
把质量工具分成三层:格式层只关心空白与标点,规则层在 AST 上找模式,度量层在仓库历史上算趋势。三层解决不同问题,混在一起会让读者分不清“必须修”和“建议改”。
2.2 机制拆解
- 解析:工具把源码解析成 AST,保留位置、作用域和类型信息。
- 匹配:规则遍历 AST,命中后产生带位置、级别和修复建议的报告。
- 修复:
--fix只应用标记为安全的修复;跨文件的修复通常需要人工确认。 - 聚合:CI 汇总报告,质量门禁按新代码/全量代码分别判断。
- 基线:存量问题冻结,新增问题才阻断;基线要定期清理,不能变成永久豁免。
2.3 完整枚举
| 层 | 代表工具 | 能发现 | 不能发现 |
|---|---|---|---|
| 格式化 | Prettier、Biome | 缩进、引号、换行、尾逗号 | 逻辑错误 |
| 规则检查 | ESLint、oxlint、Biome | 未使用变量、危险模式、风格规则 | 类型不匹配 |
| 类型检查 | TypeScript tsc | 类型错误、空值、签名不匹配 | 运行时数据错误 |
| 静态分析 | SonarQube、CodeQL | 重复、复杂度、坏味道、部分安全缺陷 | 业务语义错误 |
| 覆盖率 | Vitest/Jest coverage、Istanbul | 未执行的分支/行 | 断言是否有效 |
| 重复度 | SonarQube、jscpd | 复制粘贴的代码块 | 抽象是否合理 |
| 依赖/安全 | npm audit、Snyk、Dependabot | 已知漏洞、过期依赖 | 零日与业务逻辑漏洞 |
常见规则类别:
| 类别 | 例子 | 默认级别 | 处理方式 |
|---|---|---|---|
| 正确性 | no-unused-vars、no-undef | error | 必须修 |
| 安全性 | no-eval、危险正则 | error | 必须修或评审豁免 |
| 异步 | no-floating-promises | error | 补 catch/await |
| 可维护性 | 复杂度、函数长度 | warn | 逐步重构 |
| 风格 | 分号、引号、排序 | off/交给格式化 | 不参与评审 |
| 框架约定 | Hooks 依赖、Vue 规则 | warn/error | 按框架语义 |
2.4 关键数字与量级
| 指标 | 常见阈值 | 说明 |
|---|---|---|
| 新代码覆盖率 | 70%–90% | 低于阈值阻断合并 |
| 重复率 | 3%–5% | 超过后优先抽取 |
| 认知复杂度 | 单函数 ≤15 | 超过后拆分 |
| 文件长度 | 300–500 行 | 不是硬性上限,是信号 |
| 技术债比率 | ≤5% | 修复成本/开发成本 |
| 阻断级问题 | 0 | blocker/critical 不允许新增 |
3 实践
3.1 最小示例
// eslint.config.js:规则只留能阻止缺陷的部分。
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(js.configs.recommended, ...tseslint.configs.recommendedTypeChecked, {
languageOptions: {parserOptions: {projectService: true}},
rules: {'no-console': 'warn', '@typescript-eslint/no-floating-promises': 'error'},
});
{"singleQuote": true, "trailingComma": "all", "printWidth": 100}
# 本地先修可自动修复的问题,再把剩余报告交给评审
eslint . --fix
prettier --write .
sonar-scanner -Dsonar.qualitygate.wait=true
3.2 常用操作与参数
| 操作 | 命令 / 配置 | 说明 |
|---|---|---|
| 只检查不修改 | eslint . | CI 使用,避免隐式改写 |
| 自动修复 | eslint . --fix | 只应用安全修复 |
| 格式检查 | prettier --check . | CI 使用 |
| 类型检查 | tsc --noEmit | 与 lint 分开 |
| 覆盖率 | vitest run --coverage | 关注分支覆盖 |
| 质量门禁 | sonar.qualitygate.wait=true | 等待门禁结果再退出 |
3.3 标准流程
- 先用格式化工具统一风格,把它从评审中移除。
- 只启用能解释“为什么”的规则;每条 error 规则都要有修复路径。
- 本地 pre-commit 跑快速检查和自动修复。
- CI 跑全量 lint、类型检查、覆盖率和静态分析。
- 质量门禁只看新代码,存量问题进基线并排期清理。
- 误报要么改规则,要么写窄范围豁免并注明原因和到期时间。
- 每月回看规则命中率、豁免数量和债务趋势。
3.4 与相邻技术的组合
- 工具链:ESLint 与 Prettier 的版本随仓库锁定,CI 与本地一致。
- CI/CD:lint 是 PR 的第一道门禁,质量门禁在构建后执行。
- 测试:覆盖率只说明执行到,断言质量仍要靠测试评审。
- 安全:静态分析能发现部分注入/危险模式,但不替代依赖扫描。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 语言 | JS/TS / 多语言 | 决定规则生态 |
| 团队规模 | 小 / 大 | 决定门禁强度与豁免流程 |
| 存量代码 | 干净 / 债务重 | 决定是否先建基线 |
| 反馈速度 | 秒级 / 分钟级 | 决定本地与 CI 分工 |
| 合规 | 需要审计 / 不需要 | 决定报告留存与签名 |
3.6 决策规则
- 格式化只选一个工具,禁止 ESLint 与 Prettier 同时管风格。
- 新项目从严格规则集开始;老项目先冻结基线,再逐步收紧。
- 能自动修复的规则交给本地/CI 自动修,不能自动修的才进评审。
- 阻断级只留正确性、安全性和类型错误;风格与复杂度先 warn。
- 覆盖率门禁看新代码,避免用总量掩盖新空洞。
- 误报豁免必须带原因和到期日,不能永久关闭整条规则。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| ESLint + Prettier | 生态成熟、规则可插拔 | 两套配置、可能冲突 | 大多数 JS/TS 项目 |
| Biome | 格式化+lint 一体、快 | 规则生态较新 | 新项目、追求速度 |
| SonarQube | 度量、历史趋势、门禁 | 部署与维护成本 | 中大型团队、合规 |
仅 tsc | 零额外依赖、类型覆盖 | 不管风格与坏味道 | 极小项目、库 |
3.8 何时不该用
- 一次性脚本:格式化和门禁的收益低于配置成本。
- 规则全开却不修:告警疲劳会让真正的问题被忽略。
- 用覆盖率替代测试设计:高覆盖但无断言,仍然测不出缺陷。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 保存后格式反复跳动 | ESLint 与 Prettier 规则冲突 | 关闭风格规则,交给 Prettier |
| 自动修复改坏代码 | 规则修复不安全或跨作用域 | 只跑安全修复,改后跑测试 |
| 门禁因存量问题失败 | 没建基线或基线过期 | 冻结存量,只阻断新增 |
| 误报导致规则被整体关闭 | 豁免粒度太粗 | 单行豁免 + 原因 + 到期 |
| 本地与 CI 结果不同 | 版本/配置/忽略文件不一致 | 锁版本,共享 config |
| 覆盖率很高但缺陷多 | 只执行未断言,或排除关键文件 | 看分支覆盖与断言质量 |
| 安全热点长期未评审 | 没有责任人 | 指定 owner 与到期时间 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 用 lint 管格式 | 规则冲突、修复循环 | 交给格式化工具 |
| 一次性关闭整条规则 | 同类缺陷继续进入 | 窄范围豁免 |
| 追求 100% 覆盖率 | 写无断言测试 | 关注关键分支 |
| 把基线当永久豁免 | 债务永远不还 | 设清理计划 |
4.3 可观测信号
规则命中数、error/warn 比例、自动修复率、豁免数量与到期、覆盖率趋势、重复率、技术债比率、门禁通过率和平均修复时长。
4.4 安全 / 性能 / 一致性边界
- 安全:lint 不是安全扫描;危险模式、依赖漏洞和密钥泄露要各自设防。
- 性能:全量扫描超过十分钟会拖慢反馈;用增量与缓存。
- 一致性:规则版本、配置和忽略文件必须随仓库锁定,否则本地与 CI 漂移。
- 可维护性:门禁只能阻止新增问题,存量债务必须有排期。