构建统一开发规则库：从ESLint、Husky到团队工程化实践

1. 项目概述一个开发者规则库的诞生在软件开发这个行当里干了十几年我越来越觉得一个团队或者一个项目的长期健康很大程度上不取决于用了多牛的技术栈而在于那些看不见摸不着的“规矩”。我说的规矩就是代码规范、提交约定、分支策略、文档要求这些开发规则。它们就像城市的交通法规没有的时候大家凭着感觉走短期看好像挺“高效”但项目规模稍微一大或者人员一流动各种“交通事故”——比如合并冲突、代码风格混乱、线上Bug追溯困难——就会接踵而至。sungurerdim/dev-rules这个项目就是我个人为了解决这个问题而长期维护的一个“规则库”。它不是一个可以直接运行的软件而是一个高度结构化、可配置的规则集合旨在为软件开发团队提供一套开箱即用、又可灵活裁剪的工程实践指南。你可以把它理解为一个“最佳实践”的模板仓库里面包含了从代码提交、分支管理、代码审查到自动化检查等各个环节的规则定义和配套工具配置。这个项目的核心价值在于“统一”和“自动化”。它试图将那些散落在口头约定、陈旧文档或者个人习惯中的规则变成机器可读、可执行的配置。这样一来新成员 onboarding 时不再是听老员工讲半天“我们这里大概是怎么做的”而是直接克隆这个规则库运行几个命令他的本地环境和认知就与团队标准对齐了。对于老成员它则是一个不断演进、持续优化的“团队共识”的具象化体现减少了在代码风格、Git操作等琐事上的无谓争论。2. 核心设计理念与架构拆解2.1 为什么需要一个独立的规则库很多团队会把规则写在 Wiki 里或者放在项目根目录的CONTRIBUTING.md文件中。这当然比没有强但存在几个明显问题难以执行文字规则依赖人工记忆和自觉遵守在赶进度时极易被忽视。难以同步当规则更新时无法有效通知到所有相关方容易形成信息差。难以集成无法与开发工具链如 IDE、Git、CI/CD深度集成实现自动化检查。sungurerdim/dev-rules的设计初衷就是要解决这些问题。它的核心思想是“配置即规则”。我们将规则转化为具体的配置文件如.eslintrc.js,.prettierrc,commitlint.config.js,.husky/等并辅以清晰的文档说明。这些配置文件本身就可以被版本控制管理修改即更新克隆即应用。2.2 规则库的模块化架构为了保持灵活性和可维护性这个规则库采用了模块化的设计。它不是一个大而全的、必须全盘接受的庞然大物而是一套可以按需取用的“乐高积木”。核心模块通常包括代码规范模块这是基础。包含了针对不同语言如 JavaScript/TypeScript, Python, Go的 lint 规则和格式化配置。例如对于前端项目会提供集成了 Airbnb、Standard 等流行规范的 ESLint 配置以及匹配的 Prettier 格式化配置。Git 工作流模块定义了团队协作的基石。包括分支策略例如基于main或master、develop、feature/*、hotfix/*的 Git Flow 变体或者更简单的 GitHub Flow。会提供分支命名规范和生命周期说明。提交信息规范采用类似 Conventional Commits 的格式如feat:,fix:,docs:并集成commitlint和husky在提交时进行验证。合并请求Pull Request模板标准化 PR 描述要求填写改动背景、测试情况、关联事项等提升代码审查效率。自动化检查与钩子模块利用 Git Hooks通过 Husky 管理在关键节点自动执行规则。例如pre-commit在提交前自动运行代码格式化Prettier和基础 lint 检查确保进入版本库的代码风格一致。commit-msg使用 commitlint 检查提交信息格式是否符合规范。pre-push在推送前运行更完整的测试或构建防止有问题的代码进入远程仓库。工程化配置模块提供通用的配置文件模板如.editorconfig统一编辑器基础配置、.gitignore、CI/CD 流水线配置文件如 GitHub Actions, GitLab CI 的模板、Dockerfile 模板等。文档与流程模块包含README.md、CONTRIBUTING.md、CHANGELOG.md的模板以及团队内部的技术决策记录ADR模板将开发流程也文档化、规范化。注意模块化设计的关键在于“松耦合”。每个模块应尽可能独立通过清晰的README说明其作用和安装方式让团队可以只引入需要的部分比如一个纯后端团队可能暂时不需要前端的 ESLint 配置。2.3 技术选型背后的考量选择哪些工具来承载这些规则是项目设计的关键。我的选型原则是主流、稳定、社区活跃、可配置性强。代码检查与格式化对于 JavaScript/TSESLintPrettier是事实标准。ESLint 负责代码质量如未使用的变量、错误的语法Prettier 负责代码风格缩进、分号、引号。两者通过eslint-config-prettier解决规则冲突。对于其他语言会选择对应的主流工具如 Python 的black和flake8Go 的gofmt和golangci-lint。Git Hooks 管理Husky是目前最流行的方案。它简化了 Git Hook 的安装和管理并且其新版本v7的配置方式非常直观直接写在package.json或独立的配置文件中易于版本化管理。提交信息规范Commitlint与 Husky 是黄金搭档。它使用一组可配置的规则通常基于commitlint/config-conventional来校验提交信息格式强制养成清晰提交的习惯。配置管理所有配置均使用标准文件格式JS, JSON, YAML。一个重要的技巧是大量使用extends字段。例如ESLint 配置可以继承自某个共享配置然后在此基础上进行微调。这为规则库的“基础版本”和项目的“具体定制”提供了清晰的分离层。3. 核心模块深度解析与实操配置3.1 Git 工作流与提交规范的落地细节这是规则库中最能立竿见影提升团队协作效率的部分。光说“要用特性分支”和“提交信息要清晰”是没用的必须通过工具将其固化。3.1.1 分支策略的具体实现我通常推荐一种简化版的 Git Flow它平衡了流程的严谨性和操作的简便性main生产就绪分支。任何合并到这里的代码都必须经过完整的 CI/CD 流水线测试并且打上版本标签Tag。develop集成测试分支。所有新功能在完成开发后合并至此分支进行集成测试。feature/*功能分支。从develop检出前缀为feature/后接简短描述如feature/user-auth。release/*发布分支。从develop检出用于版本发布的最后测试和小修小补完成后合并回develop和main。hotfix/*热修复分支。从main检出用于紧急线上 Bug 修复完成后合并回develop和main。在规则库中我会提供一个详细的GIT_WORKFLOW.md文档用图表和示例说明每种分支的创建、合并时机和操作命令。3.1.2 提交规范的自动化这是通过 Husky Commitlint 实现的。以下是具体的配置步骤和原理安装依赖npm install --save-dev husky commitlint/config-conventional commitlint/cli # 或使用 yarn/pnpm启用 Huskynpx husky init这个命令会在项目根目录创建.husky文件夹并添加pre-commit示例钩子。配置 Commitlint在根目录创建commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional], rules: { type-enum: [ 2, always, [feat, fix, docs, style, refactor, test, chore, revert] ], subject-case: [0] // 不限制 subject 的大小写 } };这里继承了常规配置并自定义了允许的type类型。2表示错误必须遵守1表示警告0表示关闭。添加 commit-msg 钩子npx husky add .husky/commit-msg npx --no -- commitlint --edit ${1}这行命令创建了一个钩子文件在每次执行git commit时都会用 commitlint 去校验我们输入的提交信息。实操心得一开始团队可能会觉得这种约束很麻烦。我的经验是在项目初期就引入并辅以简短的培训解释清晰提交信息对自动化生成 CHANGELOG、快速定位问题的重要性。一旦习惯你会发现git log变得无比清晰用git log --oneline --grep^fix就能快速找到所有修复提交。3.2 代码检查与格式化的无缝集成代码风格争论是团队内耗的一大源头。用工具代替口水是唯一解。3.2.1 ESLint 与 Prettier 的协同工作很多人会混淆两者的职责。简单来说ESLint 是“找茬”的发现问题Prettier 是“理发”的格式化代码。它们需要配合但不能打架。基础安装与配置npm install --save-dev eslint prettier eslint-config-prettier eslint-plugin-prettierESLint 配置.eslintrc.js关键点在于让 ESLint 的格式化规则“闭嘴”把格式化的活完全交给 Prettier。module.exports { env: { browser: true, es2021: true, }, extends: [ eslint:recommended, // ESLint 推荐规则 plugin:typescript-eslint/recommended, // TS 推荐规则 prettier, // 必须放在最后禁用所有与 Prettier 冲突的 ESLint 规则 ], parser: typescript-eslint/parser, plugins: [typescript-eslint], rules: { // 这里可以添加或覆盖团队特定的规则 no-console: warn, // 例如警告 console.log }, };Prettier 配置.prettierrc这是一个非常主观的配置规则库提供的是一个经过多数项目验证的、可读性较高的起点。{ semi: true, trailingComma: es5, singleQuote: true, printWidth: 100, tabWidth: 2, endOfLine: lf }集成到 Git 工作流修改.husky/pre-commit钩子在提交前自动格式化并检查。#!/usr/bin/env sh . $(dirname $0)/_/husky.sh npx lint-staged然后配置package.json中的lint-staged只对暂存区的文件进行操作效率极高。{ lint-staged: { *.{js,ts,jsx,tsx}: [prettier --write, eslint --fix --max-warnings0] } }提示eslint --fix只能修复一部分问题主要是代码质量问题而prettier --write则负责所有格式化。这个顺序很重要。--max-warnings0表示将警告视为错误强制保持代码清洁。3.2.2 针对不同项目的配置继承规则库的核心优势在于可复用。我会在规则库的根目录下创建configs/文件夹里面存放各种基础配置。configs/eslint-base.js: 最基础的 ESLint 配置。configs/eslint-typescript.js: 继承了 base并添加了 TS 相关配置。configs/prettier-base.json: 基础的 Prettier 配置。在一个新项目中安装规则库或复制配置文件后项目的.eslintrc.js只需要一行module.exports require(your-org/dev-rules/configs/eslint-typescript);然后如果项目有特殊规则可以在此基础上扩展module.exports { ...require(your-org/dev-rules/configs/eslint-typescript), rules: { ...require(your-org/dev-rules/configs/eslint-typescript).rules, my-custom-rule: error } };这种方式实现了规则的“中央管理”和“本地定制”的完美结合。4. 规则库的部署与团队适配流程4.1 初始化将规则库应用到新项目对于一个全新的项目应用dev-rules应该是项目创建后的第一步。我设计了一个简单的初始化脚本scripts/init.js或使用plop这样的脚手架工具其核心步骤包括环境检查检查 Node.js 版本、包管理器npm/yarn/pnpm等。配置文件复制将规则库中预定义的配置文件如.eslintrc.js,.prettierrc,.husky/,commitlint.config.js,.editorconfig复制到项目根目录。这里要注意处理路径和可能的变量替换。依赖安装根据项目类型前端/后端/全栈自动安装对应的开发依赖devDependencies。例如一个 TS 前端项目会安装eslint,prettier,typescript,husky,lint-staged,commitlint/cli等一系列包。Git 钩子安装运行npm run prepare或husky install确保.husky目录下的钩子脚本被正确安装到项目的.git/hooks中。生成基础文档将README.md,CONTRIBUTING.md的模板填充项目基本信息后生成。这个过程可以通过一条命令完成例如npx your-org/dev-rules init极大降低了新项目的规范接入成本。4.2 增量更新规则库的版本化与同步规则不是一成不变的。随着技术演进和团队经验积累规则需要更新。我们将dev-rules本身作为一个版本化的 NPM 包或 Git 子模块来管理。作为 NPM 包发布这是最推荐的方式。将配置文件和脚本打包发布到私有或公共 NPM 仓库。项目通过package.json依赖它。优点版本控制清晰依赖管理方便更新时项目只需升级包版本。更新流程在dev-rules仓库中修改配置测试无误后发布新版本如v1.1.0。在各个项目中运行npm update your-org/dev-rules。项目可能需要根据更新日志CHANGELOG调整自己的扩展配置如果基础配置有破坏性变更。作为 Git 子模块Submodule或子仓库Subtree适合希望直接引用配置文件原始版本且更新不那么频繁的场景。优点直接链接到源文件更透明。缺点更新和同步流程相对复杂需要团队成员了解 Git 子模块操作。实操心得无论采用哪种方式必须维护清晰的 CHANGELOG。每次规则库更新都要详细说明变更内容、原因以及对现有项目的影响是向后兼容的增强还是需要项目适配的破坏性变更。这能极大减少同步更新时的混乱。4.3 团队文化适配规则不是枷锁引入规则库最大的挑战不是技术而是人。开发者尤其是资深开发者可能对“被约束”感到不适。我的经验是自上而下推行自下而上优化需要团队领导或技术负责人的支持和率先使用。同时规则库本身应该开放给所有开发者提交改进建议通过 Issue 或 PR让每个人都有参与感规则是“我们”的不是“我”的。解释“为什么”每一条规则都应该有据可循。在规则注释或配套文档中解释这条规则是为了避免什么问题如某个特定的 Bug、提升什么效率如自动生成日志、符合什么社区共识。理解背后的原因能增加认同感。提供“逃生舱”允许在极其特殊的情况下通过添加注释如// eslint-disable-next-line来临时禁用某条规则。但必须要求注明理由。这给了开发者灵活性同时也通过代码审查来监督这种特权的使用。渐进式采用不要试图一次性把所有规则强加给一个老项目。可以从最无争议的 Prettier 格式化和 commitlint 开始让团队先体验到自动化带来的便利如不再争论缩进再逐步引入更严格的 lint 规则。5. 常见问题排查与效能提升技巧5.1 典型问题速查表在推广和使用dev-rules的过程中我遇到了不少共性问题这里列出一个速查表问题现象可能原因解决方案husky钩子不执行1..husky目录未正确初始化。2. 钩子脚本没有执行权限。3. 项目不是 Git 仓库。1. 运行npx husky init重新初始化。2. 在 Unix 系统运行chmod x .husky/*。3. 运行git init。commitlint报错但信息格式看起来对1. 可能包含了不符合规范的type。2.subject首字母未大写如果规则开启。3. 配置文件中extends路径错误。1. 检查commitlint.config.js中type-enum的配置。2. 使用commitlint --edit .git/COMMIT_EDITMSG调试。3. 检查配置文件是否存在、语法是否正确。pre-commit时lint-staged报错1.lint-staged未安装或版本不匹配。2.lint-staged配置的 glob 模式未匹配到文件。3. 被调用的命令如eslint在项目内未安装。1. 重新安装lint-staged。2. 检查package.json中lint-staged的路径模式。3. 确保所有 lint 工具都已作为 devDependency 安装。ESLint 和 Prettier 规则冲突1. ESLint 配置未正确扩展prettier配置来禁用冲突规则。2. 安装或配置顺序有误。1. 确保eslint-config-prettier在extends数组的最后。2. 参考上文3.2.1的配置顺序重新检查。规则库更新后项目 CI 失败1. 新规则更严格发现了原有代码中的问题。2. 基础配置有破坏性变更项目本地覆盖规则未同步调整。1. 根据报错信息批量修复代码或暂时降低规则级别如 error - warn。2. 仔细阅读规则库的 CHANGELOG调整项目本地配置。5.2 效能提升与高级技巧IDE/编辑器集成规则库可以配套提供主流编辑器VSCode, WebStorm的推荐配置片段在.vscode/settings.json或.idea/目录中。例如配置保存时自动格式化、在编辑器中实时显示 ESLint 错误。这能将反馈周期从“提交时”提前到“编码时”体验提升巨大。与 CI/CD 深度集成在 Git 钩子之外必须在 CI 流水线中再次执行规则检查。例如在 GitHub Actions 中添加一个lint任务运行npm run lint。这确保了即使有人本地跳过了钩子有问题的代码也无法合并到主分支。可以将 lint 结果以注释形式反馈到 PR 中更直观。自定义规则开发当团队遇到一些特定领域的坏味道时可以开发自己的 ESLint 插件或 Commitlint 规则。例如禁止直接使用console.log必须使用封装的日志函数或者要求修改数据库的提交必须关联特定的type如db:。将这些自定义规则也纳入dev-rules包中管理。性能优化对于大型项目lint-staged和 ESLint 可能变慢。可以使用eslint的--cache选项。确保lint-staged只对真正改变的文件类型执行对应的命令。对于巨型单体仓库可以考虑将 lint 任务拆分成并行作业。6. 从规则库到研发效能平台sungurerdim/dev-rules的终极形态不仅仅是一个静态的配置集合。在实践中我逐渐将其扩展为一个轻量级的“研发效能平台”的基石。它的思想可以渗透到研发的更多环节标准化项目脚手架基于规则库的配置可以快速生成不同类型项目React 组件库、Node.js 微服务、全栈应用的脚手架。使用plop或自定义的 CLI 工具问答几个问题就能生成一个完全符合团队规范、配置齐全、开箱即用的项目骨架。自动化代码审查清单在 PR 模板中不仅包含描述字段还可以内嵌一个检查清单Checklist例如[ ] 代码是否遵循了 ESLint/Prettier 规则[ ] 是否添加或更新了单元测试[ ] 是否更新了相关文档[ ] 本次改动是否会影响公共 API 这能引导开发者进行自我审查也方便 Reviewer 聚焦重点。度量与改进利用 Git 历史可以分析团队在提交规范、代码质量上的遵守情况。例如统计不符合规范的提交比例、高频出现的 lint 错误类型。这些数据不是用来惩罚而是用来发现流程中的薄弱环节并针对性优化规则或提供培训。维护这样一个规则库前期确实需要投入不少精力去搭建和磨合。但长期来看它节省的是整个团队在代码风格争论、低级错误排查、新人培养上的巨大隐性成本。它让开发者能将更多精力集中在真正的业务逻辑和创新上而不是纠结于缩进用空格还是制表符。当团队的新成员能在第一天就提交出格式完美、信息清晰的代码时你会觉得这一切都是值得的。这不仅仅是工具的胜利更是一种高效、规范的工程文化的建立。