代码规范skill实战指南：从混乱到优雅的工程化解决方案

共计 2124 个字符，预计需要花费 6 分钟才能阅读完成。

背景痛点：为什么我们需要代码规范

在团队协作开发中，代码规范的不统一会导致诸多问题：

• 格式混乱 ：缩进、换行、分号等基础格式不一致，导致代码难以阅读
• 命名随意 ：变量、函数命名缺乏统一标准，增加理解成本
• 隐性 BUG：未使用严格模式导致的隐式类型转换等问题
• 维护成本 ：不同风格的代码混合，新人接手需要额外适应时间

根据统计，糟糕的代码规范会导致团队额外花费 30% 以上的 CR 时间。如何系统性地解决这些问题？我们需要一套自动化、强制性的代码规范方案。

技术方案选型

1. 静态检查工具对比

• ESLint（v8.56.0）：适用于 JavaScript/TypeScript，插件生态丰富
• TSLint（已弃用）：TypeScript 官方推荐迁移到 ESLint
• Stylelint（v16.2.1）：专攻 CSS/SCSS/Less 样式规范

建议组合：ESLint + Stylelint 覆盖全类型文件检查

2. Prettier 与 Linter 的协作

• 分工明确 ：
• Prettier 只管代码格式化
• ESLint 负责代码质量检查
• 避免冲突 ：通过 eslint-config-prettier 禁用 ESLint 中与 Prettier 冲突的规则

3. Git 钩子强制校验

使用 Husky（v9.0.11）+lint-staged（v15.2.5）实现：

// package.json 片段
{
  "husky": {
    "hooks": {"pre-commit": "lint-staged"}
  },
  "lint-staged": {"*.{js,ts}": ["eslint --fix", "prettier --write"],
    "*.{css,scss}": ["stylelint --fix"]
  }
}

完整配置示例

1. ESLint 配置（.eslintrc.js）

module.exports = {
  extends: [
    'airbnb-base',       // Airbnb 规范
    'plugin:@typescript-eslint/recommended', // TS 推荐规则
    'prettier'           // 必须放在最后
  ],
  parser: '@typescript-eslint/parser',
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    '@typescript-eslint/explicit-function-return-type': 'off', // 特殊豁免
    'import/extensions': ['error', 'ignorePackages', { ts: 'never'}]
  },
  settings: {
    'import/resolver': {
      node: {extensions: ['.js', '.ts']
      }
    }
  }
};

2. GitLab CI 自动化检查

# .gitlab-ci.yml 片段
stages:
  - test

lint:
  stage: test
  script:
    - npm run lint
  rules:
    - if: '$CI_PIPELINE_SOURCE =="merge_request_event"'  # 仅 MR 触发 

进阶优化方案

1. Monorepo 规范共享

推荐使用共享配置包：

# 创建共享包
packages/
  eslint-config/
    package.json
    index.js

# 子项目引用
{"extends": "@your-org/eslint-config"}

2. IDE 工作流优化

• VS Code 安装 ESLint/Prettier 插件
• 开启保存时自动修复：

  {
    "editor.codeActionsOnSave": {"source.fixAll.eslint": true}
  }

常见问题处理

1. 历史项目迁移

• 分阶段启用规则：

  // 先用 warning 级别
  rules: {'complex-rule': 'warn'}
  // 后续改为 error

2. 特殊规则豁免

• 文件顶部禁用：

  /* eslint-disable no-alert */
  alert('临时调试');

• 行内禁用：

  // eslint-disable-next-line no-console
  console.log(error); 

动手实验

任务 ：为 Vue3 + TypeScript 项目配置规范

1. 安装基础依赖：

   npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin \
     eslint-plugin-vue prettier eslint-config-prettier

2. 创建 .eslintrc.js：

   module.exports = {
     extends: [
       'plugin:vue/vue3-recommended',
       '@vue/typescript/recommended',
       'prettier'
     ]
   };

3. 添加 Vue 文件支持到 lint-staged：

   {
     "lint-staged": {"*.{vue,js,ts}": ["eslint --fix"]
     }
   }

结语

通过这套自动化规范方案，我们团队将 CR 时间减少了 40%，新成员上手速度提升明显。建议从新项目开始就严格实施，历史项目可以渐进式迁移。记住：好的规范应该像呼吸一样自然，而不是负担。