我们组是怎么靠代码规范工具活下来的
去年双11前两周，我们实验室负责的电商平台后端服务突然在线上崩了。排查半天，发现是一个实习生手滑把 if (user != null) 写成了 if (user = null) —— 没错，赋值号代替了判等。虽然 Git 提交记录清清楚楚写着“修复用户登录逻辑”，但没人 review 出来。当时我盯着日志看了半小时，差点想把 MacBook 合上直接跑路。
这事之后，导师在组会上拍桌子：“再这么搞，项目验收直接挂！” 作为已经在实验室干了快两年的研二老油条，我被迫接下“整顿代码规范”的烂摊子。毕竟，全组就我一个人坚持用 Mac 写代码（Windows 只拿来测兼容性），平时还总叨叨什么“可读性”、“可维护性”——这锅不背谁背？
于是，就有了这篇血泪交织的 开发心得 和 技术分享。
别人写代码，我们写规则
一开始我以为就是加个 ESLint 就完事了。天真！我们组五个人，三个前端两个后端，技术栈横跨 Vue3、React、Node.js、Spring Boot，还有个玄学 Python 脚本天天跑数据清洗。每个人写代码风格千奇百怪：有人喜欢分号结尾，有人坚决不用；有人缩进用两个空格，有人偏爱 Tab；更别提命名规范了，“userName”、“user_name”、“usrName” 全齐了。
我试过手动 Code Review，结果每次 PR 都像在考古。上周五晚上十点，我还被叫去改一个“看似没问题但跑不通”的接口，最后发现是某人把 async/await 和 .then() 混着用，Promise 链断裂了。那一刻我真的想把键盘扔出窗户。
所以，光靠人肉检查？不可能。我们必须让机器替我们“骂人”。
选型：不是越强越好，而是能落地才好
我调研了一圈主流工具：
- ESLint / Prettier：前端标配，没得说
- Stylelint：CSS/SCSS 规范，虽然我们用 Tailwind 多，但 legacy 代码里还有不少原生样式
- Checkstyle / SpotBugs：Java 后端用，但配置复杂到劝退
- Ruff：Python 的新秀，速度快得离谱，比 flake8 快 100 倍
但光有工具不够，关键是怎么让大家愿意用。我们组有个铁律：不能增加开发负担。如果每次提交都要手动跑一堆命令，第二天肯定被删干净。
于是我搞了个“三步走”策略：
- 本地开发自动格式化（保存即修复）
- Git 提交前强制检查（pre-commit hook）
- CI 流水线兜底拦截（GitHub Actions）
这样，日常写代码无感，提交时自动修，真有人绕过本地检查，CI 也会把他打回来。产品经理催进度时，我们还能甩锅给“流水线卡住了” 😏
实战：从混乱到秩序的关键配置
下面是我们最终落地的核心配置，全是踩坑后调出来的。
前端：ESLint + Prettier + Husky
先装依赖（我们用 pnpm）：
pnpm add -D eslint prettier lint-staged husky
然后 .eslintrc.js 这样配（重点来了）：
module.exports = {
extends: [
'@vue/typescript/recommended', // 我们用 Vue3 + TS
'plugin:prettier/recommended' // 让 Prettier 接管格式
],
rules: {
// 关闭一些太严格或影响开发体验的规则
'@typescript-eslint/no-explicit-any': 'off', // 紧急情况允许 any
'prettier/prettier': ['error', { semi: false, singleQuote: true }],
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
}
}
再配 package.json 里的 lint-staged：
{
"lint-staged": {
"*.{js,ts,vue}": ["eslint --fix", "prettier --write"]
},
"scripts": {
"prepare": "husky install"
}
}
运行 pnpm prepare，Husky 自动装好。下次 git commit，只检查你改的文件，快得飞起。
后端：Spotless for Java（比 Checkstyle 友好多了）
Gradle 项目里加 plugin：
plugins {
id 'com.diffplug.spotless' version '6.25.0'
}
spotless {
java {
googleJavaFormat() // 用 Google 风格，简单粗暴
removeUnusedImports()
trimTrailingWhitespace()
endWithNewline()
}
}
然后在 CI 里加一步：
- name: Check code format
run: ./gradlew spotlessCheck
谁要是提交了不符合格式的代码，直接失败。测试同学再也不用吐槽“你们 Java 代码缩进像心电图”了。
Python：Ruff + ruff-format
Python 组的同学原本用 black + flake8，慢得要死。我安利 Ruff 后，他们惊了：
# pyproject.toml
[tool.ruff]
select = ["E", "W", "F", "I", "N"] # 错误、警告、未定义、import 规范等
ignore = ["E501"] # 忽略行长度，我们用 VS Code 自动换行
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
本地开发时，VS Code 装 Ruff 插件，保存自动格式化。CI 里一行命令搞定：
ruff check . && ruff format --check .
效果：从“天天救火”到“稳如老狗”
推行三个月后，效果立竿见影：
| 指标 | 推行前 | 推行后 |
|---|---|---|
| PR 平均 review 时间 | 45 分钟 | 18 分钟 |
| 因格式/低级错误导致的返工 | 每周 3~5 次 | 几乎为 0 |
| 新人上手速度 | 1~2 周 | 2~3 天 |
最爽的是，现在 Code Review 终于能 focus 在业务逻辑和架构设计上，而不是“你这变量名能不能别叫 a1、a2？”。
上周导师还夸我：“你们组代码现在看起来像一个团队写的。” 我表面谦虚，心里狂喜——终于不用半夜被叫起来修 == 和 === 的锅了！
一点真心话
说实话，搞代码规范工具不是为了“炫技”，而是为了活得久一点。程序员最宝贵的是注意力，别让它浪费在低级错误和风格争论上。
当然，工具只是手段，团队共识才是核心。我们组每周留 15 分钟开“规范小会”，讨论要不要加新规则、要不要放宽某条限制。比如最近大家一致同意允许在调试时用 console.log，只要上线前删掉就行——毕竟，人不是机器。
最后送大家一句我在 GitHub 上看到的话：
“Code is read far more often than it is written.”
你今天偷懒省下的那几秒，可能就是明天同事（或者未来的你自己）加班两小时的源头。
所以，别犹豫了。今晚就回去给你项目加个 ESLint 吧。
毕竟，规范不是束缚，而是自由的边界。
（写完这篇，我得赶紧去 fix 一个因为没跑 prettier 被 CI 打回来的 PR……）
评论 0