代码质量工具链

代码质量不是靠自觉,而是靠工具在提交前把问题拦住。

三层防线

  1. 编辑器:实时提示类型与规范问题
  2. 提交前:lint-staged 只检查改动文件
  3. CI:全量类型检查、测试与构建

ESLint

ESLint 负责发现潜在错误与不推荐的写法。

pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-vue

eslint.config.js:

import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import pluginVue from 'eslint-plugin-vue'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  ...pluginVue.configs['flat/recommended'],
  {
    rules: {
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      '@typescript-eslint/no-explicit-any': 'warn'
    }
  }
]

Prettier

Prettier 负责格式,ESLint 负责逻辑与规范,两者职责不要混用。

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "none"
}

TypeScript

  • 开启 strict
  • 为接口响应、组件 props、事件定义类型
  • CI 中执行 vue-tsc --noEmit,不要只依赖编辑器
  • 避免用 as any 掩盖问题

提交前检查

使用 husky + lint-staged:

{
  "lint-staged": {
    "*.{ts,vue}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

只在改动文件上执行,保证提交速度。

CI 检查

pnpm typecheck
pnpm lint
pnpm test
pnpm build

四项全部通过才允许合并。构建检查能发现类型检查覆盖不到的问题,例如环境变量缺失、资源路径错误。

风格约定

  • 命名表达意图,避免 data、info、temp
  • 函数保持单一职责,超过 50 行考虑拆分
  • 组件按「容器 / 展示」区分
  • 注释解释「为什么」,而不是复述「做了什么」
  • 删除无用代码,不要靠注释保留历史

常见误区

  1. 规则开得太多但没人修,最后全部关闭
  2. 只在本地跑 lint,CI 不校验
  3. 用 eslint-disable 绕过问题而不记录原因
  4. 格式化与 lint 规则冲突,反复互相覆盖
  5. 类型定义与实际接口脱节,any 遍地

落地顺序

  1. 先接入 TypeScript 与 Prettier
  2. 再引入 ESLint,规则从少量开始
  3. 加提交前检查
  4. 最后接入 CI,形成闭环
  5. 规则逐步收紧,避免一次性改造导致大面积阻塞