简介面向Java开发者的编码规范与静态检查工具合集适合个人开发者及团队在代码评审、项目规范落地和IDE配置阶段使用可解决命名随意、注释缺失、格式不统一等常见问题。压缩包共5个文件约20.14MB包含两份PDF版《阿里巴巴Java开发手册》华山版与详尽版作为规则依据以及IDEA与Eclipse两套代码规约插件和配套的格式化、代码模板XML配置可直接导入IDE实现违规即时提示与一键格式化。资源另附插件配置教程入口便于在IDE中快速完成环境接入。目前已有488人学习下载适合作为团队统一的编码标准与新人上手参考。1. 到底什么是代码规约团队里那本“没人爱读却救过命”的小册子代码规约通俗地说就是一个团队提前商量好的、关于“代码该长什么样”的共同约定——变量怎么起名、常量放在哪、一个方法最多写多长、异常抓到了能不能悄悄吞掉、日志里该写什么不该写什么。它不改变程序能不能跑起来只改变别人接手这段代码时要不要骂人。很多人第一次撞见“代码规约”这个词是在提交代码时被一条红色波浪线拦住或者在代码评审里被同事回了句“这里不符合规约”。那份被反复转发的代码规约文档、那个在编辑器里默默标黄的代码规约插件其实是同一件事的两张脸一张写给眼睛看一张交给机器查。搞懂它你就知道为什么有些代码一眼就显得“专业”有些代码跑得再对也没人敢动。2. 为什么要有代码规约从“能跑”到“能改”之间隔着什么写代码这件事有个残酷的地方第一次写出来只花一天后面被人读、被人改要花三年。而读代码的人和写代码的人往往不是同一个甚至可能是三个月后的自己。代码规约存在的全部理由都压在这条时间差上。打个比方家里的厨房。刀放哪、调料放哪没有法律规定但一个家庭如果每次做饭都重新决定一遍位置那每顿饭都要多花十分钟找东西。规约就是那套“刀在左边第二个抽屉”的约定它不提高厨艺它只是让每个进厨房的人不用重新摸索。2.1 规约解决的不是对错而是共识初学者最容易带着一种误解看规约觉得规约是在判定“这样写是错的”。实际上绝大多数规约条目在技术上都谈不上错只是不统一。一个变量叫userList还是lst还是data编译器一个都不管一个方法里写三十行还是三百行程序照样输出正确结果。但当同一个项目里三个人分别用三种叫法第四个人进来读代码时认知负担就翻了三倍。他要先花几分钟确认lst是用户列表不是日志列表再确认data是原始数据不是清洗后的数据然后才敢动手改。规约做的事是把这类“每次都要重新判断”的小决策提前一次性拍板让所有人的脑力省下来解决真正难的问题。所以你会发现规约条目读起来经常有点“琐碎”不要用拼音缩写、常量要全大写、接口方法必须写注释。这些条目单看都不重要攒在一起就变成了一种隐形的协作效率。这也是为什么大厂特别爱做这件事。一家头部互联网公司把自己内部沉淀多年的 Java 编码要求整理成公开手册之后很快成了国内流传最广的一份代码规约参考——不是因为里面有什么高深技术而是因为它把“大家吵了几百遍的问题”一次性写死了新项目直接抄答案就行。2.2 强制、推荐、参考三档约束力对应三种后果真正读懂一份代码规约文档第一件事是看它的分级。绝大多数成体系的规约都会把条目分成三档这个分级不是装饰它对应着完全不同的处理方式。强制档管的是“踩了会出事故”的条目。比如线程池不允许用工具类随手创建、集合转数组不能直接用无参的toArray()、金额计算不能用浮点数。这些东西违反了不会立刻报错但会在某个并发高峰或者某笔特殊金额上突然炸掉。强制档的特点是它拦的不是难看是隐患。推荐档管的是“这么做更好不那么做也能活”的条目。比如建议用StringBuilder拼接循环内的字符串、建议 if 语句省略不必要的 else。这类条目违反了顶多性能差一点、可读性弱一点不会造成线上故障。参考档更像是一份经验清单读它是为了少走弯路不读也不影响项目跑起来。三档混在一起看人就容易产生两种极端要么把所有条目都当法律改到怀疑人生要么觉得“反正都是建议”全都不管。正确的姿势是分开对待——强制档一条都不能放推荐档按团队现状逐步推进参考档当读物看。提示给自己的项目定规约时强制档尽量控制在二三十条以内。条目一旦超过一百条团队就会集体失效谁都记不住最后一条都执行不下去。2.3 规约管不住什么它和“代码风格”的分界线这里有个高频混淆很多人以为代码规约就是代码风格就是缩进用几个空格、括号换不换行、import 怎么排序。这部分确实归规约管但它只占很小一块而且这块通常交给格式化工具自动完成人根本不用操心。代码风格是“排版层”的事机器一秒钟能改完代码规约真正值钱的部分在“语义层”是机器只能提示、人必须动脑改的部分。举个典型例子// 风格工具不会报警但规约强制档会盯上的写法 public class OrderService { // 魔法值1 和 2 是什么意思半年后只有写的人记得 public void handle(int type) { if (type 1) { // 每次调用都新建线程池请求量一上来线程就爆 ExecutorService pool Executors.newFixedThreadPool(10); pool.submit(() - doSomething()); } } }这段代码缩进规范、命名也还过得去格式化工具会给它打满分。但规约关心的是另外两件事1这个魔法值应该定义成有名字的枚举或常量线程池不应该在方法里创建应该由统一的地方管理并显式指定队列长度和拒绝策略。这两个问题都不是“好不好看”而是“会不会在某天出事故”。所以两者的关系可以这么记代码风格决定代码看起来整不整齐代码规约决定代码改起来会不会出事。前者靠工具一键搞定后者得靠人一条条过。3. 一份代码规约文档里到底写了什么从命名到并发的五道关口一份完整的代码规约手册通常有几十页条目上百条看着吓人但归类之后其实就那么几个板块命名、常量、格式、集合、并发、异常、日志、注释。其中格式部分可以全交给工具剩下几块才是需要人真正理解的。下面挑几个最能体现“规约思维”的板块讲透。理解了这几块的判断逻辑剩下的条目你自己都能推导出来。3.1 命名与常量机器最容易扫到、人最容易吵的部分命名的规约条目看着最多其实原则只有一句让名字自己说明它是什么别让读者去猜。具体落地就是几条类名用大驼峰、方法和变量用小驼峰、常量全大写加下划线、包名全小写不用拼音、不用无意义缩写、布尔类型的变量别用is开头很多序列化框架会把isSuccess解析成success字段名对不上就是一个典型的翻车现场。常量这块的规约更实在。核心就一句不许出现魔法值。所谓魔法值就是代码里直接写死的数字或字符串读者看不出它的含义改的时候也不知道还有没有别处依赖。// 规约前三个魔法值改一处漏两处 if (status 3) { timeout 3000; } // 规约后值有名字改的时候全局搜一处 public final class OrderConst { /** 订单状态已支付 */ public static final int STATUS_PAID 3; /** 默认超时时间单位毫秒 */ public static final long DEFAULT_TIMEOUT_MS 3000L; }这段改造的价值不在“好看”在于可维护性。半年后产品说要调整超时时间规约前你得全局搜3000还得判断哪些3000是超时、哪些是端口号、哪些是长度限制规约后只改常量定义一处改完就完了。这就是规约省下来的钱。3.2 集合与并发规约真正防事故的地方如果只允许保留一个板块的规约懂行的人多半会选并发。因为命名错了顶多难读并发写错了是真的会让服务在半夜挂掉。集合这块的经典条目有几条特别值得说。第一条是初始化时指定容量。new HashMap()默认容量是 16元素一多就要反复扩容、重新哈希数据量大的时候这个开销很可观。规约建议按预估元素数量除以负载因子来算初始容量这个算法本身不重要重要的是养成“我知道这里面大概放多少东西”的习惯。第二条是Arrays.asList()的坑。它返回的是一个固定长度的视图往里面add会直接抛异常很多人第一次踩的时候一脸懵。// 踩坑写法这里 add 会抛 UnsupportedOperationException ListString list Arrays.asList(a, b); list.add(c); // 规约写法需要可变就用 ArrayList 包一层 ListString list new ArrayList(Arrays.asList(a, b)); list.add(c);并发这块的强制条目更硬。手动创建线程、用工具类无界创建线程池、在方法内部 new 线程池这几条几乎在所有成熟规约里都是红线。原因很直白线程是稀缺资源无限制创建会把机器拖垮而且出问题时你根本不知道是哪个业务创建的。规约要求线程池必须由统一的地方创建必须显式指定核心线程数、最大线程数、队列长度和拒绝策略——这四个参数少一个线上就多一个说不清的故障点。3.3 异常与日志出事后那半页黑匣子异常和日志的规约服务的对象不是写代码的人是凌晨三点被叫起来排查问题的人。异常这块最典型的强制条目是不要捕获异常后什么都不做。空 catch 块是代码里最危险的东西之一它让一个本该暴露的问题彻底消失等到数据对不上时你连线索都没有。// 危险写法异常被吞掉出问题查无此人 try { parseConfig(path); } catch (Exception e) { } // 规约写法要么处理要么包装后抛出至少留下现场 try { parseConfig(path); } catch (IOException e) { log.error(配置文件解析失败, path{}, path, e); throw new ConfigLoadException(配置加载失败: path, e); }日志这块的规约核心是“别用字符串拼接”。用占位符{}而不是拼字符串不只是写法问题拼接方式在日志级别被关闭时依然会执行字符串拼接白白消耗 CPU占位符方式在级别不满足时会直接跳过性能差别在高频日志里非常明显。还有一条常被忽略日志里不要打印敏感信息也不要把整个对象toString()打出去。前者是安全问题后者会让日志文件在几小时内涨到几个 G。3.4 同一段代码的规约前后对照把上面几块合起来看一段完整改造感受会更直接。// 规约前能跑但处处是雷 public class PayService { public String pay(String oid, double money, int t) { if (t 1) { double fee money * 0.006; System.out.println(fee: fee); return ok; } return fail; } } // 规约后参数有名字、金额用高精度、日志走门面、返回用枚举 public class PayService { private static final Logger log LoggerFactory.getLogger(PayService.class); /** 支付类型普通支付 */ private static final int PAY_TYPE_NORMAL 1; /** 费率万分之六 */ private static final BigDecimal FEE_RATE new BigDecimal(0.0006); public PayResult pay(String orderId, BigDecimal amount, int payType) { if (payType ! PAY_TYPE_NORMAL) { return PayResult.FAIL; } BigDecimal fee amount.multiply(FEE_RATE); log.info(计算手续费, orderId{}, fee{}, orderId, fee); return PayResult.SUCCESS; } }改造点逐条对应oid/money/t换成能读懂的名字double换BigDecimal因为浮点数算钱会出现0.1 0.2 ! 0.3这种经典问题System.out换成日志门面因为标准输出在生产环境里根本进不了日志文件int返回值换成枚举调用方不用猜ok和fail各自代表什么。这段代码的实际行数变多了但它的维护成本下降了。这就是规约的一个反直觉之处它经常让代码变长却让项目变轻。4. 代码规约插件怎么用把纸面约定变成编辑器里的红线规约文档最大的问题是没人读。几十页 PDF 发下去第一周大家翻两页第二周就忘了。所以真正让规约落地的从来不是文档本身而是那个在你敲代码时不停报警的代码规约插件。4.1 静态扫描插件到底在做什么静态扫描的原理不复杂它不运行你的程序只把源码解析成一棵语法树然后拿着预先写好的规则一条条比对。发现“这里有个魔法值”“这里 catch 块是空的”“这里的类名不符合大驼峰”就在编辑器里标出来。它的价值和局限都得说清楚。价值是即时反馈——你不用等到评审才被指出问题敲完就看见了改起来几乎无痛。局限是它只认形式不认意图它能告诉你这个方法有八十行但不能告诉你这八十行是不是应该拆它能发现变量叫a但不能判断a到底该叫userId还是accountId。所以正确的定位是插件负责拦住那些机械的、可以枚举的问题人负责剩下的那部分判断。指望插件把规约全包了最后一定是“全绿但依然难维护”。4.2 代码规约文档的三种读法文档不是拿来通读的是拿来查的。三种读法对应三个场景。第一种入职或接手新项目时读强制档。只读强制级别的那几十条二十分钟能过一遍目的是知道自己不能踩哪些线。推荐档和参考档这时候跳过读了也记不住。第二种写某个具体模块前查对应章节。要写并发代码了专门翻一下并发那一章要处理集合了翻一下集合那一章。带着问题读吸收率比通读高十倍。第三种代码评审出现分歧时当裁判。两个人对一个写法争论不下翻文档看有没有明确条目。有就按文档走没有就说明这条规约该补了。这是文档最容易被低估的用法——它其实是一个团队的技术仲裁依据。顺便说一句代码规约文档的版本要跟着插件规则集一起管。文档更新了插件没更新或者反过来就会出现“文档说可以、插件报红”的尴尬局面几次之后大家对两者都不信了。4.3 把满屏红变成可修清单规则集与严重级别的调整第一次给老项目接扫描插件几乎必然会看到几千条告警。这时候最忌讳的动作是“全部改成阻塞构建”那等于直接让团队停工。正确的做法是分批治理。先只把最要命的一小批规则设成阻塞其余的降级成警告让它先跑起来。!-- 扫描规则集老项目接入时的渐进式配置 -- ruleset !-- 先只卡死这几类空 catch、线程池、金额浮点 -- rule refexception.empty-catch severityblocker/ rule refconcurrency.thread-pool severityblocker/ rule refmath.float-for-money severityblocker/ !-- 命名类先降级为警告给人时间改 -- rule refnaming.variable severitywarning/ !-- 纯风格类直接关掉交给格式化工具 -- rule refformat.indent enabledfalse/ /ruleset配置里的severity决定这条规则是拦住提交还是只提示enabled决定它是否参与扫描。策略是阻塞项控制在十条以内且必须是真正的风险项风格类全部交给格式化工具不进扫描清单剩下的先警告按模块逐个清零。按这个节奏走一个中等规模的老项目通常两三周能把警告数压到可控范围。反过来一上来就全量阻塞团队会集体想办法绕过插件那就彻底白干了。5. 常见误区与易混区别规约、规范、Lint、重构到底差在哪规约这个概念被讲乱多半是因为几个近义词被混着用。下面五组是初学者最容易搞混的。5.1 误区一规约扫描全绿就等于代码质量好易混点把“没有告警”等同于“代码好”。为什么混插件的反馈太直观了绿色对勾给了一种完成感让人误以为质量已经被验证。怎么区分扫描能查的是形式查不了设计。一个类扫描全绿但承担了七八个职责一个方法零告警但嵌套了六层 if这些插件都不会说话。规约是下限不是上限——它保证代码不至于烂到没法接手不保证代码优雅。判断质量还得看职责划分、依赖方向、测试覆盖这些插件看不见的地方。5.2 误区二代码规约就是代码格式化易混点以为装个格式化工具就等于落实了规约。为什么混因为规约里确实有一节讲缩进和换行而格式化工具恰好能自动处理这一节体验太丝滑。怎么区分格式化解决的是空白字符和换行位置改完代码逻辑一字不变。规约里的强制档改的是逻辑——把浮点换成高精度、把方法内建线程池改成统一管理、把空 catch 补上日志。这些改动格式化工具一个都做不了。一句话记格式化工具改的是“空格”规约改的是“会不会出事”。5.3 误区三规约是给新人看的老手不用管易混点把规约当成新人培训材料。为什么混规约条目确实常常出现在新人文档里语气也像在教基础。怎么区分新人违反的多是命名和注释这类低危条目老手违反的往往才是高危条目——因为老手更可能写复杂并发、更可能为了“性能”手动建线程池、更可能觉得“这个异常我确定不会发生”就空着 catch。规约对老手的价值恰恰更大它约束的是经验带来的自信。而且规约是团队共识不是等级制度谁都要遵守。5.4 误区四规约和重构是一回事易混点把“按规约改代码”和“重构”混着叫。为什么混两者都表现为“改已有代码”动作上看着像。怎么区分规约改造不改变代码的外部行为也不改变结构设计它只是把写法调整到约定格式重构改变的是内部结构——拆类、抽方法、调整依赖关系行为同样不变但设计变了。举个具体的把double换成BigDecimal是规约改造把一个八百行的类拆成三个职责清晰的类是重构。顺序上一般先规约后重构因为规约改造风险低能先把地扫干净。5.5 误区五规则越多越严格效果越好易混点觉得规约条目数量代表团队水平。为什么混规约手册动辄上百条给人一种“越全越专业”的错觉。怎么区分规则的数量和执行力成反比。一百条规则的团队通常一条都执行不下去二十条规则并且真的卡在构建里的团队反而能长期维持。判断标准不是“覆盖了多少情况”而是“团队里每个人是不是都能背出最关键的十条”。规约的目标是被执行不是被收藏。6. 什么时候该用代码规约三种该上、三种该缓的场景规约不是万能药它在某些场景下收益极高在另一些场景下纯属折腾。场景建议理由三人以上、要长期维护的项目该上且强制档要卡在构建里人多必然风格分裂越早统一成本越低对外交付或需要交接的代码该上重点抓命名、注释、异常接手的不是你可读性直接决定交接成本有并发、金额、权限等敏感逻辑该上且这几类规则设为阻塞这些地方出错不是难看是事故一次性的验证脚本、数据探查代码别硬套跑完就删命名和注释的投入收不回来原型阶段、需求还在天天变缓一缓只保留命名和异常两条结构随时推倒重来此时卡格式纯属内耗个人小工具、学习 Demo别硬套读读文档就行没有协作方规约的价值主要来自协作真正需要判断的其实是中间地带。比如一个刚立项的项目我的建议是第一天就把扫描插件接上但只开三条阻塞规则空 catch、金额浮点、线程池。其余全部警告。这样新代码从第一行起就是干净的不用经历老项目那种“几千条告警慢慢还债”的痛苦。等到项目稳定了再逐季度把警告级规则往上升一级。还有一种情况值得单独说接手一个没有任何规约的老项目。这时候最错误的做法是“先全量扫描再统一整改”因为你会得到一个五千条的清单然后团队直接放弃。正确顺序是反过来——先定三条规则卡住新增代码让存量不再恶化再挑一个改动最频繁的模块做试点清零用它的效果去说服其他人。血泪经验是规约推广失败的项目九成不是因为规则不合理而是因为一上来就想一次改完。从那以后我每次给项目接扫描插件都强制自己先只开三条阻塞规则跑满两周再谈扩容。这个习惯救过我好几次也让我彻底放弃了“一次配到位”的念头。希望帮到你。本文还有配套的精品资源点击获取 代码规约落地指南：从文档约定到静态扫描与渐进治理
简介面向Java开发者的编码规范与静态检查工具合集适合个人开发者及团队在代码评审、项目规范落地和IDE配置阶段使用可解决命名随意、注释缺失、格式不统一等常见问题。压缩包共5个文件约20.14MB包含两份PDF版《阿里巴巴Java开发手册》华山版与详尽版作为规则依据以及IDEA与Eclipse两套代码规约插件和配套的格式化、代码模板XML配置可直接导入IDE实现违规即时提示与一键格式化。资源另附插件配置教程入口便于在IDE中快速完成环境接入。目前已有488人学习下载适合作为团队统一的编码标准与新人上手参考。1. 到底什么是代码规约团队里那本“没人爱读却救过命”的小册子代码规约通俗地说就是一个团队提前商量好的、关于“代码该长什么样”的共同约定——变量怎么起名、常量放在哪、一个方法最多写多长、异常抓到了能不能悄悄吞掉、日志里该写什么不该写什么。它不改变程序能不能跑起来只改变别人接手这段代码时要不要骂人。很多人第一次撞见“代码规约”这个词是在提交代码时被一条红色波浪线拦住或者在代码评审里被同事回了句“这里不符合规约”。那份被反复转发的代码规约文档、那个在编辑器里默默标黄的代码规约插件其实是同一件事的两张脸一张写给眼睛看一张交给机器查。搞懂它你就知道为什么有些代码一眼就显得“专业”有些代码跑得再对也没人敢动。2. 为什么要有代码规约从“能跑”到“能改”之间隔着什么写代码这件事有个残酷的地方第一次写出来只花一天后面被人读、被人改要花三年。而读代码的人和写代码的人往往不是同一个甚至可能是三个月后的自己。代码规约存在的全部理由都压在这条时间差上。打个比方家里的厨房。刀放哪、调料放哪没有法律规定但一个家庭如果每次做饭都重新决定一遍位置那每顿饭都要多花十分钟找东西。规约就是那套“刀在左边第二个抽屉”的约定它不提高厨艺它只是让每个进厨房的人不用重新摸索。2.1 规约解决的不是对错而是共识初学者最容易带着一种误解看规约觉得规约是在判定“这样写是错的”。实际上绝大多数规约条目在技术上都谈不上错只是不统一。一个变量叫userList还是lst还是data编译器一个都不管一个方法里写三十行还是三百行程序照样输出正确结果。但当同一个项目里三个人分别用三种叫法第四个人进来读代码时认知负担就翻了三倍。他要先花几分钟确认lst是用户列表不是日志列表再确认data是原始数据不是清洗后的数据然后才敢动手改。规约做的事是把这类“每次都要重新判断”的小决策提前一次性拍板让所有人的脑力省下来解决真正难的问题。所以你会发现规约条目读起来经常有点“琐碎”不要用拼音缩写、常量要全大写、接口方法必须写注释。这些条目单看都不重要攒在一起就变成了一种隐形的协作效率。这也是为什么大厂特别爱做这件事。一家头部互联网公司把自己内部沉淀多年的 Java 编码要求整理成公开手册之后很快成了国内流传最广的一份代码规约参考——不是因为里面有什么高深技术而是因为它把“大家吵了几百遍的问题”一次性写死了新项目直接抄答案就行。2.2 强制、推荐、参考三档约束力对应三种后果真正读懂一份代码规约文档第一件事是看它的分级。绝大多数成体系的规约都会把条目分成三档这个分级不是装饰它对应着完全不同的处理方式。强制档管的是“踩了会出事故”的条目。比如线程池不允许用工具类随手创建、集合转数组不能直接用无参的toArray()、金额计算不能用浮点数。这些东西违反了不会立刻报错但会在某个并发高峰或者某笔特殊金额上突然炸掉。强制档的特点是它拦的不是难看是隐患。推荐档管的是“这么做更好不那么做也能活”的条目。比如建议用StringBuilder拼接循环内的字符串、建议 if 语句省略不必要的 else。这类条目违反了顶多性能差一点、可读性弱一点不会造成线上故障。参考档更像是一份经验清单读它是为了少走弯路不读也不影响项目跑起来。三档混在一起看人就容易产生两种极端要么把所有条目都当法律改到怀疑人生要么觉得“反正都是建议”全都不管。正确的姿势是分开对待——强制档一条都不能放推荐档按团队现状逐步推进参考档当读物看。提示给自己的项目定规约时强制档尽量控制在二三十条以内。条目一旦超过一百条团队就会集体失效谁都记不住最后一条都执行不下去。2.3 规约管不住什么它和“代码风格”的分界线这里有个高频混淆很多人以为代码规约就是代码风格就是缩进用几个空格、括号换不换行、import 怎么排序。这部分确实归规约管但它只占很小一块而且这块通常交给格式化工具自动完成人根本不用操心。代码风格是“排版层”的事机器一秒钟能改完代码规约真正值钱的部分在“语义层”是机器只能提示、人必须动脑改的部分。举个典型例子// 风格工具不会报警但规约强制档会盯上的写法 public class OrderService { // 魔法值1 和 2 是什么意思半年后只有写的人记得 public void handle(int type) { if (type 1) { // 每次调用都新建线程池请求量一上来线程就爆 ExecutorService pool Executors.newFixedThreadPool(10); pool.submit(() - doSomething()); } } }这段代码缩进规范、命名也还过得去格式化工具会给它打满分。但规约关心的是另外两件事1这个魔法值应该定义成有名字的枚举或常量线程池不应该在方法里创建应该由统一的地方管理并显式指定队列长度和拒绝策略。这两个问题都不是“好不好看”而是“会不会在某天出事故”。所以两者的关系可以这么记代码风格决定代码看起来整不整齐代码规约决定代码改起来会不会出事。前者靠工具一键搞定后者得靠人一条条过。3. 一份代码规约文档里到底写了什么从命名到并发的五道关口一份完整的代码规约手册通常有几十页条目上百条看着吓人但归类之后其实就那么几个板块命名、常量、格式、集合、并发、异常、日志、注释。其中格式部分可以全交给工具剩下几块才是需要人真正理解的。下面挑几个最能体现“规约思维”的板块讲透。理解了这几块的判断逻辑剩下的条目你自己都能推导出来。3.1 命名与常量机器最容易扫到、人最容易吵的部分命名的规约条目看着最多其实原则只有一句让名字自己说明它是什么别让读者去猜。具体落地就是几条类名用大驼峰、方法和变量用小驼峰、常量全大写加下划线、包名全小写不用拼音、不用无意义缩写、布尔类型的变量别用is开头很多序列化框架会把isSuccess解析成success字段名对不上就是一个典型的翻车现场。常量这块的规约更实在。核心就一句不许出现魔法值。所谓魔法值就是代码里直接写死的数字或字符串读者看不出它的含义改的时候也不知道还有没有别处依赖。// 规约前三个魔法值改一处漏两处 if (status 3) { timeout 3000; } // 规约后值有名字改的时候全局搜一处 public final class OrderConst { /** 订单状态已支付 */ public static final int STATUS_PAID 3; /** 默认超时时间单位毫秒 */ public static final long DEFAULT_TIMEOUT_MS 3000L; }这段改造的价值不在“好看”在于可维护性。半年后产品说要调整超时时间规约前你得全局搜3000还得判断哪些3000是超时、哪些是端口号、哪些是长度限制规约后只改常量定义一处改完就完了。这就是规约省下来的钱。3.2 集合与并发规约真正防事故的地方如果只允许保留一个板块的规约懂行的人多半会选并发。因为命名错了顶多难读并发写错了是真的会让服务在半夜挂掉。集合这块的经典条目有几条特别值得说。第一条是初始化时指定容量。new HashMap()默认容量是 16元素一多就要反复扩容、重新哈希数据量大的时候这个开销很可观。规约建议按预估元素数量除以负载因子来算初始容量这个算法本身不重要重要的是养成“我知道这里面大概放多少东西”的习惯。第二条是Arrays.asList()的坑。它返回的是一个固定长度的视图往里面add会直接抛异常很多人第一次踩的时候一脸懵。// 踩坑写法这里 add 会抛 UnsupportedOperationException ListString list Arrays.asList(a, b); list.add(c); // 规约写法需要可变就用 ArrayList 包一层 ListString list new ArrayList(Arrays.asList(a, b)); list.add(c);并发这块的强制条目更硬。手动创建线程、用工具类无界创建线程池、在方法内部 new 线程池这几条几乎在所有成熟规约里都是红线。原因很直白线程是稀缺资源无限制创建会把机器拖垮而且出问题时你根本不知道是哪个业务创建的。规约要求线程池必须由统一的地方创建必须显式指定核心线程数、最大线程数、队列长度和拒绝策略——这四个参数少一个线上就多一个说不清的故障点。3.3 异常与日志出事后那半页黑匣子异常和日志的规约服务的对象不是写代码的人是凌晨三点被叫起来排查问题的人。异常这块最典型的强制条目是不要捕获异常后什么都不做。空 catch 块是代码里最危险的东西之一它让一个本该暴露的问题彻底消失等到数据对不上时你连线索都没有。// 危险写法异常被吞掉出问题查无此人 try { parseConfig(path); } catch (Exception e) { } // 规约写法要么处理要么包装后抛出至少留下现场 try { parseConfig(path); } catch (IOException e) { log.error(配置文件解析失败, path{}, path, e); throw new ConfigLoadException(配置加载失败: path, e); }日志这块的规约核心是“别用字符串拼接”。用占位符{}而不是拼字符串不只是写法问题拼接方式在日志级别被关闭时依然会执行字符串拼接白白消耗 CPU占位符方式在级别不满足时会直接跳过性能差别在高频日志里非常明显。还有一条常被忽略日志里不要打印敏感信息也不要把整个对象toString()打出去。前者是安全问题后者会让日志文件在几小时内涨到几个 G。3.4 同一段代码的规约前后对照把上面几块合起来看一段完整改造感受会更直接。// 规约前能跑但处处是雷 public class PayService { public String pay(String oid, double money, int t) { if (t 1) { double fee money * 0.006; System.out.println(fee: fee); return ok; } return fail; } } // 规约后参数有名字、金额用高精度、日志走门面、返回用枚举 public class PayService { private static final Logger log LoggerFactory.getLogger(PayService.class); /** 支付类型普通支付 */ private static final int PAY_TYPE_NORMAL 1; /** 费率万分之六 */ private static final BigDecimal FEE_RATE new BigDecimal(0.0006); public PayResult pay(String orderId, BigDecimal amount, int payType) { if (payType ! PAY_TYPE_NORMAL) { return PayResult.FAIL; } BigDecimal fee amount.multiply(FEE_RATE); log.info(计算手续费, orderId{}, fee{}, orderId, fee); return PayResult.SUCCESS; } }改造点逐条对应oid/money/t换成能读懂的名字double换BigDecimal因为浮点数算钱会出现0.1 0.2 ! 0.3这种经典问题System.out换成日志门面因为标准输出在生产环境里根本进不了日志文件int返回值换成枚举调用方不用猜ok和fail各自代表什么。这段代码的实际行数变多了但它的维护成本下降了。这就是规约的一个反直觉之处它经常让代码变长却让项目变轻。4. 代码规约插件怎么用把纸面约定变成编辑器里的红线规约文档最大的问题是没人读。几十页 PDF 发下去第一周大家翻两页第二周就忘了。所以真正让规约落地的从来不是文档本身而是那个在你敲代码时不停报警的代码规约插件。4.1 静态扫描插件到底在做什么静态扫描的原理不复杂它不运行你的程序只把源码解析成一棵语法树然后拿着预先写好的规则一条条比对。发现“这里有个魔法值”“这里 catch 块是空的”“这里的类名不符合大驼峰”就在编辑器里标出来。它的价值和局限都得说清楚。价值是即时反馈——你不用等到评审才被指出问题敲完就看见了改起来几乎无痛。局限是它只认形式不认意图它能告诉你这个方法有八十行但不能告诉你这八十行是不是应该拆它能发现变量叫a但不能判断a到底该叫userId还是accountId。所以正确的定位是插件负责拦住那些机械的、可以枚举的问题人负责剩下的那部分判断。指望插件把规约全包了最后一定是“全绿但依然难维护”。4.2 代码规约文档的三种读法文档不是拿来通读的是拿来查的。三种读法对应三个场景。第一种入职或接手新项目时读强制档。只读强制级别的那几十条二十分钟能过一遍目的是知道自己不能踩哪些线。推荐档和参考档这时候跳过读了也记不住。第二种写某个具体模块前查对应章节。要写并发代码了专门翻一下并发那一章要处理集合了翻一下集合那一章。带着问题读吸收率比通读高十倍。第三种代码评审出现分歧时当裁判。两个人对一个写法争论不下翻文档看有没有明确条目。有就按文档走没有就说明这条规约该补了。这是文档最容易被低估的用法——它其实是一个团队的技术仲裁依据。顺便说一句代码规约文档的版本要跟着插件规则集一起管。文档更新了插件没更新或者反过来就会出现“文档说可以、插件报红”的尴尬局面几次之后大家对两者都不信了。4.3 把满屏红变成可修清单规则集与严重级别的调整第一次给老项目接扫描插件几乎必然会看到几千条告警。这时候最忌讳的动作是“全部改成阻塞构建”那等于直接让团队停工。正确的做法是分批治理。先只把最要命的一小批规则设成阻塞其余的降级成警告让它先跑起来。!-- 扫描规则集老项目接入时的渐进式配置 -- ruleset !-- 先只卡死这几类空 catch、线程池、金额浮点 -- rule refexception.empty-catch severityblocker/ rule refconcurrency.thread-pool severityblocker/ rule refmath.float-for-money severityblocker/ !-- 命名类先降级为警告给人时间改 -- rule refnaming.variable severitywarning/ !-- 纯风格类直接关掉交给格式化工具 -- rule refformat.indent enabledfalse/ /ruleset配置里的severity决定这条规则是拦住提交还是只提示enabled决定它是否参与扫描。策略是阻塞项控制在十条以内且必须是真正的风险项风格类全部交给格式化工具不进扫描清单剩下的先警告按模块逐个清零。按这个节奏走一个中等规模的老项目通常两三周能把警告数压到可控范围。反过来一上来就全量阻塞团队会集体想办法绕过插件那就彻底白干了。5. 常见误区与易混区别规约、规范、Lint、重构到底差在哪规约这个概念被讲乱多半是因为几个近义词被混着用。下面五组是初学者最容易搞混的。5.1 误区一规约扫描全绿就等于代码质量好易混点把“没有告警”等同于“代码好”。为什么混插件的反馈太直观了绿色对勾给了一种完成感让人误以为质量已经被验证。怎么区分扫描能查的是形式查不了设计。一个类扫描全绿但承担了七八个职责一个方法零告警但嵌套了六层 if这些插件都不会说话。规约是下限不是上限——它保证代码不至于烂到没法接手不保证代码优雅。判断质量还得看职责划分、依赖方向、测试覆盖这些插件看不见的地方。5.2 误区二代码规约就是代码格式化易混点以为装个格式化工具就等于落实了规约。为什么混因为规约里确实有一节讲缩进和换行而格式化工具恰好能自动处理这一节体验太丝滑。怎么区分格式化解决的是空白字符和换行位置改完代码逻辑一字不变。规约里的强制档改的是逻辑——把浮点换成高精度、把方法内建线程池改成统一管理、把空 catch 补上日志。这些改动格式化工具一个都做不了。一句话记格式化工具改的是“空格”规约改的是“会不会出事”。5.3 误区三规约是给新人看的老手不用管易混点把规约当成新人培训材料。为什么混规约条目确实常常出现在新人文档里语气也像在教基础。怎么区分新人违反的多是命名和注释这类低危条目老手违反的往往才是高危条目——因为老手更可能写复杂并发、更可能为了“性能”手动建线程池、更可能觉得“这个异常我确定不会发生”就空着 catch。规约对老手的价值恰恰更大它约束的是经验带来的自信。而且规约是团队共识不是等级制度谁都要遵守。5.4 误区四规约和重构是一回事易混点把“按规约改代码”和“重构”混着叫。为什么混两者都表现为“改已有代码”动作上看着像。怎么区分规约改造不改变代码的外部行为也不改变结构设计它只是把写法调整到约定格式重构改变的是内部结构——拆类、抽方法、调整依赖关系行为同样不变但设计变了。举个具体的把double换成BigDecimal是规约改造把一个八百行的类拆成三个职责清晰的类是重构。顺序上一般先规约后重构因为规约改造风险低能先把地扫干净。5.5 误区五规则越多越严格效果越好易混点觉得规约条目数量代表团队水平。为什么混规约手册动辄上百条给人一种“越全越专业”的错觉。怎么区分规则的数量和执行力成反比。一百条规则的团队通常一条都执行不下去二十条规则并且真的卡在构建里的团队反而能长期维持。判断标准不是“覆盖了多少情况”而是“团队里每个人是不是都能背出最关键的十条”。规约的目标是被执行不是被收藏。6. 什么时候该用代码规约三种该上、三种该缓的场景规约不是万能药它在某些场景下收益极高在另一些场景下纯属折腾。场景建议理由三人以上、要长期维护的项目该上且强制档要卡在构建里人多必然风格分裂越早统一成本越低对外交付或需要交接的代码该上重点抓命名、注释、异常接手的不是你可读性直接决定交接成本有并发、金额、权限等敏感逻辑该上且这几类规则设为阻塞这些地方出错不是难看是事故一次性的验证脚本、数据探查代码别硬套跑完就删命名和注释的投入收不回来原型阶段、需求还在天天变缓一缓只保留命名和异常两条结构随时推倒重来此时卡格式纯属内耗个人小工具、学习 Demo别硬套读读文档就行没有协作方规约的价值主要来自协作真正需要判断的其实是中间地带。比如一个刚立项的项目我的建议是第一天就把扫描插件接上但只开三条阻塞规则空 catch、金额浮点、线程池。其余全部警告。这样新代码从第一行起就是干净的不用经历老项目那种“几千条告警慢慢还债”的痛苦。等到项目稳定了再逐季度把警告级规则往上升一级。还有一种情况值得单独说接手一个没有任何规约的老项目。这时候最错误的做法是“先全量扫描再统一整改”因为你会得到一个五千条的清单然后团队直接放弃。正确顺序是反过来——先定三条规则卡住新增代码让存量不再恶化再挑一个改动最频繁的模块做试点清零用它的效果去说服其他人。血泪经验是规约推广失败的项目九成不是因为规则不合理而是因为一上来就想一次改完。从那以后我每次给项目接扫描插件都强制自己先只开三条阻塞规则跑满两周再谈扩容。这个习惯救过我好几次也让我彻底放弃了“一次配到位”的念头。希望帮到你。本文还有配套的精品资源点击获取