https://github.com/singgel?tab=repositories
一、编程规约
(一) 命名规约
6.【强制】抽象类命名使用 Abstract 或 Base 开头 ; 异常类命名使用 Exception 结尾 ; 测试类命名以它要测试的类的名称开始,以 Test 结尾。
7.【强制】中括号是数组类型的一部分,数组定义如下: String[] args;
反例:使用 String args[] 的方式来定义。
11.【推荐】如果使用到了设计模式,建议在类名中体现出具体模式。
说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计思想。
正例:
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;
12.【推荐】接口类中的方法和属性不要加任何修饰符号 (public 也不要加 ) ,保持代码的简洁性,并加上有效的 Javadoc 注释。尽量不要在接口里定义变量,如果一定要定义变量,肯定是与接口方法相关,并且是整个应用的基础常量。
正例:接口方法签名: void f();
接口基础常量表示: String COMPANY = ” alibaba ” ;
反例:接口方法定义: public abstract void f();
说明: JDK 8 中接口允许有默认实现,那么这个 default 方法,是对所有实现类都有价值的默认实现。
13.接口和实现类的命名有两套规则:
1 ) 【强制】对于 Service 和 DAO 类,基于 SOA 的理念,暴露出来的服务一定是接口,内部的实现类用 Impl 的后缀与接口区别。
正例: CacheServiceImpl 实现 CacheService 接口。
2 ) 【推荐】 如果是形容能力的接口名称,取对应的形容词做接口名 ( 通常是– able 的形式 ) 。
正例: AbstractTranslator 实现 Translatable 。
15.【参考】各层命名规约:
A) Service / DAO 层方法命名规约
1 ) 获取单个对象的方法用 get 做前缀。
2 ) 获取多个对象的方法用 list 做前缀。
3 ) 获取统计值的方法用 count 做前缀。
4 ) 插入的方法用 save( 推荐 ) 或 insert 做前缀。
5 ) 删除的方法用 remove( 推荐 ) 或 delete 做前缀。
6 ) 修改的方法用 update 做前缀。
B) 领域模型命名规约
1 ) 数据对象: xxxDO , xxx 即为数据表名。
2 ) 数据传输对象: xxxDTO , xxx 为业务领域相关的名称。
3 ) 展示对象: xxxVO , xxx 一般为网页名称。
4 ) POJO 是 DO / DTO / BO / VO 的统称,禁止命名成 xxxPOJO 。
(二)常量定义
3.【推荐】不要使用一个常量类维护所有常量,应该按常量功能进行归类,分开维护。如:缓存相关的常量放在类: CacheConsts 下 ; 系统配置相关的常量放在类: ConfigConsts 下。
说明:大而全的常量类,非得使用查找功能才能定位到修改的常量,不利于理解和维护。
4.【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
1） 跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
2） 应用内共享常量：放置在一方库的 modules 中的 constant 目录下。
反例： 易懂变量也要统一定义成应用内共享常量，两位攻城师在两个类中分别定义了表示“是”的变量：
类 A 中： public static final String YES = “yes”;
类 B 中： public static final String YES = “y”;
A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致产生线上问题。
3） 子工程内部共享常量：即在当前子工程的 constant 目录下。
4） 包内共享常量：即在当前包下单独的 constant 目录下。
5） 类内共享常量：直接在类内部 private static final 定义。
(三) 格式规约
8.【强制】 IDE 的 text file encoding 设置为 UTF -8 ; IDE 中文件的换行符使用 Unix 格式,不要使用 windows 格式。
(四) OOP 规约
2.【强制】所有的覆写方法,必须加@ Override 注解。
反例: getObject() 与 get 0 bject() 的问题。一个是字母的 O ,一个是数字的 0,加@ Override可以准确判断是否覆盖成功。另外,如果在抽象类中对方法签名进行修改,其实现类会马上编译报错。
4.【强制】对外暴露的接口签名,原则上不允许修改方法签名,避免对接口调用方产生影响。接口过时必须加@ Deprecated 注解,并清晰地说明采用的新接口或者新服务是什么。
6.【强制】 Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
正例： “test”.equals(object);
反例： object.equals(“test”);
说明： 推荐使用 java.util.Objects#equals （ JDK7 引入的工具类）
7.【强制】所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。
说明： 对于 Integer var=?在-128 至 127 之间的赋值， Integer 对象是在IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。示例如下：
Integer i1 = 123;
Integer i2 = 123;
System.out.println(i1==i2);
Integer i3 = 129;
Integer i4 = 129;
System.out.println(i3==i4);
System.out.println(i3.equals(i4));
int i5 = 130;
int i6 = 130;
System.out.println(i5==i6);输出：
true
false
true
true8.【强制】关于基本数据类型与包装数据类型的使用标准如下：
1） 所有的 POJO 类属性必须使用包装数据类型。
2） RPC 方法的返回值和参数必须使用包装数据类型。
3） 所有的局部变量【 推荐】 使用基本数据类型。
说明： POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何NPE 问题，或者入库检查，都由使用者来保证。
正例： 数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。
反例： 比如显示成交总额涨跌情况，即正负 x%， x 为基本数据类型，调用的 RPC 服务，调用不成功时，返回的是默认值，页面显示： 0%，这是不合理的，应该显示成中划线-。所以包装数据类型的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。
9.【强制】定义 DO / DTO / VO 等 POJO 类时,不要设定任何属性默认值。
反例: POJO 类的 gmtCreate 默认值为 new Date(); 但是这个属性在数据提取时并没有置入具体值,在更新其它字段时又附带更新了此字段,导致创建时间被修改成当前时间。
10.【强制】序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败； 如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
说明： 注意 serialVersionUID 不一致会抛出序列化运行时异常。
13.【推荐】使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
说明：
String str = “a,b,c,,”;
String[] ary = str.split(“,”);
//预期大于 3，结果是 3
System.out.println(ary.length);
15.【推荐】 类内方法定义顺序依次是:公有方法或保护方法 > 私有方法 > getter / setter方法。
说明:公有方法是类的调用者和维护者最关心的方法,首屏展示最好 ; 保护方法虽然只是子类关心,也可能是“模板设计模式”下的核心方法 ; 而私有方法外部一般不需要特别关心,是一个黑盒实现 ; 因为方法信息价值较低,所有 Service 和 DAO 的 getter / setter 方法放在类体最后。
17.【推荐】循环体内，字符串的联接方式，使用 StringBuilder 的 append 方法进行扩展。
反例：
String str = “start”;
for(int i=0; i<100; i++){
str = str + “hello”;
}
说明： 反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。
20.【推荐】类成员与方法访问控制从严：
1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
2） 工具类不允许有 public 或 default 构造方法。
3） 类非 static 成员变量并且与子类共享，必须是 protected。
4） 类非 static 成员变量并且仅在本类使用，必须是 private。
5） 类 static 成员变量如果仅在本类使用，必须是 private。
6） 若是 static 成员变量，必须考虑是否为 final。
7） 类成员方法只供类内部调用，必须是 private。
8） 类成员方法只对继承类公开，那么限制为 protected。
说明： 任何类、方法、参数、变量，严控访问范围。过宽泛的访问范围，不利于模块解耦。
思考：如果是一个 private 的方法，想删除就删除，可是一个 public 的 Service 方法，或者一个 public 的成员变量，删除一下，不得手心冒点汗吗？变量像自己的小孩，尽量在自己的视
线内，变量作用域太大，如果无限制的到处跑，那么你会担心的。
(五)集合处理
1.【强制】 关于 hashCode 和 equals 的处理，遵循如下规则：
1） 只要重写 equals，就必须重写 hashCode。
2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
3） 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals。
正例： String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象作为 key 来使用。
2.【强制】 ArrayList 的 subList 结果不可强转成 ArrayList ,否则会抛出 ClassCastException异常: java . util . RandomAccessSubList cannot be cast to java . util . ArrayList ;
说明: subList 返回的是 ArrayList 的内部类 SubList ,并不是ArrayList ,而是ArrayList 的一个视图,对于 SubList 子列表的所有操作最终会反映到原列表上。
3.【强制】 在 subList 场景中,高度注意对原集合元素个数的修改,会导致子列表的遍历、增加、删除均产生ConcurrentModificationException 异常。
4.【强制】使用集合转数组的方法,必须使用集合的 toArray(T[] array) ,传入的是类型完全一样的数组,大小就是 list . size() 。
反例:直接使用 toArray 无参方法存在问题,此方法返回值只能是 Object[] 类,若强转其它类型数组将出现 ClassCastException 错误。
正例:
List list = new ArrayList(2);
list.add(“guan”);
list.add(“bao”);
String[] array = new String[list.size()];
array = list.toArray(array);
说明:使用 toArray 带参方法,入参分配的数组空间不够大时,toArray 方法内部将重新分配内存空间,并返回新数组地址 ; 如果数组元素大于实际所需,下标为 [ list . size() ] 的数组元素将被置为 null ,其它数组元素保持原值,因此最好将方法入参数组大小定义与集合元素个数一致。
5.【强制】使用工具类 Arrays . asList() 把数组转换成集合时,不能使用其修改集合相关的方法,它的 add / remove / clear 方法会抛出 UnsupportedOperationException 异常。
说明: asList 的返回对象是一个 Arrays 内部类,并没有实现集合的修改方法。 Arrays . asList体现的是适配器模式,只是转换接口,后台的数据仍是数组。
String[] str = new String[] { “a”, “b” };
List list = Arrays.asList(str);
第一种情况: list.add(“c”); 运行时异常。
第二种情况: str[0]=”gujin”;
那么 list.get(0) 也会随之修改。
7.【强制】不要在 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);
}
}
说明:以上代码的执行结果肯定会出乎大家的意料,那么试一下把“1”换成“2”,会是同样的结果吗?答案：“1”不会报错，换成“2”会报错。
正例:
Iterator it = a.iterator();
while(it.hasNext()){
String temp =
it.next();
if(删除元素的条件){
it.remove();
}
}
正例稳定正确地运行。
8.【强制】 在 JDK 7 版本以上, Comparator 要满足自反性,传递性,对称性,不然 Arrays . sort ,Collections . sort 会报IllegalArgumentException 异常。
说明:
1 ) 自反性: x , y 的比较结果和 y , x 的比较结果相反。
2 ) 传递性: x > y , y > z ,则 x > z 。
3 ) 对称性: x = y ,则 x , z 比较结果和 y , z 比较结果相同。
反例:下例中没有处理相等的情况,实际使用中可能会出现异常:
new Comparator() {
@Override
public int compare(Student o1, Student o2) {
return o1.getId() > o2.getId() ? 1 : -1;
}
9.【推荐】集合初始化时,尽量指定集合初始值大小。
说明: ArrayList 尽量使用 ArrayList(int initialCapacity) 初始化。
10.【推荐】使用 entrySet 遍历 Map 类集合 KV ,而不是 keySet 方式进行遍历。
说明: keySet 其实是遍历了 2 次,一次是转为 Iterator 对象,另一次是从 hashMap 中取出key 所对应的 value 。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中,效率更高。如果是JDK 8,使用 Map . foreach 方法。
正例: values() 返回的是 V 值集合,是一个 list 集合对象 ;keySet() 返回的是 K 值集合,是一个 Set 集合对象 ;entrySet() 返回的是 K - V 值组合集合。
11.【推荐】高度注意 Map 类集合 K / V 能不能存储 null 值的情况,如下表格:
反例: 由于 HashMap 的干扰,很多人认为 ConcurrentHashMap 是可以置入 null 值,注意存储null 值时会抛出 NPE 异常。
12.【参考】合理利用好集合的有序性 (sort) 和稳定性 (order) ,避免集合的无序性 (unsort) 和不稳定性 (unorder) 带来的负面影响。
说明:有序性是指遍历的结果是按某种比较规则依次排列的。稳定性指集合每次遍历的元素次序是一定的。如: ArrayList 是 order / unsort;HashMap 是 unorder / unsort;TreeSet 是order / sort 。
13.【参考】利用 Set 元素唯一的特性,可以快速对一个集合进行去重操作,避免使用 List 的contains 方法进行遍历、对比、去重操作。
(六) 并发处理
1.【强制】获取单例对象需要保证线程安全,其中的方法也要保证线程安全。
说明:资源驱动类、工具类、单例工厂类都需要注意。
2.【强制】创建线程或线程池时请指定有意义的线程名称,方便出错时回溯。
正例:
public class TimerTaskThread extends Thread {
public TimerTaskThread(){
super.setName(“TimerTaskThread”);
…
}
3.【强制】线程资源必须通过线程池提供,不允许在应用中自行显式创建线程。
说明:使用线程池的好处是减少在创建和销毁线程上所花的时间以及系统资源的开销,解决资源不足的问题。如果不使用线程池,有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。
4.【强制】线程池不允许使用 Executors 去创建,而是通过 ThreadPoolExecutor 的方式,这样的处理方式让写的同学更加明确线程池的运行规则,规避资源耗尽的风险。
说明: Executors 返回的线程池对象的弊端如下:
1) FixedThreadPool 和 SingleThreadPool :
允许的请求队列长度为 Integer.MAX_VALUE ,可能会堆积大量的请求,从而导致 OOM 。
2) CachedThreadPool 和 ScheduledThreadPool :
允许的创建线程数量为 Integer.MAX_VALUE ,可能会创建大量的线程,从而导致 OOM 。
注意：我在java编程思想读书笔记中并发一节中，都是使用的Executors创建方式，需要慢慢转换思想修正之。
5.【强制】 SimpleDateFormat 是线程不安全的类,一般不要定义为 static 变量,如果定义为static ,必须加锁,或者使用 DateUtils 工具类。
正例:注意线程安全,使用 DateUtils 。亦推荐如下处理:
private static final ThreadLocal df = new ThreadLocal() {
@ Override
protected DateFormat initialValue() {
return new SimpleDateFormat(“yyyy-MM-dd”);
}
};
说明:如果是 JDK 8 的应用,可以使用 Instant 代替 Date , LocalDateTime 代替 Calendar ,DateTimeFormatter 代替 Simpledateformatter ,官方给出的解释: simple beautiful strong immutable thread - safe 。
6.【强制】高并发时,同步调用应该去考量锁的性能损耗。能用无锁数据结构,就不要用锁 ; 能锁区块,就不要锁整个方法体 ; 能用对象锁,就不要用类锁。
7.【强制】对多个资源、数据库表、对象同时加锁时,需要保持一致的加锁顺序,否则可能会造成死锁。
说明:线程一需要对表 A 、 B 、 C 依次全部加锁后才可以进行更新操作,那么线程二的加锁顺序也必须是 A 、 B 、 C ,否则可能出现死锁。
11.【推荐】避免 Random 实例被多线程使用,虽然共享该实例是线程安全的,但会因竞争同一seed 导致的性能下降。
说明: Random 实例包括 java . util . Random 的实例或者 Math . random() 实例。
正例:在 JDK 7 之后,可以直接使用 API ThreadLocalRandom ,在 JDK 7 之前,可以做到每个线程一个实例。
12.【推荐】通过双重检查锁 (double - checked locking)( 在并发场景 ) 实现延迟初始化的优化问题隐患 ( 可参考 The ” Double - Checked Locking is Broken ” Declaration) ,推荐问题解决方案中较为简单一种 ( 适用于 JDK 5 及以上版本 ) ,将目标属性声明为 volatile 型 。
反例:
class Foo {
private Helper helper = null;
public Helper getHelper() {
if (helper == null)
synchronized(this) {
if (helper == null)
helper = new Helper();
}
}
return helper;
// other functions and members…
}
注意：阅读java编程思想读书笔记中并发一节关于volatile内容。
13.【参考】 volatile 解决多线程内存不可见问题。对于一写多读,是可以解决变量同步问题,但是如果多写,同样无法解决线程安全问题。如果是 count ++操作,使用如下类实现:
AtomicInteger count = new AtomicInteger(); count . addAndGet( 1 ); 如果是 JDK 8,推荐使用 LongAdder 对象,比 AtomicLong 性能更好 ( 减少乐观锁的重试次数 ) 。
15.【参考】 ThreadLocal 无法解决共享对象的更新问题, ThreadLocal 对象建议使用 static修饰。这个变量是针对一个线程内所有操作共有的,所以设置为静态变量,所有此类实例共享此静态变量 ,也就是说在类第一次被使用时装载,只分配一块存储空间,所有此类的对象 ( 只要是这个线程内定义的 ) 都可以操控这个变量。
(七) 控制语句
3.【推荐】推荐尽量少用 else , if - else 的方式可以改写成:
if(condition){
…
return obj;
}
// 接着写 else 的业务逻辑代码;
说明:如果非得使用 if()…else if()…else… 方式表达逻辑,【强制】请勿超过 3 层,
超过请使用状态设计模式。
正例:逻辑上超过 3 层的 if-else 代码可以使用卫语句,或者状态模式来实现。
5.【推荐】循环体中的语句要考量性能,以下操作尽量移至循环体外处理,如定义对象、变量、获取数据库连接,进行不必要的 try - catch 操作 ( 这个 try - catch 是否可以移至循环体外 ) 。
7.【参考】方法中需要进行参数校验的场景:
1 ) 调用频次低的方法。
2 ) 执行时间开销很大的方法,参数校验时间几乎可以忽略不计,但如果因为参数错误导致中间执行回退,或者错误,那得不偿失。
3 ) 需要极高稳定性和可用性的方法。
4 ) 对外提供的开放接口,不管是 RPC / API / HTTP 接口。
5) 敏感权限入口。
8.【参考】方法中不需要参数校验的场景:
1 ) 极有可能被循环调用的方法,不建议对参数进行校验。但在方法说明里必须注明外部参数检查。
2 ) 底层的方法调用频度都比较高,一般不校验。毕竟是像纯净水过滤的最后一道,参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中,部署在同一台服务器中,所以 DAO 的参数校验,可以省略。
3 ) 被声明成 private 只会被自己代码所调用的方法,如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题,此时可以不校验参数。
(八) 注释规约
1.【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/*内容/格式,不得使用// xxx 方式。
说明:在 IDE 编辑窗口中, Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释 ; 在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。
2.【强制】所有的抽象方法 ( 包括接口中的方法 ) 必须要用 Javadoc 注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。
说明:对子类的实现要求,或者调用注意事项,请一并说明。
7.【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。
说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。
8.【参考】注释掉的代码尽量要配合说明,而不是简单的注释掉。
说明:代码被注释掉有两种可能性:1 ) 后续会恢复此段代码逻辑。2 ) 永久不用。前者如果没有备注信息,难以知晓注释动机。后者建议直接删掉 ( 代码仓库保存了历史代码 ) 。
(九) 其它
1.【强制】在使用正则表达式时,利用好其预编译功能,可以有效加快正则匹配速度。
说明:不要在方法体内定义: Pattern pattern = Pattern . compile( 规则 );
4.【强制】注意 Math . random() 这个方法返回是 double 类型,注意取值的范围 0≤ x <1 ( 能够取到零值,注意除零异常 ) ,如果想获取整数类型的随机数,不要将 x 放大 10 的若干倍然后
取整,直接使用 Random 对象的 nextInt 或者 nextLong 方法。
5.【强制】获取当前毫秒数 System . currentTimeMillis(); 而不是 new Date() . getTime();
说明:如果想获取更加精确的纳秒级时间值,用 System . nanoTime() 。在 JDK 8 中,针对统计时间等场景,推荐使用 Instant 类。
7.【推荐】任何数据结构的构造或初始化,都应指定大小,避免数据结构无限增长吃光内存。
二、异常日志
(一) 异常处理
1.【强制】不要捕获 Java 类库中定义的继承自 RuntimeException 的运行时异常类,如:
IndexOutOfBoundsException / NullPointerException,这类异常由程序员预检查来规避,保证程序健壮性。
正例: if(obj
反例: try
!= null) {…}
{ obj.method() } catch(NullPointerException e){…}
3.【强制】对大段代码进行 try - catch ,这是不负责任的表现。 catch 时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型,再做对应的异常处理。
4.【强制】捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之,如果不想处理它,请将该异常抛给它的调用者。最外层的业务使用者,必须处理异常,将其转化为用户可以理解的内容。
5.【强制】有 try 块放到了事务代码中, catch 异常后,如果需要回滚事务,一定要注意手动回滚事务。
6.【强制】 finally 块必须对资源对象、流对象进行关闭,有异常也要做 try - catch 。
说明:如果 JDK 7,可以使用 try - with - resources 方式。
一个问题：为什么非要关闭这些资源对象和流对象呢？
参考：
1.Why do I need to use finally to close resources?
2.Do I need to close an InputStream in Java?
7.【强制】不能在 finally 块中使用 return , finally 块中的 return 返回后方法结束执行,不会再执行 try 块中的 return 语句。
8.【强制】捕获异常与抛异常,必须是完全匹配,或者捕获异常是抛异常的父类。
说明:如果预期对方抛的是绣球,实际接到的是铅球,就会产生意外情况。
9.【推荐】方法的返回值可以为 null ,不强制返回空集合,或者空对象等,必须添加注释充分说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题。
说明:本规约明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象,对调用者来说,也并非高枕无忧,必须考虑到远程调用失败,运行时异常等场景返回 null 的情况。
10.【推荐】防止 NPE ,是程序员的基本修养,注意 NPE 产生的场景:
1 ) 返回类型为包装数据类型,有可能是 null ,返回 int 值时注意判空。
反例: public int f() { return Integer 对象}; 如果为 null ,自动解箱抛 NPE 。
2 ) 数据库的查询结果可能为 null 。
3 ) 集合里的元素即使 isNotEmpty ,取出的数据元素也可能为 null 。
4 ) 远程调用返回对象,一律要求进行 NPE 判断。
5 ) 对于 Session 中获取的数据,建议 NPE 检查,避免空指针。
6 ) 级联调用 obj . getA() . getB() . getC(); 一连串调用,易产生 NPE 。
11.【推荐】在代码中使用“抛异常”还是“返回错误码”,对于公司外的 http / api 开放接口必须使用“错误码” ; 而应用内部推荐异常抛出 ; 跨应用间 RPC 调用优先考虑使用 Result 方式,封装 isSuccess 、“错误码”、“错误简短信息”。
说明:关于 RPC 方法返回方式使用 Result 方式的理由:
1 ) 使用抛异常返回方式,调用方如果没有捕获到就会产生运行时错误。
2 ) 如果不加栈信息,只是 new 自定义异常,加入自己的理解的 error message ,对于调用端解决问题的帮助不会太多。如果加了栈信息,在频繁调用出错的情况下,数据序列化和传输的性能损耗也是问题。
(二) 日志规约
1.【强制】应用中不可直接使用日志系统 (Log 4 j 、 Logback) 中的 API ,而应依赖使用日志框架SLF 4 J 中的 API ,使用门面模式的日志框架,有利于维护和各个类的日志处理方式统一。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(Abc.class);
三、MySQL 规约
(一) 建表规约
1.【强制】表达是与否概念的字段,必须使用 is _ xxx 的方式命名,数据类型是 unsigned tinyint( 1 表示是,0 表示否 ) ,此规则同样适用于 odps 建表。
说明:任何字段如果为非负数,必须是 unsigned 。
2.【强制】表名、字段名必须使用小写字母或数字 ; 禁止出现数字开头,禁止两个下划线中间只出现数字。数据库字段名的修改代价很大,因为无法进行预发布,所以字段名称需要慎重考虑。
正例: getter _ admin , task _ config , level 3_ name
反例: GetterAdmin , taskConfig , level 3 name
5.【强制】唯一索引名为 uk 字段名 ; 普通索引名则为 idx 字段名。
说明: uk _ 即 unique key;idx _ 即 index 的简称。
6.【强制】小数类型为 decimal ,禁止使用 float 和 double 。
说明: float 和 double 在存储的时候,存在精度损失的问题,很可能在值的比较时,得到不正确的结果。如果存储的数据范围超过 decimal 的范围,建议将数据拆成整数和小数分开存储。
8.【强制】 varchar 是可变长字符串,不预先分配存储空间,长度不要超过 5000,如果存储长度大于此值,定义字段类型为 text ,独立出来一张表,用主键来对应,避免影响其它字段索引效率。
9.【强制】表必备三字段: id , gmt _ create , gmt _ modified 。
说明:其中 id 必为主键,类型为 unsigned bigint 、单表时自增、步长为 1。 gmt _ create ,gmt _ modified 的类型均为 date _ time 类型。
13.【推荐】字段允许适当冗余,以提高性能,但是必须考虑数据同步的情况。冗余字段应遵循:
1 ) 不是频繁修改的字段。
2 ) 不是 varchar 超长字段,更不能是 text 字段。
正例:商品类目名称使用频率高,字段长度短,名称基本一成不变,可在相关联的表中冗余存储类目名称,避免关联查询。
14.【推荐】单表行数超过 500 万行或者单表容量超过 2 GB ,才推荐进行分库分表。
说明:如果预计三年后的数据量根本达不到这个级别,请不要在创建表时就分库分表。
15.【参考】合适的字符存储长度,不但节约数据库表空间、节约索引存储,更重要的是提升检索速度。
正例:人的年龄用 unsigned tinyint( 表示范围 0-255,人的寿命不会超过 255 岁 ); 海龟就必须是 smallint ,但如果是太阳的年龄,就必须是 int; 如果是所有恒星的年龄都加起来,那么就必须使用 bigint 。
(二) 索引规约
1.【强制】业务上具有唯一特性的字段,即使是组合字段,也必须建成唯一索引。
说明:不要以为唯一索引影响了 insert 速度,这个速度损耗可以忽略,但提高查找速度是明显的 ; 另外,即使在应用层做了非常完善的校验和控制,只要没有唯一索引,根据墨菲定律,必然有脏数据产生。
2.【强制】 超过三个表禁止 join 。需要 join 的字段,数据类型保持绝对一致 ; 多表关联查询时,保证被关联的字段需要有索引。
说明:即使双表 join 也要注意表索引、 SQL 性能。
3.【强制】在 varchar 字段上建立索引时,必须指定索引长度,没必要对全字段建立索引,根据实际文本区分度决定索引长度。
说明:索引的长度与区分度是一对矛盾体,一般对字符串类型数据,长度为 20 的索引,区分度会高达 90%以上,可以使用 count(distinct left( 列名, 索引长度 )) / count( * ) 的区分度来确定。
5.【推荐】如果有 order by 的场景,请注意利用索引的有序性。 order by 最后的字段是组合索引的一部分,并且放在索引组合顺序的最后,避免出现 file _ sort 的情况,影响查询性能。
正例: where a =? and b =? order by c; 索引: a _ b _ c
反例:索引中有范围查找,那么索引有序性无法利用,如: WHERE a >10 ORDER BY b; 索引a _ b 无法排序。
6.【推荐】利用覆盖索引来进行查询操作,来避免回表操作。
说明:如果一本书需要知道第 11 章是什么标题,会翻开第 11 章对应的那一页吗?目录浏览一下就好,这个目录就是起到覆盖索引的作用。
正例:能够建立索引的种类:主键索引、唯一索引、普通索引,而覆盖索引是一种查询的一种效果,用 explain 的结果, extra 列会出现: using index 。
7.【推荐】利用延迟关联或者子查询优化超多分页场景。
说明: MySQL 并不是跳过 offset 行,而是取 offset + N 行,然后返回放弃前 offset 行,返回N 行,那当 offset 特别大的时候,效率就非常的低下,要么控制返回的总页数,要么对超过特定阈值的页数进行 SQL 改写。
正例:先快速定位需要获取的 id 段,然后再关联:
SELECT a.* FROM 表 1 a, (select id from 表 1 where 条件 LIMIT 100000,20 ) b where a.id=b.id
9.【推荐】建组合索引的时候,区分度最高的在最左边。
正例:如果 where a =? and b =? , a 列的几乎接近于唯一值,那么只需要单建 idx _ a 索引即可。
说明:存在非等号和等号混合判断条件时,在建索引时,请把等号条件的列前置。如: where a >?and b =? 那么即使 a 的区分度更高,也必须把 b 放在索引的最前列。
10.【参考】创建索引时避免有如下极端误解:
1 ) 误认为一个查询就需要建一个索引。
2 ) 误认为索引会消耗空间、严重拖慢更新和新增速度。
3 ) 误认为唯一索引一律需要在应用层通过“先查后插”方式解决。
(三) SQL 规约
1.【强制】不要使用 count( 列名 ) 或 count( 常量 ) 来替代 count( * ) , count( * ) 就是 SQL 92 定义的标准统计行数的语法,跟数据库无关,跟 NULL 和非 NULL 无关。
说明: count( * ) 会统计值为 NULL 的行,而 count( 列名 ) 不会统计此列为 NULL 值的行。
2.【强制】 count(distinct col) 计算该列除 NULL 之外的不重复数量。注意 count(distinct col 1, col 2 ) 如果其中一列全为 NULL ,那么即使另一列有不同的值,也返回为 0。
3.【强制】当某一列的值全是 NULL 时, count(col) 的返回结果为 0,但 sum(col) 的返回结果为NULL ,因此使用 sum() 时需注意 NPE 问题。
正例:可以使用如下方式来避免 sum 的 NPE 问题: SELECT IF(ISNULL(SUM(g)) ,0, SUM(g)) FROM table;
4.【强制】使用 ISNULL() 来判断是否为 NULL 值。注意: NULL 与任何值的直接比较都为 NULL。
说明:
1 ) NULL<>NULL 的返回结果是 NULL ,而不是 false 。
2 ) NULL=NULL 的返回结果是 NULL ,而不是 true 。
3 ) NULL<>1 的返回结果是 NULL ,而不是 true 。
6.【强制】不得使用外键与级联,一切外键概念必须在应用层解决。
说明: ( 概念解释 ) 学生表中的 student _ id 是主键,那么成绩表中的 student _ id 则为外键。
如果更新学生表中的 student _ id ,同时触发成绩表中的 student _ id 更新,则为级联更新。
外键与级联更新适用于单机低并发,不适合分布式、高并发集群 ; 级联更新是强阻塞,存在数据库更新风暴的风险 ; 外键影响数据库的插入速度。
9.【推荐】 in 操作能避免则避免,若实在避免不了,需要仔细评估 in 后边的集合元素数量,控制在 1000 个之内。
10.【参考】如果有全球化需要,所有的字符存储与表示,均以 utf -8 编码,那么字符计数方法注意:
说明:
SELECT LENGTH( “轻松工作” ); 返回为 12
SELECT CHARACTER _ LENGTH( “轻松工作” ); 返回为 4
如果要使用表情,那么使用 utfmb 4 来进行存储,注意它与 utf -8 编码的区别。
11.【参考】 TRUNCATE TABLE 比 DELETE 速度快,且使用的系统和事务日志资源少,但 TRUNCATE无事务且不触发 trigger ,有可能造成事故,故不建议在开发代码中使用此语句。
说明: TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。
(四) ORM 规约
1.【强制】在表查询中,一律不要使用 * 作为查询的字段列表,需要哪些字段必须明确写明。
说明:1 ) 增加查询分析器解析成本。2 ) 增减字段容易与 resultMap 配置不一致。
2.【强制】 POJO 类的 boolean 属性不能加 is ,而数据库字段必须加 is _,要求在 resultMap 中进行字段与属性之间的映射。
说明:参见定义 POJO 类以及数据库字段定义规定,在 sql . xml 增加映射,是必须的。
四、工程规约
(一) 应用分层
1.【推荐】图中默认上层依赖于下层,箭头关系表示可直接依赖,如:开放接口层可以依赖于Web 层,也可以直接依赖于 Service 层,依此类推:
开放接口层:可直接封装 Service 接口暴露成 RPC 接口 ; 通过 Web 封装成 http 接口 ; 网关控制层等。
终端显示层:各个端的模板渲染并执行显示层。当前主要是 velocity 渲染, JS 渲染, JSP 渲染,移动端展示层等。
Web 层:主要是对访问控制进行转发,各类基本参数校验,或者不复用的业务简单处理等。
Service 层:相对具体的业务逻辑服务层。
Manager 层:通用业务处理层,它有如下特征:
1 ) 对第三方平台封装的层,预处理返回结果及转化异常信息 ;
2 ) 对 Service 层通用能力的下沉,如缓存方案、中间件通用处理 ;
3 ) 与 DAO 层交互,对 DAO 的业务通用能力的封装。
DAO 层:数据访问层,与底层 MySQL 、 Oracle 、 Hbase 进行数据交互。
外部接口或第三方平台:包括其它部门 RPC 开放接口,基础平台,其它公司的 HTTP 接口。
3.【参考】分层领域模型规约:
DO(Data Object) :与数据库表结构一一对应,通过 DAO 层向上传输数据源对象。
DTO(Data Transfer Object) :数据传输对象, Service 和 Manager 向外传输的对象。
BO(Business Object) :业务对象。可以由 Service 层输出的封装业务逻辑的对象。
QUERY :数据查询对象,各层接收上层的查询请求。注:超过 2 个参数的查询封装,禁止使用 Map 类来传输。
VO(View Object) :显示层对象,通常是 Web 向模板渲染引擎层传输的对象。
(二) 二方库规约
1.【强制】定义 GAV 遵从以下规则:
1 ) GroupID 格式: com .{公司/ BU }.业务线. [ 子业务线 ] ,最多 4 级。
说明: {公司/ BU } 例如: alibaba / taobao / tmall / aliexpress 等 BU 一级 ; 子业务线可选。
正例: com . taobao . jstorm 或 com.alibaba.dubbo.register
2 ) ArtifactID 格式:产品线名-模块名。语义不重复不遗漏,先到仓库中心去查证一下。
正例: dubbo - client / fastjson - api / jstorm - tool
3 ) Version :详细规定参考下方。
2.【强制】二方库版本号命名方式:主版本号.次版本号.修订号
1 ) 主版本号:当做了不兼容的 API 修改,或者增加了能改变产品方向的新功能。
2 ) 次版本号:当做了向下兼容的功能性新增 ( 新增类、接口等 ) 。
3 ) 修订号:修复 bug ,没有修改方法签名的功能加强,保持 API 兼容性。
说明:起始版本号必须为: 1.0.0 ,而不是 0.0.1
(三) 服务器规约
1.【推荐】高并发服务器建议调小 TCP 协议的 time _ wait 超时时间。
说明:操作系统默认 240 秒后,才会关闭处于 time _ wait 状态的连接,在高并发访问下,服务器端会因为处于 time _ wait 的连接数太多,可能无法建立新的连接,所以需要在服务器上调小此等待值。
正例:在 linux 服务器上请通过变更/ etc / sysctl . conf 文件去修改该缺省值 ( 秒 ) :
net . ipv 4. tcp _ fin _ timeout = 30
2.【推荐】调大服务器所支持的最大文件句柄数 (File Descriptor ,简写为 fd) 。
说明:主流操作系统的设计是将 TCP / UDP 连接采用与文件一样的方式去管理,即一个连接对应于一个 fd 。主流的 linux 服务器默认所支持最大 fd 数量为 1024,当并发连接数很大时很容易因为 fd 不足而出现“ open too many files ”错误,导致新的连接无法建立。 建议将 linux服务器所支持的最大句柄数调高数倍 ( 与服务器的内存数量相关 ) 。
4.【参考】服务器内部重定向使用 forward; 外部重定向地址使用 URL 拼装工具类来生成,否则会带来 URL 维护不一致的问题和潜在的安全风险。
五、安全规约
1.【强制】隶属于用户个人的页面或者功能必须进行权限控制校验。
说明：防止没有做水平权限校验就可随意访问、操作别人的数据，比如查看、修改别人的订单。
2.【强制】用户敏感数据禁止直接展示，必须对展示数据脱敏。
说明：查看个人手机号码会显示成:158****9119，隐藏中间 4位，防止隐私泄露。
3.【强制】用户输入的 SQL参数严格使用参数绑定或者 METADATA字段值限定，防止 SQL注入，禁止字符串拼接 SQL访问数据库。
4.【强制】用户请求传入的任何参数必须做有效性验证。
说明：忽略参数校验可能导致：
- page size过大导致内存溢出
- 恶意 order by导致数据库慢查询
- 任意重定向
- SQL注入
- 反序列化注入
- 正则输入源串拒绝服务 ReDoS
说明：Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使用的是特殊构造的字符串来验证，有可能导致死循环的效果。
5.【强制】禁止向 HTML页面输出未经安全过滤或未正确转义的用户数据。
6.【强制】表单、AJAX提交必须执行 CSRF安全过滤。
说明：CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在CSRF漏洞的应用/网站，攻击者可以事先构造好 URL，只要受害者用户一访问，后台便在用户不知情情况下对数据库中用户参数进行相应修改。
7.【强制】在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损。
说明：如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费。
8.【推荐】发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。