简介：面向Java开发者与团队代码评审场景的阿里巴巴代码规约资料包，围绕编码规范落地、静态检查与IDE格式化配置展开，适合希望统一代码风格、减少低级缺陷的初中级开发者和技术负责人使用。压缩包共5个文件，约20.14MB，包含2份PDF规约手册、2个XML格式与模板配置文件以及1个插件压缩包，覆盖规范查阅、Eclipse与IDEA插件接入、代码模板和格式化规则配置等用途。已有488人学习下载。读者可借助详尽版与华山版手册系统梳理命名、注释、集合、并发、异常等约定，并结合插件与XML配置在开发环境中快速执行检查与自动格式化，从而把规约要求落实到日常编码和团队评审中。
1. 代码规约到底是个什么东西：为什么你写的代码别人读起来像天书
搬进一个新小区，如果每栋楼都不挂门牌号，快递员就只能一遍遍打电话让你下楼接。代码世界里，代码规约就是那套门牌号加路标：它不改变房子结不结实，但决定了别人能不能顺利找到你住哪儿、门朝哪边开。通俗地说，代码规约是一群人提前商量好的写代码习惯清单：变量怎么起名、一个方法写到多长就该拆、异常抓到之后要不要留个记录、集合初始化要不要预估容量、并发场景下哪些写法碰都不能碰。它通常以两种形态出现在你面前：一份可以逐条翻阅的代码规约文档，和一个装进编辑器里、边写边提示的代码规约插件。值得搞懂它的理由很朴素——你今天省下的那点打字时间，日后会变成同事和你自己花在“这行代码到底想干什么”上的成倍时间。
2. 为什么要有代码规约：从「能跑」到「好维护」的那道坎
写代码这件事有个很迷惑人的地方：让程序跑起来，门槛并不高；让程序在半年后还能被别人改动，门槛就一下子高了很多。代码规约存在的根本原因，就卡在这道坎上。它不解决“功能能不能实现”，它解决的是“实现完之后，这份代码还剩下多少可维护性”。一份规约手册里的条目看起来零零碎碎，其实每一条都在回答同一个问题：怎样写，才能让下一个人接手时不至于先花两天时间做考古。
2.1 代码首先是写给人看的，其次才是给机器跑的
机器对代码的容忍度极高。变量叫a、叫b、叫list1、叫list2，编译器一样能跑；一个方法写三千行，只要逻辑没错，照样能编译通过。问题在于，代码的生命周期里，真正被“写”的时间可能只占一成，剩下九成都在被读、被改、被排查。
打个比方，代码像一份需要多人接力续写的说明书。你写的那一页如果字迹潦草、术语自创、前后指代不明，后面每个人接手都得先猜你的意思，猜错了就改错地方。规约做的就是把这份说明书的书写格式统一起来：谁写都是同样的字号、同样的命名逻辑、同样的段落顺序，接棒的人不需要重新适应一套风格。
这也是为什么规约里最不起眼的那部分——命名和格式——反而是收益最直接的部分。把int a = 1改成int orderStatus = STATUS_WAIT_PAY，功能一行没变，但下一个读代码的人少了一次猜测。这种收益不会出现在任何性能报表上，却会实打实体现在每次改需求的耗时里。
还有一层容易被忽略：命名混乱会传染。一个人用temp、data、obj命名，接手的第二个人为了跟周围风格保持一致，也会继续这么叫，三个月后整个模块就变成一堆谁也说不清含义的缩写。规约的价值之一，就是在第一个人写下temp的时候，编辑器里就弹出一句提示。
2.2 规约省下的是读代码的时间这笔隐形账
很多团队在讨论要不要推行规约时，算的是“遵守规约会多花多少时间”。这个账算得没错，但只算了一半，另一半是省下来的时间，而它从不显示在任何报表里。
可以粗略拆一下读代码的时间都花在哪了：找入口、理解命名、弄懂异常分支、确认并发是否安全、判断这段逻辑是不是废弃代码。规约几乎对每一项都有针对性条目——命名规则压缩“理解命名”的时间，注释要求压缩“找入口”的时间，异常与日志条目压缩“弄懂异常分支”的时间，并发条目压缩“确认是否安全”的时间。
更现实的一笔账在排查阶段。线上出问题时，日志是唯一的现场。如果规约要求日志必须带上下文（订单号、状态值、关键参数），那排查的人打开日志就能定位到具体哪一笔请求出了岔子；如果没有这条要求，日志里只剩一行null pointer，那就只能靠猜和复现，这种时候的耗时是没法预估的。
提示：评估规约收益时，别只看代码行数或 bug 数量，看“新人接手一个模块需要几天能独立改需求”，这个指标对规约的松紧最敏感。
2.3 规约怎么从纸面走进日常：三种落地时机
一份规约如果只躺在文档里，实际执行率通常低得可怜——不是大家不想遵守，是没人会在赶进度的时候还去翻手册。所以规约必须找到“在人最需要的时候出现”的位置。常见的三个时机是：写的时候提示、提交的时候拦截、评审的时候讨论。
写的时候提示，靠的是编辑器插件，光标停在那一行就告诉你不符合哪一条；提交的时候拦截，靠的是提交前或构建阶段的自动扫描，不合规就过不去；评审的时候讨论，靠的是人和人之间的确认，主要处理工具判断不了的条目，比如注释写得对不对、这个抽象该不该拆。
下面这段代码演示的是同一段逻辑在规约下的两种写法，差别不在功能，全在可读性：
// 反例：命名靠猜 + 魔法值 + 异常被吞掉 public class DemoA { public void run(int s) { if (s == 1) { // 1 代表什么状态？只能去别处找 try { handle(); } catch (Exception e) { // 什么都不做，出问题时现场已经没了 } } } }// 正例：状态具名 + 异常留下可追溯的记录 public class OrderStatusDemo { /** 待支付 */ private static final int STATUS_WAIT_PAY = 1; private static final Logger log = LoggerFactory.getLogger(OrderStatusDemo.class); public void run(int status) { if (status == STATUS_WAIT_PAY) { try { handle(); } catch (Exception e) { // 保留状态值与异常栈，排查时不用再复现 log.warn("处理待支付订单失败, status={}", status, e); } } } }两段代码做的事完全一样：判断状态是否等于待支付，是就调用处理方法。改动只有三处——把魔法值1提成常量并写清含义、把参数名s换成status、把空 catch 换成带上下文和异常栈的日志。参数说明上，status是外部传入的订单状态码，STATUS_WAIT_PAY是它的一个已知取值，日志里的{}是占位符，避免字符串拼接带来的额外开销。
这三处改动正是规约里最典型的“低成本高回报”条目：写的时候多敲几个字符，读和排的时候少走很多弯路。
3. 一份代码规约手册里写了什么：命名、注释、集合、并发、异常五个部分
规约手册通常不厚，但条目覆盖的范围很广，因为它要管的是一份代码从起名到上线的全过程。把内容按主题拆开，大致能归到五个部分里：命名与格式、注释与文档、集合与容器使用、并发与线程、异常与日志。每个部分的“硬度”不一样，有的几乎全是机器能判定的硬规则，有的需要人来判断。
3.1 命名与格式：收益最直接、争议最小的一层
这一层是规约的入口，也是最容易被误当成规约全部的部分。命名规则通常很明确：类名用大驼峰、方法和变量用小驼峰、常量全大写加下划线、包名全小写；方法名用动词开头，布尔类型的字段别用is开头去表示非布尔含义；避免拼音和英文混写，避免单字母变量（循环计数器和临时坐标除外）。
格式方面，行宽、缩进、空行位置、括号位置这些条目看着琐碎，作用却很实在：当所有人写出来的代码长得差不多，代码评审时的注意力就能从“这个缩进怎么怪怪的”转移到“这段逻辑对不对”。格式化能自动完成的部分，就不该占用人的时间。
命名这条线还有一个隐含约定：名字要能自我解释。getUserInfoById比getInfo好，getInfo又比query好。规约不太可能规定到“什么名字算好”，但会把明显不合格的模式挡在门外，比如temp、data1、obj2这类无信息量的名字。
3.2 注释与文档：写「为什么」，别复述「是什么」
注释是规约里最容易写偏的部分。很多人写注释的习惯是把代码翻译一遍：i++; // i 自增。这种注释不但没用，还会在代码改动后变成错误的负担——改了代码忘了改注释，后来的人按注释理解就踩坑。
规约在这块的取向通常是：注释应该解释“为什么这么写”，而不是“这行在写什么”。比如一段看似多余的判空，注释里应该说明它是为了兼容某个历史数据来源；一个刻意不用某优化写法的地方，注释里应该说明原因。代码本身已经表达了“是什么”，注释要补的是代码表达不了的那部分信息：背景、约束、取舍。
对外暴露的方法和接口，规约一般会要求写清参数含义、返回值含义、可能抛出的异常，以及边界条件。这不是形式主义——调用方通常不会去读实现，只看签名和说明。说明写错了，用错接口几乎是必然的。
还有一条常被忽略：过期注释比没有注释更有害。规约里通常会有一条明确要求，代码改动时同步更新或删除失效注释。听起来是常识，但真正做到需要团队反复强调。
3.3 集合与并发：规约里最「救命」的部分
这一部分是规约里技术含量最高、也最容易翻车的地方。集合相关的条目大多围绕容量和空值：初始化集合时预估容量，避免频繁扩容带来的抖动；返回集合类型时优先返回空集合而不是null，让调用方少写一层判空；遍历过程中不要做结构性修改，需要删除元素时用迭代器或先收集再统一处理。
并发部分的条目更硬。线程池不要用默认构造，必须自己指定核心线程数、最大线程数、队列长度和拒绝策略——默认配置在流量突增时会把任务堆在无界队列里，最后的表现不是报错，而是悄无声息地越来越慢。共享变量要么加锁要么用线程安全容器，别指望“应该不会同时改”。加锁要保证多把锁的获取顺序一致，否则就是死锁的温床。定时任务和异步任务都要显式指定线程池，不要随手起一个新线程。
这些条目之所以“救命”，是因为它们违反之后的后果往往不是当场报错，而是在某个流量高峰、某个特定时序下才暴露出来。等暴露的时候，排查难度远高于写的时候多写一行配置。
3.4 异常与日志：给未来的自己留个黑匣子
异常和日志放在一起讲，是因为它们服务于同一个目的：出问题时留下可用的现场。规约在这块的条目通常集中在几个点：不要捕获异常后什么都不做，至少记录或向上抛出；不要用一个笼统的catch (Exception e)包住一大段逻辑，把能精确处理的异常分开；捕获之后要么处理，要么转换成对上层有意义的异常继续抛，别原样吞掉。
日志方面，规约一般要求：日志内容要带业务上下文（哪个用户、哪笔订单、哪个状态值），而不是只写“处理失败”；异常日志要传异常对象本身，保留堆栈，别只打印一句e.getMessage()，那个字符串经常是null；不同级别用对场景，能用warn说清的事别用error刷屏，真出问题时error级别反而被淹没。
| 主题区 | 典型条目 | 违反后的代价 | 工具能否自动检查 |
|---|---|---|---|
| 命名与格式 | 类名大驼峰、常量全大写、方法不宜过长 | 阅读成本上升，改动时易看漏 | 大部分可 |
| 注释与文档 | 对外方法写清参数与返回、删除过期注释 | 调用方按错误说明用错接口 | 部分可 |
| 集合与容器 | 初始化指定容量、返回空集合而非 null | 扩容抖动、调用方空指针 | 部分可 |
| 并发与线程 | 线程池显式配置、锁顺序一致 | 任务堆积、死锁 | 少数可 |
| 异常与日志 | 不吞异常、日志带上下文与堆栈 | 线上问题没有现场 | 部分可 |
注意：表格右侧那列很关键。能自动检查的条目靠工具守，不能自动检查的条目只能靠评审和习惯守，两类要分开管，否则会出现“插件通过了就以为万事大吉”的错觉。
4. 代码规约的三种形态：文档、插件与提交检查
同样是“代码规约”这四个字，在不同场合指的可能是完全不同的东西。有人说的是一份可以逐条翻阅的手册，有人说的是编辑器里那个会弹黄线的插件，有人说的是提交代码时拦住你的那道自动检查。三者是同一套规则的不同载体，作用范围、反馈速度、覆盖度都不一样，混为一谈就容易做出错误判断——比如以为装个插件就等于团队有了规约。
4.1 文档形态：可以逐条翻的字典
文档是规约最原始的形态，优势在于覆盖最全。工具能自动判定的规则终究是有限的，像“这个抽象该不该拆”“这段注释有没有说清为什么”“这个命名是否准确表达了业务含义”这类判断，只能靠人读、靠讨论，文档就是讨论时的共同参照物。
文档的另一个价值是“解释”。一份好的规约文档不只给出结论，还会说明条目背后的原因和适用边界。比如“不要用Executors的默认线程池”这条，文档里会解释为什么默认队列会带来堆积风险，读的人理解了原因，遇到变体场景时也能自己判断，而不是死记一条禁令。
文档形态的短板也很明显：没人会在赶进度的时候翻手册。它的作用更像是字典——不是用来通读的，是用来在争议出现时作为依据。指望靠一份文档让所有人自动写规范代码，基本不现实。
4.2 插件形态：编辑器里的即时提醒
插件把规约从“事后查”变成“写的时候就知道”。光标停在某个变量名上，编辑器标出一行提示，告诉你这条不符合哪一项规则、建议怎么改。反馈越靠近书写动作，修正成本越低——写完三千行再回头改命名，和刚写完这一行就被提醒，代价差好几倍。
插件能覆盖的主要是硬规则：命名格式、字符串比较方式、集合初始化、空指针风险点、资源未关闭、日志占位符写法等等。这类规则的共同点是判定逻辑确定，不需要理解业务意图。
插件形态的短板是“可忽略”。提示可以随手划过去，也可以整段抑制，甚至可以把规则关掉。团队里如果没有后续动作，插件很容易变成背景噪音，大家看一眼就继续写。所以插件通常不是终点，而是第一道提醒线。
4.3 提交检查形态：提交前的最后一道拦截
把自动扫描放在提交前或构建阶段，性质就变了：从建议变成拦截。这一层的配置通常是一个脚本或一个构建任务，扫描改动过的文件，命中规则就返回非零状态码，提交直接失败。
#!/usr/bin/env bash # 提交前只扫本次改动涉及的源码文件，避免全量扫描拖慢提交 set -e changed=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(java)$' || true) # 没有源码改动就直接放行 if [ -z "$changed" ]; then exit 0 fi # scan.sh 是团队封装的扫描入口，命中问题返回非零 if ! ./tools/scan.sh $changed; then echo "检测到不符合代码规约的写法，请修正后再提交" exit 1 fi这段脚本的关键点有三个。--cached表示只看已暂存的改动，--diff-filter=ACM把新增、修改、复制三类文件纳入范围，删掉的文件不必再扫。grep -E '\.(java)$'是文件类型过滤，换成其他语言只要改这里。最后那个if !是拦截逻辑，扫描脚本返回非零就阻断提交，返回零则静默通过。
参数上最需要调的是扫描范围。全量扫描动辄几分钟，开发者等两次就会开始想办法绕过，所以只扫改动文件是常见做法。另外要留一条应急通道，比如遇到紧急修复可以临时跳过，但跳过的记录要能被看到，否则通道很快就变成主路。
| 形态 | 出现位置 | 反馈速度 | 覆盖范围 | 主要短板 |
|---|---|---|---|---|
| 文档 | 手册、内部页面 | 需要主动查阅 | 全部条目 | 没人看就等于不存在 |
| 插件 | 编辑器内 | 写一行提示一行 | 可机检条目 | 提示可被随手忽略 |
| 提交检查 | 提交或构建阶段 | 提交时 | 可机检条目 | 配置不当会拖慢流程 |
三种形态不是替代关系，而是分层：文档负责解释和兜底，插件负责尽早提醒，提交检查负责守住底线。团队规模越大，越需要三层同时在位。
5. 常见误区与易混概念：代码规约、编码风格、最佳实践与静态检查
“代码规约”这个词被用得太随意，导致很多讨论其实在说不同的事。有人觉得它就是缩进和对齐，有人觉得它就是一套最佳实践合集，有人觉得装了插件就算有了规约。把这几组概念分清楚，能省掉大量无效争论。
5.1 误区：代码规约等于代码格式化
易混点在于两者都会涉及缩进、空格、换行、括号位置，看起来是一回事。之所以混，是因为很多团队推行规约的第一步就是引入自动格式化工具，做完这一步就觉得“规约已经上了”。
区分方式看范围：格式化只处理“字符怎么排布”，不处理“名字起得对不对”“异常该不该吞”“线程池怎么配”。格式化是规约里最外层、最容易自动化的那一小块，占全部条目的比例通常很小。判断一个团队有没有真的在管规约，看它有没有超出格式化的条目在落地，而不是看它有没有配置格式化工具。
5.2 误区：代码规约和编码风格指南是一码事
这两个词经常被换着用，实际指向的严格程度不同。编码风格指南偏向“偏好”，比如左括号换不换行、字段顺序怎么排，风格之间没有绝对对错，选一套统一就行。代码规约里除了这类偏好项，还包含大量有明确后果的硬性条目：资源必须关闭、线程池必须显式配置、异常不能吞。
区分方式看违反后果：违反风格指南，后果是“看起来不统一”；违反规约里的硬性条目，后果是“线上可能出问题”。讨论时如果双方对某一条争执不下，先问一句“违反它会导致什么”，答案落在审美上就归风格，落在故障上就归规约，归属清楚了，争论通常就能收敛。
5.3 误区：规约就是最佳实践大全
规约手册里的条目看起来都很“正确”，容易被理解成“把好经验全收进来”。实际上规约的定位更接近底线，而不是上限。底线意味着：这些条目必须遵守，遵守之后代码达到可维护的最低标准；它不保证你写出优雅的设计，也不解决架构层面的问题。
区分方式看条目性质：规约条目通常可判定、可检查、边界清晰，比如“不要捕获异常后什么都不做”。而“这个模块该不该拆成两个服务”“这个抽象层次是否合适”属于设计判断，不在规约的射程内。把设计问题塞进规约，只会让规约变得又长又无法执行。
5.4 误区：装了插件就等于遵守了规约
插件是提醒工具，不是执行保证。它可以被忽略、被抑制、被关掉，而且它只能覆盖可机检的条目——注释写得对不对、命名是否准确表达业务含义、这个异常处理是否合理，插件基本判断不了。
区分方式看“谁在负责”。装了插件但没人看提示、没人处理警告，等于没有规约；插件之外还有代码评审、还有提交检查、还有对不可机检条目的明确约定，才算形成闭环。工具解决的是“让人知道”，人解决的才是“让人照做”。
5.5 误区：规约条目越多、越严越专业
条目堆得越多的规约，执行率往往越低。原因很直接：条目一多，开发者记不住，插件提示刷屏，评审时也讨论不过来，最后大家的策略变成“整体忽略”。
区分方式看边际收益。一条规约如果违反后的代价很小、检查成本却很高，那它带来的更多是摩擦而不是价值。合理的做法是把条目分层：必须遵守的硬规则、建议遵守的推荐项、仅供参照的参考项，三层分开管，硬规则用工具守，推荐项靠评审提，参考项写进文档备查。这样团队知道哪些不能让，哪些可以商量。
6. 什么时候该上代码规约，什么时候别急着上
规约不是越早越好，也不是所有团队都需要同等强度。判断标准其实就一条：这份代码有多少人读。一个人写、一个人维护、活不过三个月的小脚本，上全套规约纯属自找麻烦；三个人以上协作、要长期迭代、出问题要能查，规约的收益就会迅速超过成本。
具体可以按几个信号来判断。第一个信号是“新人上手时间变长”：新同事接手一个模块要问东问西，说明命名和注释这层已经欠账了，这时候命名规则和注释要求是最该先上的。第二个信号是“线上问题排查靠猜”：日志里没有上下文、异常被吞掉，说明异常与日志这层该补了。第三个信号是“同类问题反复出现”：线程池配置错、集合没预分配、资源没关闭，这些重复出现的问题最适合固化成硬规则，交给工具守。
反过来，这几种情况别急着大动。团队只有一两个人、代码量很小，先把命名和格式统一就够，别一次上几十条规则。项目处于探索期、需求方向随时会变，先把并发和异常的硬规则立住，其余留给后面。还有一种是老项目改造，如果代码已经积累了几十万行、大量历史写法与新规约冲突，直接全量扫描会让所有人都被警告淹没——比较现实的做法是先管住新增代码，历史代码在改动时顺手修，别指望一次性还清。
我自己的血泪经验是这样的：早年在模拟项目 X 上推行规约，一上来就把能开的规则全开了，结果提交检查天天拦人，大家开始互相分享“怎么跳过检查”的办法，规约推行两周就名存实亡。后来换了个做法，只留了十几条硬规则在提交检查里，其余全降级成编辑器提示，情况立刻不一样——拦截少而准，大家愿意配合，剩下的慢慢加。
从那以后我每次给新项目配规约，都强制走一遍三步：先确认这份代码有几个人读，再挑出违反后果最重的十来条设为拦截，剩下的先只提示不阻断；跑一个月看提交记录，把误报多的规则调掉，把真的拦下过问题的规则留下。这份整理的代码规约资料——文档、插件配置、提交检查脚本三部分——我按这个思路分好了层，需要的时候把它下载下来放在手边，照着改一改就能用。
希望帮到你。
本文还有配套的精品资源，点击获取
崩溃排查指南：从弹窗到根因的完整链路)
