代码规范工具怎么配才不被同事骂？

上周五晚上十一点，我正对着一个 Spring Boot 项目疯狂敲代码，突然 Git 提交失败了——pre-commit hook 报了一堆 ESLint 错误。当时我真的想砸键盘。这已经是我入职这家上市公司技术中台团队的第二个月，原以为终于可以摆脱“野路子”写法，结果发现团队里居然有人连 == 和 === 都混用……更离谱的是，区块链项目的 Java 代码里竟然出现了中文注释！

作为一个喜欢深夜 coding 的人（白天会议太多，根本没法写代码），我对这种“自由发挥”的风格忍无可忍。于是，我主动请缨，在团队内部推动一套统一的代码规范工具链。没想到，这一推，踩了不少坑，也收获了不少经验。

今天就来聊聊，在真实项目中，如何配置和落地一套既不惹人烦、又能真正提升代码质量的规范工具链。尤其是当你同时维护着传统的 Spring Boot 后端服务和新兴的区块链智能合约前端时，这套方案尤为重要。

为什么我们非要搞这些“形式主义”？

我知道，很多老程序员一听到“代码规范”就翻白眼：“能跑就行，管它格式呢？”但现实很残酷。

去年双11期间，我们一个核心支付模块因为两个开发用了不同的缩进风格（一个 tab 一个空格），合并时没注意，导致某个 if 分支被意外注释掉。虽然测试没覆盖到，但线上跑了三天才发现——还好金额不大，不然 HR 可能要找我谈话了。

更别说区块链项目了。那玩意儿一旦部署上链，几乎无法修改。你敢在智能合约里写个模糊的变量名 data？审计公司看了直接摇头。所以，规范不是为了好看，是为了保命。

而我们技术中台的定位，就是为公司十几个业务线提供稳定、可复用的基础能力。如果我们的代码都乱七八糟，别人凭什么信你？

工具选型：别贪多，够用就好

一开始我想搞个“全家桶”：ESLint + Prettier + Checkstyle + SpotBugs + SonarQube……结果被组长一句话点醒：“你这是要建 CI/CD 宇宙吗？先保证大家愿意用。”

于是我们做了精简：

• 前端（含区块链 DApp）：ESLint + Prettier + Husky
• 后端（Spring Boot）：Spotless + Checkstyle + Maven Enforcer

为什么这么选？

• ESLint 是 JavaScript 生态的事实标准，规则丰富，社区支持好。
• Prettier 负责格式化，和 ESLint 解耦，避免规则冲突。
• Husky 让 pre-commit hook 简单到一行命令。
• Spotless 是 Gradle/Maven 插件，能自动格式化 Java/Kotlin/SQL 等，比 Google Java Format 更灵活。
• Checkstyle 强制命名、复杂度等硬性规则。
• Maven Enforcer 确保 JDK 版本、依赖版本一致——这点在跨团队协作时太重要了。

至于 SonarQube？暂时没上。不是不好，而是初期成本太高，小团队维护不起。等我们把基础打牢再说。

实战配置：从“抗拒”到“真香”

前端部分：让 Prettier 和 ESLint 和平共处

很多人搞不清 ESLint 和 Prettier 的分工。简单说：ESLint 管逻辑错误和代码质量，Prettier 管空格、换行、引号这些格式问题。

我们这样配 .eslintrc.js：

module.exports = {
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended', // 如果用 TS
    'prettier' // 关键！禁用 ESLint 中与 Prettier 冲突的规则
  ],
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    '@typescript-eslint/no-explicit-any': 'error' // 区块链项目严禁 any！
  }
}

再配 .prettierrc：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

然后装 Husky：

npm install husky --save-dev
npx husky init

生成的 .husky/pre-commit 文件改成：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npm run lint-staged

再配 package.json：

{
  "scripts": {
    "lint": "eslint . --ext .js,.ts,.tsx",
    "format": "prettier --write .",
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"]
  }
}

效果？现在每次 git commit，只检查你改的文件，自动 fix 能 fix 的问题。不能 fix 的（比如用了 any），直接拦住你不让提交。既不打扰，又守住底线。

后端部分：Spring Boot 也能自动格式化

Java 开发最烦什么？缩进不一致、import 顺序乱、大括号位置打架。我们用 Spotless 一键解决。

在 pom.xml 里加：

<plugin>
  <groupId>com.diffplug.spotless</groupId>
  <artifactId>spotless-maven-plugin</artifactId>
  <version>2.40.0</version>
  <configuration>
    <java>
      <googleJavaFormat>
        <version>1.19.2</version>
        <style>AOSP</style> <!-- 更紧凑，适合屏幕小的人 -->
      </googleJavaFormat>
      <removeUnusedImports/>
      <trimTrailingWhitespace/>
      <endWithNewline/>
    </java>
  </configuration>
</plugin>

然后加个 Checkstyle 规则（我们用了简化版的阿里规约）：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <version>3.3.0</verson>
  <configuration>
    <configLocation>checkstyle/checkstyle.xml</configLocation>
    <encoding>UTF-8</encoding>
    <consoleOutput>true</consoleOutput>
    <failsOnError>true</failsOnError>
  </configuration>
</plugin>

关键来了：怎么让开发者不反感？

我们做了两件事：

1. 本地 IDE 自动同步：把 Spotless 配置导出成 IntelliJ 格式，放到项目根目录 idea-code-style.xml，新人 clone 下来直接导入，写代码时自动格式化。
2. CI 层只报错不修复：GitHub Actions 里跑 mvn spotless:check checkstyle:check，失败就阻断 PR。但本地可以用 mvn spotless:apply 一键修复。

这样，开发者在本地写代码无感，提交时自动合规，CI 严格把关——三重保险，但体验不割裂。

区块链项目的特殊考量

我们有个基于以太坊的 NFT 平台，前端用 React + ethers.js，后端是 Spring Boot + Web3j。

这里有两个坑：

1. Solidity 没有成熟的 Linter。我们只能靠 Slither 做静态分析，但它太重，不适合放 pre-commit。所以我们在 CI 里跑，只对 main 分支强制。
2. 前端 DApp 的安全要求极高。比如，禁止使用 eval、禁止动态 require、所有外部调用必须 try-catch。这些都得写进 ESLint custom rule。

我们甚至写了个自定义 rule 来检测是否用了 window.ethereum 而没做存在性检查：

// eslint-plugin-safe-web3.js
module.exports = {
  rules: {
    'check-ethereum': {
      create(context) {
        return {
          MemberExpression(node) {
            if (node.object.name === 'window' && node.property.name === 'ethereum') {
              context.report({ node, message: 'Always check window.ethereum exists!' });
            }
          }
        };
      }
    }
  }
};

上线前，这个 rule 拦住了三次潜在的用户白屏事故。产品经理再也不敢说“规范耽误开发速度”了。

团队推广：怎么让同事不拉黑你？

说实话，推行规范最大的阻力不是技术，是人。

我们组有个十年老 Java，坚决不用 Lombok，说“看不懂”。还有个前端小哥觉得 Prettier 把他心爱的分号删了，差点掀桌。

怎么办？先示弱，再给糖。

我在周会上说：“兄弟们，我知道这些工具很烦。但我被线上 bug 整怕了，求你们帮我试两周。如果影响效率，我请全组喝一周瑞幸。”

然后我做了三件事：

1. 写了一份超详细的 README，包含：
   • 为什么需要这些工具
   • 每个工具的作用（配图说明，虽然文章不能插图，但实际文档有）
   • 常见问题解答（比如“为什么我的 import 被删了？”）
2. 提供一键脚本：./setup-dev-env.sh 自动安装 Husky、配置 IDE、导入 code style。
3. 设立“豁免期”：前两周 CI 只 warning 不 fail，让大家适应。

结果？两周后，那个反对最激烈的老哥主动来找我：“你那个 Spotless 能不能也处理下 SQL 文件？我写 MyBatis 映射老对不齐。”

有时候，最好的说服，是让他自己尝到甜头。

效果如何？数据说话

推行一个月后，我们统计了几个指标：

指标	推行前	推行后	变化
PR 平均评论数（格式相关）	4.2	0.3	↓93%
代码审查时间（小时/PR）	2.1	1.4	↓33%
因格式问题导致的构建失败	12次/周	0	↓100%
新人上手时间	3天	1天	↓67%

最惊喜的是，区块链项目的审计通过率从 70% 提升到 95%。审计公司说：“你们的代码风格统一，变量命名清晰，省了我们不少时间。”

最后几句真心话

代码规范工具不是银弹，它解决不了架构问题，也写不出业务逻辑。但它能减少无谓的争论，降低协作成本，避免低级错误——尤其是在像我们这样支撑多个业务线的技术中台。

而且，当你深夜加班改 bug 时，看到整齐划一的代码，心里会莫名踏实。那种感觉，就像在暴雨夜开车，突然看到前方有路灯。

如果你也在一个混乱的项目里挣扎，不妨从一个小工具开始。不用追求完美，先让团队接受“自动格式化”这件事。剩下的，慢慢来。

毕竟，好的工程文化，都是从一次成功的 pre-commit 开始的。

（写完这篇博客，已经是凌晨两点。明天还要 review 三个 Spring Boot 微服务的 PR……希望他们没把 if 写成一行。）