简介：围绕阿里巴巴Java开发手册整理的代码规约配套资料包，面向Java后端开发者、团队技术负责人以及需要统一编码规范的高校学生与初级工程师，解决团队代码风格不一致、命名与集合使用随意、异常与并发处理缺少约束等常见问题。压缩包共5个文件，约20.14MB，主体是两份PDF手册：华山版与详尽版，分别满足快速查阅与逐条细读的需要；另有p3c-formatter、eclipse-codestyle.xml、eclipse-codetemplate.xml及EclipseFormatter.zip等配置类文件，用于在Eclipse与IDEA中采用统一的格式化模板和代码检查插件。已有488人学习下载。读者可以借助这份资料完成从规范理解到工具落地的完整过程：先通过手册掌握命名、常量、集合、并发、注释等条目的判定标准与反例，再借助代码风格文件与模板，让团队成员在保存代码时即符合约定，减少Code Review中的格式争议，也适合作为新人入职培训与项目规范落地的参考材料。

1. 一套代码规约真正的价值，在于它能不能卡住提交

上个月帮一个团队看流水线为什么老是红，日志里躺着四十多条静态扫描告警，全是空指针风险和线程池没关闭这类老问题。聊下来发现，这套代码规约的文档他们打印出来读过三遍，插件一个没装，构建里一个检查没配，规矩全停留在纸面上。这份资源其实是三件套：规约文档给判断标准，代码规约插件负责在敲代码时当场提醒，规则包负责在合并前兜底。它适合 Java 后端团队、刚接手老项目要立规矩的人、以及要给团队做规范培训的负责人；不适合单文件脚本、一次性数据处理这种本来就不需要工程化约束的场景。下面按文档怎么读、插件怎么装、流水线怎么接、坑在哪的顺序走一遍，每一步都能直接抄。

2. 代码规约文档怎么读：十二个章节与三级严重度的对号入座

拿到一份代码规约文档，最常见的错误是从第一页开始逐条背。背到并发章节基本就放弃了，因为前面的命名规约还没消化完。这份文档的正确打开方式是按「触达频率 × 事故成本」排优先级，而不是按目录顺序。

2.1 按改动频率排序，先读每天都会碰到的四章

文档主体一般拆成命名风格、常量定义、代码格式、OOP 规约、日期时间、集合处理、并发处理、控制语句、注释规约、异常处理、日志规约、单元测试、安全规约这十几块。真正需要优先吃透的是命名、集合、并发、异常四章，因为它们几乎出现在每个类里，而且是代码评审时最容易吵起来的地方。

这张表的意思是：命名和格式类条款交给工具，人的注意力放在集合、并发、异常这三块。文档里关于集合的条款大多在讲「初始化指定容量」「不要在 foreach 里做 remove」，这类问题用眼睛看代码很难发现，必须靠静态扫描，所以读的时候要顺手记下哪些条款是机器能查的。

再说安全规约。它触达频率最低，一年可能就碰上一次，但碰上就是事故。我的习惯是把它单独摘出来做成一份上线前 checklist，不塞进日常 review 清单里，因为日常 review 没人会认真看。

2.2 三级严重度的实际边界：Blocker 到底拦什么

文档给每条规则标了 Blocker、Critical、Major 三级，很多人以为这是按「重要程度」排的，其实它对应的是「处理策略」。Blocker 指的是会导致运行期错误、资源泄漏、并发死锁、安全漏洞的条款，处理策略是零容忍，不许提交；Critical 是局部逻辑隐患和可维护性问题，允许在标注技术债单号的前提下短期放行；Major 是风格类，历史代码一次性整改，新代码必须遵守。

团队落地时最容易翻车的地方，是把所有规则都当 Blocker 用。历史项目一开扫描，几千条告警铺满屏幕，第二天插件就被卸载了。比较稳的做法是分级映射到构建策略：Blocker 设成失败，Critical 设成告警，Major 只出报告不拦人。

提示：这个映射关系要写进团队 README，不然新人和 CI 的预期永远对不上。规则包升级时优先看 Blocker 级别有没有新增，那是唯一值得开紧急会讨论的部分。

2.3 把条款翻译成可检查的条目

文档读完的产出不应该是一份笔记，而应该是一张「谁检查、怎么检查、能不能自动修」的对照表。下面这张表是我在几个项目里沉淀下来的常用条目，可以直接改成自己团队的版本。

表格右边那一列很关键：能被工具自动发现的条款，就别浪费人力在 review 里逐行看；不能被工具发现的条款，才需要写进 review 清单。很多团队把这两类混在一起，结果是 review 时既看格式又看逻辑，效率极低。

具体执行顺序我一般这么排：先在全量代码上跑一遍扫描，导出一份基线报告；统计告警数量最多的前十条规则；拿这十条做一次半小时的团队分享；把历史遗留目录和自动生成代码加进排除清单；最后约定新代码零新增。这五步走完，规约才算从文档变成了团队共识。跳过基线报告直接卡点，基本等于逼团队关插件。

3. 代码规约插件怎么装、怎么配：从实时红线到一键全量扫描

文档解决的是「知道该怎么做」，插件解决的是「写的时候别忘」。这一步的落地成本最低，但顺序最容易搞错——很多人先配了 CI 再装插件，结果开发者本地看不到问题，流水线一报错就是几十条，体验极差。

3.1 版本对不上是装不上的头号原因

插件市场里搜「代码规约」或者「code guidelines」，能搜到对应条目，但装的时候提示不兼容，八成是 IDE 大版本对不上。IDE 的 build 号第一位数字对应年份末位、后面跟大版本号，插件页面会写兼容区间，对不上就只能找历史版本或者离线包。

内网环境没法直连插件市场，走离线安装。先确认 IDE 的版本和配置目录，再决定把 zip 包放到哪。

# 查看 IDE 安装版本，build.txt 里形如 IU-233.11799.300 cat /opt/idea*/build.txt 2>/dev/null || true # 配置目录：Linux 在 ~/.config/JetBrains，macOS 在 ~/Library/Application Support/JetBrains ls -d ~/.config/JetBrains/*/ 2>/dev/null \ || ls -d ~/Library/Application\ Support/JetBrains/*/ 2>/dev/null

build.txt里的233对应 2023.3，插件兼容区间就是按这个前缀判断的。配置目录下的plugins子目录是插件落盘位置，卸载后如果菜单还在、功能异常，多半是这里留了残包，删掉对应目录重启即可。离线包的安装入口是 Settings → Plugins → 齿轮菜单 → Install Plugin from Disk，选中 zip 后重启。

3.2 三种扫描入口，作用域决定耗时

插件装好后有三个扫描入口：单个文件右键、整个包右键、整个模块右键。它们的检查逻辑一样，区别只在作用域，而作用域直接决定耗时。一个中型模块第一次全量扫描跑三五分钟很正常，第二次开始走增量缓存，通常十几秒。

第一次扫描之前，先把不该扫的目录排除掉，否则报告里一半是噪音：

• target/、build/这类编译产物目录
• 代码生成器产出的generated-sources
• 前端工程里的node_modules
• 第三方 SDK 拷贝进来的源码包

排除入口在 Settings → Editor → Inspections → 规约规则分组右侧的排除项，也可以在项目结构里把目录标记为 Excluded。这一步做完再扫描，报告才有参考价值。

3.3 规则开关与严重度覆盖：关规则要有边界

团队总会遇到几条「我们不接受」的规则，比如某些命名缩写规范跟内部框架冲突。正确的做法是把规则降级或者关掉，并且把这份配置提交到仓库共享，而不是每个人在自己机器上无视告警。IDE 的检查配置可以导出成 xml，放在项目的.idea/inspectionProfiles/下。

<!-- .idea/inspectionProfiles/team-guidelines.xml 检查项 ID 以本地插件实际注册的为准，在 Settings → Inspections 里能看到 --> <component name="InspectionProjectProfileManager"> <profile version="1.0" name="team-guidelines"> <option name="myName" value="team-guidelines" /> <!-- 阻断级：命名不合规直接标红 --> <inspection_tool class="NamingConventionInspection" enabled="true" level="ERROR" /> <!-- 提醒级：注释缺失只标黄，不阻断编译 --> <inspection_tool class="CommentConventionInspection" enabled="true" level="WARNING" /> <!-- 历史模块整体不查，范围要写清楚，别全项目一刀切 --> <inspection_tool class="CollectionConventionInspection" enabled="false" level="WARNING" /> </profile> </component>

class属性是检查项的唯一标识，填错不会报错，只是不生效，所以改完要随手打开一个违规文件验证一下。level决定显示颜色和是否计入错误数，ERROR会影响部分团队的提交前检查，WARNING只标黄。enabled="false"是完全不查，我的建议是只在遗留模块上这么干，并且把模块名写进注释，半年后回头清理时才知道当时为什么关。

配置文件提交到仓库后，其他人拉下来在 Inspections 面板切换到team-guidelines这个 profile 即可复用。注意只提交 profile 文件，别提交workspace.xml，那里面全是个人窗口布局，冲突起来非常难受。

4. 接进构建：让规约在合并前而不是上线后报错

本地插件靠自觉，流水线靠强制。这一章解决的是「怎么让不合规的代码进不了主干」，同时不把构建时间拖垮。

4.1 为什么用规则包而不是自己写正则脚本

有人会想，写个 grep 脚本查一下命名不就完了。命名确实能查，但规约里真正值钱的条款都跟语法结构有关，比如「不要在 foreach 里 remove 元素」「线程池必须手动创建」「catch 块不能为空」，这些用正则会写出大量误报，维护成本比收益高得多。

规则包的底层是基于抽象语法树的静态分析，规则以 XPath 或者 Java 类的形式挂在 AST 节点上，能准确区分「在循环体内调用了 remove」和「在循环外调用了 remove」。代价是每次扫描要解析源码，构建时间会增加，所以接入节奏要控制：第一阶段只出报告不拦人，第二阶段只拦增量代码，第三阶段才全量卡点。

4.2 在构建里挂规则集：配置片段与路径确认

以 Maven 项目为例，把规则包作为插件依赖挂进pom.xml。下面的坐标是占位写法，groupId和artifactId换成你手上规则包的真实坐标，版本号统一提到 properties 里管理。

<properties> <!-- 规则包版本、文档版本、插件版本三者要一起升级，见 6.2 --> <guidelines.version>2.1.0</guidelines.version> </properties> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>pmd-maven-plugin</artifactId> <version>3.21.2</version> <configuration> <!-- 路径是规则包 jar 内部的 classpath 路径，不是磁盘路径 --> <rulesets> <ruleset>rulesets/java/naming.xml</ruleset> <ruleset>rulesets/java/collection.xml</ruleset> <ruleset>rulesets/java/concurrent.xml</ruleset> <ruleset>rulesets/java/exception.xml</ruleset> </rulesets> <!-- 观察期设 false，只出报告；收敛期之后再改 true --> <failOnViolation>false</failOnViolation> <printFailingErrors>true</printFailingErrors> <!-- 不扫测试代码，测试里的断言和命名规则本来就不一样 --> <includeTests>false</includeTests> <targetJdk>${maven.compiler.source}</targetJdk> </configuration> <executions> <execution> <id>guidelines-check</id> <!-- 放 verify 而不是 validate，避免每次编译都跑一遍 --> <phase>verify</phase> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>

rulesets这一项是最容易报错的地方，路径写错会直接抛「Unable to find ruleset」。路径是相对规则包 jar 根目录的 classpath 路径，不是你自己项目的目录。确认方法是从本地仓库把 jar 拆开看一眼：

# 先让 Maven 把依赖拉下来，再看 jar 里 xml 的真实路径 mvn -q dependency:resolve JAR=$(ls ~/.m2/repository/your/groupId/coding-guidelines-pmd/*/*.jar | head -n 1) jar tf "$JAR" | grep -i '\.xml$' | head -n 20

输出里形如rulesets/java/naming.xml的才是该填的值，带META-INF前缀的那些是插件描述文件，别填进去。targetJdk要跟项目实际的编译级别一致，填高了会把用了新语法的代码误判成错误，填低了则部分规则不生效。

4.3 阈值与失败策略：先统计，再卡点

直接把failOnViolation设成 true 是团队接入失败率最高的操作。历史代码几千条告警，构建必红，红两周大家就习惯了，卡点彻底失效。分三段走：观察期跑全量出报告，收敛期只卡本次变更的文件，卡点期再全量开。

收敛期的关键是拿到变更文件列表，只对改动部分做检查：

# 取本次分支相对主干的变更 Java 文件 git diff --name-only origin/main...HEAD -- '*.java' > changed.txt # 没有变更就跳过，否则插件会退化成全量扫描 if [ -s changed.txt ]; then FILES=$(paste -sd, changed.txt) mvn -q pmd:check -Dpmd.includes="$FILES" else echo "no java changes, skip guidelines check" fi

pmd.includes接受逗号分隔的相对路径，文件多的时候命令行参数会超长，超过几千个文件就改成分片执行或者直接用文件列表参数。参数名在不同插件版本里可能是includes，升级后先在本地跑一次确认没有静默失效——静默失效是最坑的，构建绿了但根本没扫。

还有一个细节：增量检查只覆盖「改动的文件」，如果某个文件里原本就有历史告警，一改动就会全部暴露出来，等于逼着顺手清理。这个副作用大部分时候是好事，但要在团队里提前说清楚，否则会被当成工具抽风。

5. 避坑：五条踩过的坑和对应解法

这一章全是血泪经验，按「现象 → 原因 → 解决」写，遇到过的可以直接对号入座。

坑一：本地插件报的问题，流水线上一条都没有。现象是开发者本地一片红，CI 全绿。原因是插件版本和规则包版本不一致，插件内置的规则集是旧的，构建用的是新的。解决方式是把三个版本号（IDE 插件、规则包、文档）写进项目 README，升级时一起动，并且在 CI 里打印实际加载的规则集清单，日志里能直接看到扫了哪几个 xml。

坑二：Lombok 生成的 getter 被报「缺少注释」「字段未使用」。现象是加了@Data的类满屏告警。原因是静态分析在注解处理之前跑，看不到生成的代码。解决方式是确认 IDE 的 Annotation Processing 已开启，同时在检查配置里把「未使用字段」这类结构类检查针对 Lombok 注解做排除；构建侧则把规则集里跟字段访问相关的规则单独摘出来，不要一刀切关掉整个命名分组。

坑三：一开扫描全红，第二天插件被卸载。现象是历史项目接入当天告警破千，团队集体无视。原因是没做基线，直接把新项目的标准套在老代码上。解决方式是先出基线报告存进仓库，把遗留包和自动生成目录排除，只对新增和改动文件卡点，历史债按模块排期清理，一次清一个包。

坑四：构建时间从三分钟涨到十二分钟。现象是接入后流水线明显变慢。原因通常是插件绑在了validate阶段，每次编译都跑一遍全量扫描。解决方式是把执行阶段挪到verify，includeTests设成 false，并且开启增量；规则集也别全量挂，按 4.2 里的方式只挂实际用得上的几组。

坑五：规则集路径报错，换了几种写法都不对。现象是构建抛Unable to find ruleset。原因是把磁盘路径或者 jar 文件名当成了 classpath 路径。解决方式是用jar tf列出 jar 内部的 xml 文件，照着输出原样填，注意大小写和前缀；如果规则包是通过dependency引入的，确认 scope 不是provided，否则在 CI 环境里根本不在 classpath 上。

注意：这五条里有三条跟版本和路径有关，本质上都是「配置没有版本化」。把规则包版本、规则集清单、检查配置一起纳入仓库管理，能省掉后面一大半的沟通成本。

6. 进阶：把通用规约裁成团队自己的那一份

通用规约解决的是及格线问题，真正好用的团队规约一定是在它基础上裁剪过的。裁剪不等于删规则，而是把团队踩过的坑固化成新规则。

6.1 用 XPath 加一条自己的规则

规则包支持自定义 XPath 规则，适合那种「通用规约没写、但我们团队踩过」的场景。比如约定 Controller 里不许直接 new 线程池，必须走统一的配置类：

<!-- rulesets/java/team-custom.xml --> <ruleset name="team-custom" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"> <description>团队自定义规则</description> <rule name="NoNewThreadPoolInController" language="java" message="Controller 中禁止直接创建线程池，统一从 ThreadPoolConfig 获取" class="net.sourceforge.pmd.lang.rule.XPathRule"> <priority>2</priority> <properties> <property name="xpath"> <value><![CDATA[ //ClassOrInterfaceDeclaration[ends-with(@Image, 'Controller')] //AllocationExpression[ClassOrInterfaceType[@Image='ThreadPoolExecutor']] ]]></value> </property> </properties> </rule> </ruleset>

XPath 分两段：前半段定位类名以Controller结尾的类声明，ends-with是 XPath 2.0 函数，PMD 6 默认走 1.0 解析器时要用contains(@Image, 'Controller')替代；后半段找该类里所有new ThreadPoolExecutor的分配表达式。priority取 1 到 5，对应 Blocker 到 Info，这里设 2 表示严重但不阻断。写完挂进 4.2 的rulesets列表里，跑一次mvn pmd:check验证，报语法错误优先怀疑 XPath 版本不匹配，而不是表达式写错。

自定义规则最容易犯的错是写得太宽。比如上面这条如果去掉Controller限定，就会把工具类里的正常创建也报出来，误报三次以上团队就会要求关掉它。

6.2 版本对齐与升级流程

规则包、IDE 插件、文档三者版本必须一起走。我的做法是在仓库根目录放一张小表，谁升级谁填：

升级流程固定成四步：拉新版本到分支跑全量扫描，导出与旧版本的告警差异，团队评审新增的 Blocker 级告警，确认无误后合并并把版本号写进上表。跳过差异评审直接升级，最容易出现的情况是某条规则收紧了，第二天全组的构建一起红，而没人知道是哪次升级带来的。

从那以后我每次接新项目，第一件事不是装插件，而是先跑一遍全量扫描、把基线报告存进仓库，再决定哪些规则现在就卡、哪些先观察。这个习惯帮我省掉了至少三次「上线前一天才发现构建卡住」的翻车。希望帮到你。

本文还有配套的精品资源，点击获取