[这是我参与11月更文挑战的第4天，活动详情查看：2021最后一次更文挑战]()
本规范是自己基于多家公司经验，有自己开发经验也有行业规范要求，列举一些常用的场景而成文，可提供给初创团队参考使用，可根据实际开发参考
规范的目的：
现代软件架构都需要协同开发完成，高效 协作即降低协同成本，提升沟通效率，所谓无规矩不成方圆，无规范不能协作，对软件来说，适当的规范和标准绝不是 消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式 一起做事，提升协作效率。代码的字里行间流淌的是软件生命中的血液，质量的提升 是尽可能少踩坑，杜绝踩重复的坑，切实提升质量意识.
规范阅读须知:
1.规约整理了开发中较为常用的规范，并做了解释说明，其他未做详尽解释的请参考《阿里巴巴 Java 开发手册》
2.规约依次分为强制、推荐、参考三大类
一.命名规约
1.1 【强制】 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束.
1.2 【强制】 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式
1.3 【强制】类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外:(领域模型 的相关命名)DO / BO / DTO / VO等
1.4 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。
| 原文 | 正确的命名 | 不正确的命名 |
|---|---|---|
| XML HTTP request | XmlHttpRequest | XMLHTTPRequest |
| new customer ID | newCustomerId | newCustomerID |
| inner stopwatch | innerStopwatch | innerStopWatch |
| supports IPv6 on iOS? | supportsIpv6OnIos | supportsIPv6OnIOS |
1.5 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长
1.6 【强制】抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类命名以它要测试的类的名称开始，以 Test 结尾
1.7 【强制】POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误.
反例: 定义为基本数据类型Boolean isSuccess;的属性，它的方法也是isSuccess()，RPC 框架在反向解析的时候，“以为”对应的属性名称是 success，导致属性获取不到，进而抛出异常。
1.8 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用 单数形式，但是类名如果有复数含义，类名可以使用复数形式
正例: 应用工具类包名为com.**.open.util、类名为MessageUtils(此规则参考 spring 的框架结构)
不同类根据模块或业务分类放到相应的包中如下图
1.9 【推荐】如果使用到了设计模式，建议在类名中体现出具体模式.
正例:
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;
1.10 【强制】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别.
正例: CacheServiceImpl 实现 CacheService 接口
1.11 【参考】枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。
说明: 枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
正例: 枚举名字:DealStatusEnum，成员名称: SUCCESS / UNKOWN_REASON。
1.12 【参考】各层命名规约
Service/DAO层方法命名规约：
获取单个对象的方法用get做前缀。
获取多个对象的方法用list做前缀。
获取统计值的方法用count做前缀。
插入的方法用save(推荐)或insert做前缀。
删除的方法用remove(推荐)或delete做前缀。
修改的方法用update做前缀。
领域模型命名规约。
数据对象:xxxDO，xxx即为数据表名。
数据传输对象:xxxDTO，xxx为业务领域相关的名称。
展示对象:xxxVO，xxx一般为网页名称。
POJO是DO/DTO/BO/VO的统称，禁止命名成xxxPOJO。
1.13 【强制】不允许出现任何魔法值(即未经定义的常量)直接出现在代码中。
反例: String key = "Id#taobao_"+tradeId; cache.put(key, value);
1.14 【强制】long 或者 Long 初始赋值时，必须使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误解。
说明: Long a = 2l; 写的是数字的21，还是Long型的2?
1.15【推荐】不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。如:缓存相关的常量放在类: CacheConsts 下; 系统配置相关的常量放在类: ConfigConsts 下。
说明: 大而全的常量类，非得使用查找功能才能定位到修改的常量，不利于理解和维护
1.16 【推荐】如果变量值仅在一个范围内变化用 Enum 类。如果还带有名称之外的延伸属性，必须 使用 Enum 类，下面正例中的数字就是延伸信息，表示星期几
正例: public Enum { MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5), SATURDAY(6), SUNDAY(7);}
枚举值需要定义延伸属性的场景通常是要持久数据库，或者显示在界面上
二.异常处理规约
2.1 【强制】Java 类库中定义的一类 RuntimeException 可以通过预先检查进行规避，而不应该通过 catch 来处理，比如: IndexOutOfBoundsException，NullPointerException等等。
说明: 无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过 catch NumberFormatException 来实现。
正例: if (obj != null) {...}
反例: try { obj.method() } catch (NullPointerException e) {...}
判空是一个永恒的话题，只要你不确定变量是否为空，都应该判空，否则后患无穷。
2.2 【强制】异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。
说明:禁止使用异常来封装业务逻辑，业务异常应该用错误码来表示.
2.3 【强制】对大段代码进行 try-catch，这是不负责任的表现。catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理.
2.4 【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请 将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。
说明:禁止吃掉异常，吃掉异常就是捕获异常什么都没做，也没抛出，这也是不负责任的表现。是在不能处理的异常抛出去，但是得让使用方知道这种情况，这是编程提供方契约的一种方式
2,5【强制】finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。 说明:如果 JDK7 及以上，可以使用 try-with-resources 方式
说明: 永恒的资源关闭原则。
2.6【强制】不能在 finally 块中使用 return，finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句
说明:会覆盖try块里面的return语句
2.7 【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景
· 返回类型为包装数据类型，有可能是null，返回int值时注意判空。
· 反例: public int f() { return Integer 对象}; 如果为 null，自动解箱抛 NPE。
· 数据库的查询结果可能为null。
· 集合里的元素即使isNotEmpty，取出的数据元素也可能为null。
· 远程调用返回对象，一律要求进行NPE判断。
· 对于Session中获取的数据，建议NPE检查，避免空指针。
· 级联调用obj.getA().getB().getC();一连串调用，易产生NPE
说明:判空，缓存的数据，别人的数据，都要判空。
2.8【推荐】在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须 使用“错误码”;而应用内部推荐异常抛出;跨应用间 RPC 调用优先考虑使用 Result 方式，封 装 isSuccess、“错误码”、“错误简短信息”.
说明:业务异常使用Result模式，系统异常用Java原生异常。
2.9 【参考】避免出现重复的代码(Don’t Repeat Yourself)，即DRY原则。
说明: 随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是共用模块.
正例: 一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取: private boolean checkParam(DTO dto) {...}
三. 并发处理
3.1 【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯正例:
public class TimerTaskThread extends Thread {
public TimerTaskThread() {
super.setName("TimerTaskThread");
...
}
}
说明 :写代码的时候就要想到查bug的时候要用到什么信息，然后决定如何命名、打印日志等
3.2 【强制】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
说明: 一个是使用线程池缓存线程可以提高效率，另外线程池帮我们做了管理线程的事情，提供了优雅关机、interrupt等待IO的线程，饱和策略等功能.
3.3【强制】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
说明: Executors 返回的线程池对象的弊端如下:
FixedThreadPool 和 SingleThreadPool: 允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。
CachedThreadPool 和 ScheduledThreadPool: 允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM
线程池如果没有限制最大数量，线程池撑开的时候，由于内存不够或者系统配置的最大线程数超出，都会产生oom
3.4 【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为static变量，如果定义为 static，必须加锁，或者使用 DateUtils 工具类
正例: 注意线程安全，使用 DateUtils。亦推荐如下处理:
private static final ThreadLocal df = new ThreadLocal() {
@Override
protected DateFormat initialValue() {
return new SimpleDateFormat("yyyy-MM-dd");
}
};
说明: 如果是 JDK8 的应用，可以使用 Instant 代替 Date，LocalDateTime 代替 Calendar， DateTimeFormatter 代替 Simpledateformatter，官方给出的解释: simple beautiful strong immutable thread-safe
3.5【强制】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁; 能锁区块，就不要锁整个方法体; 能用对象锁，就不要用类锁
说明: 优先无锁，不用锁能解决的一定不要用锁，即使用锁也要控制粒度，越细越好
3.6 【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造 成死锁。
说明: 线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A、B、C，否则可能出现死锁
3.7 【强制】并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。
说明: 如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次 数不得小于 3 次.状态流转、维护可用余额等最好直接利用数据库的行级锁，不需要显式的加锁.
3.8 【强制】多线程并行处理定时任务时，Timer 运行多个 TimerTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题.
说明: 线程执行体、任务最上层等一定要抓住Throwable并进行相应的处理，否则会使线程终止。
3.9 【推荐】使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown 方法，线程执行代码注意 catch 异常，确保 countDown 方法可以执行，避免主线程无法执行至 await 方法，直到超时才返回结果
说明 : 注意，子线程抛出异常堆栈，不能在主线程 try-catch 到,请在try...finally语句里执行countDown方法，与关闭资源类似。
3.10 【推荐】避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一 seed 导致的性能下降。
正例: 在 JDK7 之后，可以直接使用 API ThreadLocalRandom，在 JDK7 之前，可以做到每个线程一个实例。
3.11【参考】volatile 解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题， 但是如果多写，同样无法解决线程安全问题。如果是 count++操作，使用如下类实现: AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 如果是 JDK8，推荐使用 LongAdder 对象，比 AtomicLong 性能更好(减少乐观锁的重试次数)
说明 :volatile只有内存可见性语义，synchronized有互斥语义，一写多读使用volatile就可以，多写就必须使用synchronized，fetch-mod-get也必须使用synchronized。
四.日志规约
4.1【强制】应用中不可直接使用日志系统(Log4j、Logback)中的 API，而应依赖使用日志框架 SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一
javaimport org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(Abc.class);
4.2 【强制】对 trace/debug/info 级别的日志输出，必须使用条件输出形式或者使用占位符的方 式。
说明: logger.debug("Processing trade with id: " + id + " symbol: " + symbol); 如果日志级别是 warn，上述日志不会打印，但是会执行字符串拼接操作，如果 symbol 是对象， 会执行 toString()方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。
正例: (条件)
Java
if (logger.isDebugEnabled()) {
logger.debug("Processing trade with id: " + id + " symbol: " + symbol);
}
正例: (占位符)
logger.debug("Processing trade with id: {} symbol : {} ", id, symbol);
4.3 【强制】异常信息应该包括两类信息: 案发现场信息和异常堆栈信息。如果不处理，那么通过 关键字 throws 往上抛出。
正例: logger.error(各类参数或者对象 toString + "_" + e.getMessage(), e);
打印日志一定要包含环境，否则找bug的时候日志对不上
4.3 【推荐】谨慎地记录日志。生产环境禁止输出 debug 日志;有选择地输出 info 日志;如果使 用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志
说明 :大量地输出无效日志，不利于系统性能升，也不利于快速定位错误点，写代码的时候就要想到查bug的时候怎么查，需要哪些日志，打印日志只需要打印核心内容，不要随便就把对象json序列化打印出来，如果是列表会很大
4.4 【参考】可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适 从。注意日志输出的级别，error 级别只记录系统逻辑出错、异常等重要的错误信息。如非必要，请不要在此场景打出 error 级别。
说明 ：合理利用warn级别日志，error级别日志最重要，理想情况下生产上产生的error和warn日志开发要定期的梳理。
五 .安全规约
5.1 【强制】隶属于用户个人的页面或者功能必须进行权限控制校验
说明: 防止没有做水平权限校验就可随意访问、修改、删除别人的数据，比如查看他人的私信内容、修改他人的订单。面向用户的所有服务都要有权限校验。
后端服务没有权限校验，也要有服务化平台下的调用权限管理.
5.2 【强制】用户敏感数据禁止直接展示，必须对展示数据脱敏。
说明: 查看个人手机号码会显示成:158****9119，隐藏中间 4 位，防止隐私泄露
5.3 【强制】用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入， 禁止字符串拼接 SQL 访问数据库
说明： 这条一般用代码检查工具都会检查出来。开发人员千万不要做字符串连接SQL
5.4 【强制】用户请求传入的任何参数必须做有效性验证
说明:
忽略参数校验可能导致
page size过大导致内存溢出。
恶意order by导致数据库慢查询。
任意重定向。
SQL注入。
反序列化注入。
正则输入源串拒绝服务ReDoS.
一般在框架层都要做特殊字符的过滤，包括：大于号、小于号、单引号等。
任何使用集合的时候，输入参数是集合的时候，返回是集合的时候，一定要有条数的限制，不能无限大。
5.5 【强制】在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制， 如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损
说明： 针对用户输入，一定要做防御式编程
5.6 【推荐】发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。
六.集合处理
6.1 【强制】关于 hashCode 和 equals 的处理，遵循如下规则
只要重写equals，就必须重写hashCode.
因为Set存储的是不重复的对象，依据hashCode和equals进行判断，所以Set存储的对象必须重写这两个方法。
如果自定义对象做为Map的键，那么必须重写hashCode和equals
说明: String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象作为 key 来使用
6.2 【强制】 在 subList 场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增 加、删除均产生ConcurrentModificationException 异常
6.3 【强制】ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCastException.
说明: subList 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList ，而是 ArrayList 的一个视图，对于SubList子列表的所有操作最终会反映到原列表上
6.4 【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁
反例:
| List a = new ArrayList();a.add("1");a.add("2");for (String temp : a) {if ("1".equals(temp)) {a.remove(temp);}} |
|---|
正例:
| Iterator it = a.iterator(); while (it.hasNext()) {String temp = it.next();if (删除元素的条件) {it.remove();}} |
|---|
6.5 【推荐】集合初始化时，尽量指定集合初始值大小。
说明: ArrayList尽量使用ArrayList(int initialCapacity) 初始化,预估数组大小，能够提高程序效率
6.6 【推荐】使用 entrySet 遍历 Map 类集合 KV，而不是 keySet 方式进行遍历
说明: keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出 key 所对应的 value。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效率更高。如果是 JDK8，使用 Map.foreach 方法。
6.7 【参考】 HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在开发过程中注意规避此风险。
说明 :开发程序的时候要预估使用量，根据使用量来设置初始值
七.控制语句规约
7.1 【强制】在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止;在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有
7.2 【强制】在 if/else/for/while/do 语句中必须使用大括号，即使只有一行代码，避免使用 下面的形式:if (condition) statements;
7.3 【推荐】推荐尽量少用 else， if-else 的方式可以改写成:
| if (condition) { ...return obj;}// 接着写 else 的业务逻辑代码 |
|---|
7.4 【推荐】除常用方法(如 getXxx/isXxx)等外，不要在条件判断中执行其它复杂的语句，将复 杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性.
反例:
if ((file.open(fileName, "w") != null) && (...) || (...)) { ...}
正例:
boolean existed = (file.open(fileName, "w") != null) && (...) || (...); if (existed) {
...
}
7.5 【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、 获取数据库连接，进行不必要的 try-catch 操作(这个 try-catch 是否可以移至循环体外)。
说明: 循环体内尽量不要获取资源、不要处理异常。
7.6 【参考】方法中需要进行参数校验的场景
1 .调用频次低的方法。
-
执行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
-
需要极高稳定性和可用性的方法。
-
对外提供的开放接口，不管是RPC/API/HTTP接口。
-
敏感权限入口
7.7 【参考】方法中不需要参数校验的场景
-
极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参 数检查要求。
-
底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一 台服务器中，所以 DAO 的参数校验，可以省略。
3.被声明成private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。
说明:在这个框框里，根据业务适当调整是可以的。
八.格式规约
8.1 【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行; 如果 是非空代码块则:
1.左大括号前不换行。
2.左大括号后换行。
3.右大括号前换行。
4.右大括号后还有else等代码则不换行;表示终止右大括号后必须换行
8.2 【强制】if/for/while/switch/do 等保留字与左右括号之间都必须加空格。
8.3 【强制】缩进采用 4 个空格，禁止使用 tab 字符
正例:
| public static void main(String[] args) {// 缩进 4 个空格String say = "hello";// 运算符的左右必须有一个空格int flag = 0;// 关键词 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格if (flag == 0) {System.out.println(say);}// 左大括号前加空格且不换行;左大括号后换行if (flag == 1) {System.out.println("world");// 右大括号前换行，右大括号后有 else，不用换行} else { System.out.println("ok");// 在右大括号后直接结束，则必须换行}} |
|---|
8.4 【强制】IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式， 不要使用 windows 格式。
说明 :请不要用GB字符集，换了环境总有问题，Java程序多数跑在Linux上，当然要用Unix换行符.
8.5 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。
正例: 下例中实参的"a", 后边必须要有一个空格。
method("a", "b", "c");
8.6 【推荐】方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义 之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。
8.7 【推荐】为避免代码行过长，影响阅读，将列宽限制为160个字符。
Intellij IDEA中设置列宽及格式化时自动换行（设置后，格式化代码时会自动按160的列宽进行换行）：
附1：编程风格模板
Intellij IDEA的code style模板
-
打开Editor→Code Style，点击Scheme右侧的"Manage..."按钮。
-
点击"Import..."按钮。
Idea 插件安装
请开发人员安装阿里巴巴开发规约插件p3c上传代码必须已扫描。
