1. 基本功能 1. 基本功能

2. 配置方法 2. 配置方法

2.1. 文件编码配置

打开 Jetbrains IDEA 的 bin 目录编辑idea64.exe.vmoptions 文件(如果用的是64bit)， 在文件末尾添加配
置项 -Dfile.encoding=UTF-8
properties文件编码配置
settings ==> 搜索encoding ==> 选中Editor > File Encoding ==> 勾选properties 转义选项

2.2 Java编程规范

命名

软件中随处可见命名。我们给变量、函数、参数、类和包命名。给目录、jar包和war包命名。需要为它们提供名副
其实的命名，避免歧义，让代码易于阅读。
1. 代码中命名均不能以 下划线或美元符号 开始, 也不能以 下划线或美元符号 结束
反例 : name / name / $object / name / name$ / object$
2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许使用中文的方式。
说明 : 正确的英文拼写和语法可以让阅读者易于理解， 避免歧义。 注意， 即使纯拼音命名方式也要避免使
用。
正例 : product / repository / gillion / aliyun / xiamen 等国际通用的名称， 可视同英文。
反例 : cangku [仓库] / getZhekou [折扣] / xxxx [学校信息] / double 价格 = 3.14D
3. 类名使用 UpperCamelCase 风格, 必须遵从骆驼形式, 但一下情形例外: DO / BO / DTO / VO /
AO
正例 : MarcoPolo / UserDTO / XmlUtils / TcpUdpDeal / StudentService
反例 : macoPolo / UserDto / XMLUtils / TCPUDPDeal / Studentservice
4. 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格， 必须遵从驼峰形式。

userList / getHttpMessage() / inputUserId
5. 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

YYYYMMDDFORMATTER / MAXSTOCKCOUNT

MAXCOUNT
6. 抽象类命名要使用 Abstract 或 Base 开头； 异常类命名要以 Exception 结尾； 测试类命名
以它要测试的类的名称开始， 以 Test 结尾。
7. 中括号是数组类型的一部分，数组定义如下 : String[] args ;
反例 : 使用String args[] 的方式来定义。
8. POJO类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。
反例 : 定义为基本数据类型 Boolean isDeleted 的属性，它的方法也是 isDeleted() ，RPC
框架在反向解析的时候，“以为”对应的属性名称是deleted ，导致属性获取不到，进而抛出异常。
9. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但
是类名如果有复数含义，类名可以使用复数形式。
10. 杜绝完全不规范的缩写，避免望文不知义。
反例 : AbstractClass “缩写”命名成 AbsClass ； condition “缩写”命名成 condi ，此类随意缩写
严重降低了代码的可阅读性。
11. 为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词
组合来表达其意。
正例 : 从远程仓库拉取代码的类命名为 PullCodeFromRemoteRepository。
反例 : 变量 int a; 的随意命名方式。
12. 如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。 说明 : 将设计模式体现在
名字中，有利于阅读者快速理解架构设计理念。
正例：
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;
13. 接口类中的方法和属性不要加任何修饰符号（ public 也不要加），保持代码的简洁性，并加上有
效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是
整个应用的基础常量。 正例 :
接口方法签名 : void f();
接口基础常量表示 : String COMPANY = “Gillion”;
反例 :
接口方法定义 : public abstract void f();
说明 : JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。
14. 接口和实现类的命名有两套规则 :
对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部 的实现类用 Impl
的后缀与接口区别。
正例 : CacheServiceImpl 实现 CacheService 接口。
如果是形容能力的接口名称，取对应的形容词做接口名（通常是–able 的形式）。
正例 : AbstractTranslator 实现 Translatable 。
15. 枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。 说明 : 枚举其实
就是特殊的常量类，且构造方法被默认强制是私有。 正例 : 枚举名字为 ProcessStatusEnum 的成员名
称 : SUCCESS / UNKOWNREASON 。
16. 各层命名规约 :
Service/DAO 层方法命名规约
1. 获取单个对象的方法用 get 做前缀。
2. 获取多个对象的方法用 list 做前缀。
3. 获取统计值的方法用 count 做前缀。
4. 插入的方法用 save/insert 做前缀。
5. 删除的方法用 remove/delete 做前缀。
6. 修改的方法用 update 做前缀。
领域模型命名规约
1. 数据对象 : xxxDO ， xxx 即为数据表名。
2. 数据传输对象 : xxxDTO ， xxx 为业务领域相关的名称。
3. 展示对象 : xxxVO ， xxx 一般为网页名称。
4. POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO 。

2.3 常量定义

1. 不允许任何魔法值（即未经定义的常量）直接出现在代码中。 反例 :
   String key = “Id#taobao” + tradeId;
   cache.put(key, value);
2. long 或者 Long 初始赋值时，使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误
   解。 说明 : Long a = 2l ; 写的是数字的 21 ，还是 Long 型的 2 ?
3. 不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护。 说明 : 大而全的常量类，非
   得使用查找功能才能定位到修改的常量，不利于理解和维护。 正例 : 缓存相关常量放在类 CacheConsts
   下；系统配置相关常量放在类 ConfigConsts 下。
4. 常量的复用层次有五层 : 跨应用共享常量、应用内共享常量、子工程内共享常量、包 内共享常量、
   类内共享常量。
5. 跨应用共享常量 : 放置在二方库中，通常是 client.jar 中的 constant 目录下。
6. 应用内共享常量 : 放置在一方库中，通常是 modules 中的 constant 目录下。
   反例 :
   易懂变量也要统一定义成应用内共享常量，两位工程师在两个类中分别定义了表示“是”的变量 :
   类 A 中 : public static final String YES = “yes”
   类 B 中 : public static final String YES = “y”;
   A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致线上问题。
7. 子工程内部共享常量 : 即在当前子工程的 constant 目录下。
8. 包内共享常量 : 即在当前包下单独的 constant 目录下。
9. 类内共享常量 : 直接在类内部 private static final 定义。
10. 如果变量值仅在一个范围内变化，且带有名称之外的延伸属性，定义为枚举类。下面正例中的数字
    就是延伸信息，表示星期几。
    正例 :
    public Enum {
    MONDAY(1),
    TUESDAY(2),
    WEDNESDAY(3),
    THURSDAY(4),
    FRIDAY(5),
    SATURDAY(6),
    SUNDAY(7);
    }
11. 禁止用new BigDecimal(“0”) 来初始化对象，应使用BigDecimal.ZERO , 同理应用于可用常量初
    始化的其它对象

2.4. 代码格式

2.4.1. 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则:

1. 左大括号前不换行。
2. 左大括号后换行。
3. 右大括号前换行。
4. 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。

2. 4.2 左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。

详见第 5 条下方正例提示。
反例 : if (空格 a == b 空格)
2. if/for/while/switch/do 等保留字与括号之间都必须加空格。
3. 任何二目、三目运算符的左右两边都需要加一个空格。 说明 : 运算符包括赋值运算符= 、逻辑运算
符&& 、+-/ 符号等。
4. 采用 4 个空格缩进，禁止使用 tab 字符。 说明 : 如果使用 tab 缩进，必须设置 1 个 tab 为 4 个
空格。IDEA 设置 tab 为 4 个空格时，请勿勾选 Use tab character ；而在 eclipse 中，必须勾选
insert spaces for tabs 。 正例 : （涉及 1-5 点）
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”);
// 在右大括号后直接结束，则必须换行
}
}
5. 注释的双斜线与注释内容之间有且仅有一个空格。
正例 : // 注释内容，注意在//和注释内容之间有一个空格。
1. 单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则 :
2. 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
3. 运算符与下文一起换行。
4. 方法调用的点符号与下文一起换行。
5. 方法调用时，多个参数，需要换行时，在逗号后进行。
6. 在括号前不要换行，见反例。
正例 :

StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下，换行缩进 4 个空格，点号和方法名称一起换行
sb.append("zi").append("xin")...
.append("huang")...
.append("huang")...
.append("huang");

反例 :

StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下，不要在括号前换行
sb.append("zi").append("xin")...append
("huang");
// 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行
method(args1, args2, args3, ...
, argsX);

方法参数在定义和传入时，多个参数逗号后边必须加空格。
正例 : 下例中实参的”a”,后边必须要有一个空格。method(“a”, “b”, “c”);
没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。
正例 :
int a = 3;
long b = 4L;
float c = 5F;
StringBuffer sb = new StringBuffer();
说明 : 增加 sb 这个变量，如果需要对齐，则给 a、b、c 都要增加几个空格，在变量比较多的情况下，是一种累
赘的事情。
方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空
行。相同业务逻辑和语义之间不需要插入空行。 说明 : 没有必要插入多个空行进行隔开。

2.5 OOP 规约

避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类
名来访问即可。
所有的覆写方法，必须加@Override 注解。 说明 : getObject() 与 get0bject() 的问题。一个
是字母的 O ，一个是数字的 0 ，加@Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法
签名进行修改，其实现类会马上编译报错。
相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。
说明 : 可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程） smile 正例 : public User
getUsers(String type, Integer… ids) {…}
外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过
时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
不能使用过时的类或方法。 说明 : java.net.URLDecoder 中的方法 decode(String
encodeStr) 这个方法已经过时，应该使用双参数 decode(String source, String encode) 。接口提供
方既然明确是过时接口，那么有义务同时提供新的接口；作为调用方来说，有义务去考证过时方法的新实现
是什么。
Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals 。 正
例 : “test”.equals(object) ; 反例 : object.equals(“test”) ; 说明 : 推荐使用
java.util.Objects#equals （JDK7 引入的工具类）
所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。 说明 : 对于 Integer
var = ? 在 -128 至 127 范围内的赋值， Integer 对象是在IntegerCache.cache 产生，会复用已有
对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产
生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。
关于基本数据类型与包装数据类型的使用标准如下 :
所有的 POJO 类属性必须使用包装数据类型。
RPC 方法的返回值和参数必须使用包装数据类型。
所有的局部变量使用基本数据类型。
说明 : POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或者入库
检查，都由使用者来保证。 正例 : 数据库的查询结果可能是 null ，因为自动拆箱，用基本数据类型接收有
NPE 风险。 反例 : 比如显示成交总额涨跌情况，即正负 x% ， x 为基本数据类型，调用的 RPC 服务，调用
不成功时，返回的是默认值，页面显示为 0% ，这是不合理的，应该显示成中划线。所以包装 数据类型的 null
值，能够表示额外的信息，如 : 远程调用失败，异常退出。
定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。 反例 : POJO 类的 gmtCreate
默认值为 new Date(); 但是这个属性在数据提取时并没有置入具 体值，在更新其它字段时又附带更新了此
字段，导致创建时间被修改成当前时间。
序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败；如 果完全不兼容
升级，避免反序列化混乱，那么请修改 serialVersionUID 值。 说明 : 注意 serialVersionUID 不一致
会抛出序列化运行时异常。
构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
POJO 类必须写 toString 方法。使用 IDE 的中工具 : source > generate toString 时，如果
继承了另一个 POJO 类，注意在前面加一下 super.toString 。 说明 : 在方法执行抛出异常时，可以直接
调用 POJO 的 toString() 方法打印其属性值，便于排 查问题。
使用索引访问用 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 方法放在类体 最后。
setter 方法中，参数名称与类成员变量名称一致， this.成员名 = 参数名。在getter/setter
方法中，不要增加业务逻辑，增加排查问题的难度。
反例 :

public Integer getData () {
if (true) {
return this.data + 100;
} else {
return this.data - 100;
}
}

循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。 说明 : 反编译出
的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行 append 操作，最后通过
toString 方法返回 String 对象，造成内存资源浪费。
反例 :

String str = "start";
for (int i = 0; i < 100; i++) {
str = str + "hello";
}

final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 fina l 关键字 :
不允许被继承的类，如 : String 类。
不允许修改引用的域对象，如 : POJO 类的域变量。
不允许被重写的方法，如 : POJO 类的 setter 方法。
不允许运行过程中重新赋值的局部变量。
避免上下文重复使用一个变量，使用 final 描述可以强制重新定义一个变量，方便更好地进行重构。
慎用 Object 的 clone 方法来拷贝对象。 说明 : 对象的 clone 方法默认是浅拷贝，若想实现深
拷贝需要重写 clone 方法实现属性对象的拷贝。推介使用InnerBuilder 插件生成 类$Builder 类，然后
用它来拷贝。
类成员与方法访问控制从严 :
如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
工具类不允许有 public 或 default 构造方法。
类非 static 成员变量并且与子类共享，必须是 protected 。
类非 static 成员变量并且仅在本类使用，必须是 private 。
类 static 成员变量如果仅在本类使用，必须是 private 。
若是 static 成员变量，必须考虑是否为 final。
类成员方法只供类内部调用，必须是 private。
类成员方法只对继承类公开，那么限制为 protected。
说明 : 任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。
思考 : 如果是一个 private 的方法，想删除就删除，可是一个 public 的 service 方法，或者一个 public
的成员变量，删除一下，不得手心冒点汗吗？变量像自己的小孩，尽量在自己的视线内，变量作用域太大，无限制
的到处跑，那么你会担心的。

2.6. 集合处理

关于 hashCode 和 equals 的处理，遵循如下规则 :
只要重写 equals ，就必须重写 hashCode 。
因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个
方法。
如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals。
说明 : String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象 作为 key 来
使用。新工程建议使用 lombok 插件处理
ArrayList 的subList 结果不可强转成ArrayList ，否则会抛出ClassCastException 异常，
即 java.util.RandomAccessSubList cannot be cast to java.util.ArrayList. 说明 : subList 返回的是 ArrayList 的内部类 SubList ，并不是 ArrayList ，而是ArrayList 的一个视图，对于SubList 子列表的所有操作最终会反映到原列表上。Guava 处理过的集合对象也不能强转型在 subList 场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增加、删除 均会产生 ConcurrentModificationException 异常。
使用集合转数组的方法，必须使用集合的 toArray(T[] array) ，传入的是类型完全一样的数组，大小就是 list.size() 。或使用Guava的工具方法 Iterables.toArray(list, Class clazz)
说明 : 使用 toArray 带参方法，入参分配的数组空间不够大时， toArray 方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为[list.size()] 的数组元素将被置为 null，其它数组元素保持原值，因此最好将方法入参数组大小定义与集合元素个数一致。
正例 :

List list = new ArrayList(2);
list.add("guan");
list.add("bao");
String[] array = new String[list.size()];
array = list.toArray(array);

//Guava
String[] strArray = Iterables.toArray(strs, String.class);

反例 : 直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[] 类，若强转其它 类型数组将
出现 ClassCastException 错误。
使用工具类 Arrays.asList() 把数组转换成集合时，不能使用其修改集合相关的方法，它的
add/remove/clear 方法会抛出 UnsupportedOperationException 异常。 说明 : asList 的返回对象
是一个 Arrays 内部类，并没有实现集合的修改方法。Arrays.asList 体现的是适配器模式，只是转换接
口，后台的数据仍是数组。
String[] str = new String[] { “you”, “wu” };
List list = Arrays.asList(str);
第一种情况 : list.add(“yangguanbao”); 运行时异常。 第二种情况 : str[0] = “gujin”; 那么
list.get(0) 也会随之修改。
泛型通配符来接收返回的数据，此写法的泛型集合不能使用 add 方法，而不能使用 get 方法，做
为接口调用赋值时易出错。 说明 : 扩展说一下 PECS(Producer Extends Consumer Super) 原则 :
频繁往外读取内容的，适合用。
经常往里插入的，适合用。
不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，
如果并发操作，需要对 Iterator 对象加锁。
正例 :

Iterator iterator = list.iterator();
while (iterator.hasNext()) {
String item = iterator.next();
if (删除元素的条件) {
iterator.remove();
}
}
 反例 :
 List list = new ArrayList();
list.add("1");
list.add("2");
for (String item : list) {
if ("1".equals(item)) {
list.remove(item);
}
}

说明 : 以上代码的执行结果肯定会出乎大家的意料，那么试一下把“1”换成“2”，会是同样的结果吗？
在 JDK7 版本及以上， Comparator 要满足如下三个条件，不然 Arrays.sort ，
Collections.sort 会报 IllegalArgumentException 异常。 说明 : 三个条件如下
x，y 的比较结果和 y，x 的比较结果相反。
x>y，y>z ，则 x>z 。
x=y ，则 x，z 比较结果和 y，z 比较结果相同。
反例 : 下例中没有处理相等的情况，实际使用中可能会出现异常 :
new Comparator() {
@Override
public int compare(Student o1, Student o2) {
return o1.getId() > o2.getId() ? 1 : -1;
}
};
集合初始化时，指定集合初始值大小。 说明 : HashMap 使用 HashMap(int initialCapacity)
初始化， 正例 : initialCapacity = (需要存储的元素个数 / 负载因子) + 1 。注意负载因子（即
loaderfactor ）默认为 0.75 ，如果暂时无法确定初始值大小，请设置为 16 （即默认值）。 反例 :
HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素不断增加，容量 7 次被迫扩大，
resize 需要重建 hash 表，严重影响性能。
使用 entrySet 遍历 Map 类集合 KV ，而不是 keySet 方式进行遍历。 说明 : keySet 其实是
遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出key 所对应的 value 。而
entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效率更高。如果是 JDK8 ，使用
Map.foreach 方法。 正例 : values() 返回的是 V 值集合，是一个 list 集合对象； keySet() 返
回的是 K 值集合，是一个 Set 集合对象； entrySet() 返回的是 K-V 值组合集合。
高度注意 Map 类集合 K/V 能不能存储 null 值的情况，如下表格 :
集合类 Key Value Super 说明
Hashtable 不允许为 null 不允许为 null Dictionary 线程安全
ConcurrentHashMap 不允许为 null 不允许为 null AbstractMap 锁分段技术（ JDK8:CAS ）
TreeMap 不允许为 null 允许为 null AbstractMa p 线程不安全
HashMap 允许为 null 允许为 null AbstractMap 线程不安全
反例 : 由于 HashMa p 的干扰，很多人认为 ConcurrentHashMap 是可以置入 null 值，而事实上，存储
null 值时会抛出 NPE 异常。
合理利用好集合的有序性( sort )和稳定性( order )，避免集合的无序性( unsort )和不稳定性( unorder )带来的负面影响。 说明 : 有序性是指遍历的结果是按某种比较规则依次排列的。稳定性指集合每次遍历的元素次序是一定的。如: ArrayList 是 order/unsort ； HashMap 是 unorder/unsort ；TreeSet 是 order/sort 。利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的 contains方法进行遍历、对比、去重操作。
JAVA8 中list 转换为map 的时候Lists.transform 、或者for 循环的的写法较为繁琐，建议采用lambda 写法
反例:

final Map<String, String> areaCodeWithNameMap = new HashMap();
for(Area area: areaList) {
areaCodeWithNameMap.put(area.getCode, area.getName());
}
 正例:
final Map<String, String> areaCodeWithNameMap = areaList.stream()
.collect(Collectors.toMap(Area::getCode, Area::getName))

2.7. 并发处理

获取单例对象需要保证线程安全，其中的方法也要保证线程安全。 说明 : 资源驱动类、工具类、单
例工厂类都需要注意。
创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
正例 :

public class TimerTaskThread extends Thread {
public TimerTaskThread() {
super.setName("TimerTaskThread");
...
}
}

线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。 说明 : 使用线程池的好处是减少在创建和销毁线程上所花的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
说明 : Executors 返回的线程池对象的弊端如下 :
FixedThreadPool 和 SingleThreadPool : 允许的请求队列长度为 Integer.MAXVALUE ，可能会堆积大
量的请求，从而导致 OOM
CachedThreadPool 和 ScheduledThreadPool : 允许的创建线程数量为 Integer.MAXVALUE ，可能会
创建大量的线程，从而导致 OOM 。
SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为static ，
必须加锁，或者使用 DateUtils 工具类。 正例 : 注意线程安全，使用
org.apache.commons.lang3.time.FastDateFormat 。亦推荐如下处理 :

private static final ThreadLocal df = new ThreadLocal() {
@Override
protected DateFormat initialValue() {
return new SimpleDateFormat("yyyy-MM-dd");
}
};

//FastDateFormat 是线程安全的
public static final FastDateFormat FORMATTER = FastDateFormat.getInstance(“yyyy-MMdd”);
说明 : 如果是 JDK8 的应用，可以使用 Instant 代替 Date ， LocalDateTime 代替 Calendar ，
DateTimeFormatter 代替 SimpleDateFormat ，官方给出的解释 : simple beautiful strong immutable
thread-safe 。
高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。 说明 : 尽可能使加锁的代码块工作量尽可能的小，避免在锁代码块中调用 RPC 方法。
对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。 说明 :线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A、B、C，否则可能出现死锁。
并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。 说明 : 如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于 3 次。
多线程并行处理定时任务时， Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。
使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown 方法，线程执行代码注意 catch 异常，确保 countDown 方法被执行到，避免主线程无法执行至 await 方法，直到超时才返回结果。 说明 : 注意，子线程抛出异常堆栈，不能在主线程 try-catch 到。
避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed 导致的性能下降。 说明 : Random 实例包括 java.util.Random 的实例或者 Math.random() 的方式。 正例 :
在 JDK7 之后，可以直接使用 API ThreadLocalRandom ，而在 JDK7 之前，需要编码保证每个线程持有一
个实例。
在并发场景下，通过双重检查锁（ double-checked locking ）实现延迟初始化的优化问题隐患(可参考 The “Double-Checked Locking is Broken” Declaration) ，推荐解决方案中较为简单一种（适用于 JDK5 及以上版本），将目标属性声明为 volatile 型。
反例 :

class Singleton {
private Helper helper = null;
public Helper getHelper() {
if (helper == null) synchronized(this) {
if (helper == null)
helper = new Helper();
}
return helper;
}
// other methods and fields...
}

volatile 解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。如果是 count++ 操作，使用如下类实现 : AtomicInteger count = newAtomicInteger(); count.addAndGet(1); 如果是 JDK8，推荐使用 LongAdder 对象，比 AtomicLong 性能更好（减少乐观锁的重试次数）。
HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在开发过程中可以使用其它数据结构或加锁来规避此风险。
ThreadLocal 无法解决共享对象的更新问题， ThreadLocal 对象建议使用 static 修饰。这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变量 ，也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象(只要是这个线程内定义的)都可以操控这个变量。

2.8 控制语句

在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。
在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式 : 反例 : if (condition) statements;表达异常的分支时，少用 if-else 方式，这种方式可以改写成 :

public Object func1(){
if (condition) {
...
return obj;
}

// 接着写 else 的业务逻辑代码;
}
说明 : 如果非得使用 if()…else if()…else… 方式表达逻辑:
避免后续代码维护困难，请勿超过 3 层。
正例 : 超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，其中卫语
句示例如下 :

public void today() {
if (isBusy()) {
System.out.println(“change time.”);
return;
}
if (isFree()) {
System.out.println(“go to travel.”);
return;
}
System.out.println(“stay at home to learn Alibaba Java Coding Guidelines.”);
return;
}

除常用方法（如 getXxx/isXxx ）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。 说明 : 很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？ 正例 :
// 伪代码如下

final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed) {
...
}
 反例 :
if ((file.open(fileName, "w") != null) && (...) || (...)) {
...
}

循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体外?）。
接口入参保护，这种场景常见的是用于做批量操作的接口。
下列情形，需要进行参数校验 :
调用频次低的方法。
执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
需要极高稳定性和可用性的方法。
对外提供的开放接口，不管是 RPC/API/HTTP 接口。
敏感权限入口。
下列情形，不需要进行参数校验 :
极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一台服务器中，所以 DAO 的参数校验，可以省略。
被声明成 private 只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

2.9. 注释规约

类、类属性、类方法的注释必须使用 Javadoc 规范，使用/内容/ 格式，不得使用// xxx 方式。 说明 : 在 IDE 编辑窗口中， Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；
在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明 : 对子类的实现要求，或者调用注意事项，请一并说
明。
所有的类都必须添加创建者和创建日期。
方法内部单行注释，在被注释语句上方另起一行，使用// 注释。方法内部多行注释 使用/ / 注
释，注意与代码对齐。
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
反例 : “TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。 说明 : 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的
意义。
谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。 说明 : 代码被注释掉有两种可能性 :
后续会恢复此段代码逻辑。
永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。对于注释的要求 :
能够准确反应设计思想和代码逻辑；
能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端 : 过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。 反例 :
// put elephant into fridge
put(elephant, fridge);
方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语 义清晰的代码不需要额
外的注释。
特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描， 经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
待办事宜（ TODO ）:（ 标记人，标记时间，[预计处理时间]）表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。
错误，不能工作（ FIXME ）:（标记人，标记时间，[预计处理时间]）在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

if (logger.isDebugEnabled()) {
logger.debug('message , arg :' + arg);
}
if (logger.isInfoEnabled()) {
logger.Info('message , area : {}', x  y);
}

3.0. 框架相关

使用自定义查询时， 在服务类中要对必要参数进行非空校验。否则当所有条件字段的值都为null
时会变成全表扫描
禁止在循环里再次循环获取值，应将条件集合数据转换成map 或set 通过然后判断来降低复杂度
反例:

final List<Employee> filteredEmployeesByDepts = new ArrayList<>();
for (Employee employee : employeeList) {
for (Dept dept : allowDeptList) {
if (Objects.equals(employee.getDeptId(), dept.getId())) {
filteredEmployeesByDepts.add(dept);
}
}
}

正例
// 先抽取过滤条件的部门编号(deptId)到一个Set

final Set<String> allowDeptIds =
deptList.stream().map(Dept::getId).collect(Collectors.toSet());
final List<Employee> filteredEmployeesByDepts = employeeList.stream()
.filter(employee -> allowDeptIds.contains(employee.getDeptId()))
.collect(Collectors.toList());

服务类不允许提供Example 对象作为参数的公有方法，应按特定场景提供方法参数并在内部拼接Example
反例：

public OrderServiceImpl implements OrderService {
public int deleteOrderByExample(OrderExample example) {
return orderMapper.deleteByExample(example);
}
}

正例：

public OrderServiceImpl implements OrderService {
public int deleteOrderByExample(OrderVO conditionObj) {
OrderExample example = createExampleByVO(conditionObj);
return orderMapper.deleteByExample(example);
}
private OrderExample createExampleByVO(OrderVO conditionObj) {
OrderExample example = new OrderExample();
if (conditionObj.getOrderId() != null) {
....
}
...
return example;
}
}

日志输出不得使用System.out , 请使用日志输出API 组件 SLF4J尽量不要在循环中进行数据库操作， 应该尽可能的采用批量操作构造Example 时字段名采用常量而非字面量

 反例：
WaybillExample example = WaybillExample.create();
example.and().andCreateCondition("waybilltype", Operation.EQ,
params.getWaybillType());
 正例:
WaybillExample example = WaybillExample.create();
example.and().andCreateCondition(Waybill.WAYBILLTYPE, Operation.EQ,
params.getWaybillType());

实例注入要使用Spring 的依赖注入， 不得使用SpringContextHolder.getBean() 获取Service 层中非特殊情况（如返回动态结构的结果）而将返回值设定为Map 来返回数据，应采用强类型.禁止在Controller 、Service 层中将参数采用JsonNode 、HashMap 等弱类型，应根据业务需要定义强类型(POJO) 参数当业务逻辑发现异常需要终止业务逻辑执行时不应该采用return null 或返回一个空字符串( return “” )、类型等方式来终止，而应抛出对应的业务异常.

3.1. 其它

包定义采用格式： com.gillion.模块.功能划分.类名
正例 :

com.gillion.oms.entity.Order
com.gillion.oms.entity.enums.OrderStatusEnum
com.gillion.oms.controller.EmployeeController
com.gillion.ods.service.OrderDetailService
com.gillion.smartdata.utils.ZookeeperUtils

在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。 说明 : 不要在方法体内定义 : Pattern pattern = Pattern.compile(规则) ;
注意 Math.random() 这个方法返回是 double 类型，注意取值的范围 (大于等于0小于1) （能够取到零值，注意除零异常），如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后取整，直接使用Random 对象的 nextInt 或者 nextLong 方法。
说明 : 推介使用commons-lang3 的 RandomUtils 和 RandomStringUtils获取当前毫秒数 System.currentTimeMillis() ; 而不是 new Date().getTime() ; 说明 : 如果想获取更加精确的纳秒级时间值，使用 System.nanoTime() 的方式。在 JDK8 中，针对统计时间等场景，推荐使用 Instant 类。
不要在视图模板中加入任何复杂的逻辑。 说明 : 根据 MVC 理论，视图的职责是展示，不要抢模型和控制器的活。
任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。及时清理不再使用的代码段或配置信息。
非对外提供服务的接口、对象不应定义在API 模块中，应归属到Business 或独立的Entity 包Controller 类应该放在controller 包下，不应建立web 包并放在它下面，会有歧义Entity 、VO 、DTO 类应按归属系统进行命名，不应该按业务跨系统定义Controller 中入参空校验不应自己写代码来实现，要统一使用框架的校验controller 层不应对业务对象进行业务性的操作或访问数据库，应只对出入参进行处理有规律的字符串拼接应该优先采用工具类或stream() 处理
反例 :

// 动态构建SQL时，拼接IN条件的占位符 => USERID IN(?, ?, ?...?)
sqlBuilder.append("USERID IN(");
for (int i = 0; i <users.size(); i++) {
sqlBuilder.append("?,")
}
// 去除最后一个多余的逗号
sqlBuilder.setLength(sqlBuilder.length() - 1);
sqlBuilder.append(')');
// 拼接订单详情备注赋值到订单的描述
if (!order.getOrderDetails().isEmpty()) {
StringBuilder orderSummaryBuilder = new StringBuilder();
for (OrderDetail orderDetail : order.getOrderDetails()) {
orderSummaryBuilder.append(orderDetail.getRemark()).append(",");
}
orderSummaryBuilder.setLength(sqlBuilder.length() - 1);
order.setSummary(orderSummaryBuilder.toString());
}
 正例
import org.apache.commons.lang3.StringUtils
String userIdCondition = StringUtils.repeat("?", ",", users.size());
// 拼接方式一
List<String> orderDetailRemarks = order.getOrderDetails().stream()
.map(OrderDetail::getRemark)
.collect(Collectors.toList());
String orderSummary = StringUtils.join(orderDetailRemarks, ",");
order.setSummary(orderSummary);
// 拼接方式二
String orderSummary = order.getOrderDetails().stream()
.map(OrderDetail::getRemark)
.collect(Collectors.joining(","))
order.setSummary(orderSummary);

3.2. Javascript编程规范

代码块必须由函数或者自运行函数包裹， 禁止随意定义全局变量。
反例 :

var $consolePanel = $('#consolePanel');
var a, b;
 正例 :
document.ready(function() {
var $consolePanel = $('#consolePanel');
var a, b;
});
(function() {
var $consolePanel = $('#consolePanel');
var a, b;
...
}());

Dom 对象命名要以简称开头或者全称结尾， jQuery 包装对象要以 $ 开头
正例 :

// <label id="lblName">姓名 : </label>
var lblName = document.getDocumentById('lblName');
var $lblName, $nameLabel = $('#lblName');
// <input id="txtName" name="user.name" type="text" />
var txtName = document.getDocumentById('txtName');
var $txtName, nameText = $('#txtName');
// <input id="numAge" name="user.age" type="number"/>
var $ageNumber, $numAge = $('#numAge');
// 

<div id="consolePanel"></div>

var consolePanel, consolePanelDiv = document.getDocumentById('consolePanel');

 反例 :
// <label id="lblName">姓名 : </label>
var nameLbl = document.getDocumentById('lblName');
var lblName = $('#lblName');

1. 公有对象的私有方法必须以下划线 开头， 并通过文档注释注解@private 标注。 不是公有对象的
   私有方法或者私有属性不得以 下划线 开头。
   正例 :

define('SomeModule', [], function () {
return {
/
 @private
 @cfg {width} 容器宽度
 @cfg {height} 容器高度

@return 容器面积
/
calculateArea: function (width, height) {
return width  height;
}
};
});
 反例 :
define('SomeModule', [], function () {
return {
calculateArea: function (width, height) {
return width  height;
}
};
});

1. 容器节点的事件绑定限定触发元素, 防止后续Dom 结构更改因为冒泡机制导致不可预料的触发。
   正例 :

//
 主面板
$('#mainPanel').click(function(evt) {
var target = evt.target;
if ($(target).is('#mainPanel')) {
...
}
});

1. 迭代数组前预存长度
   正例 :

var ary = ...
var i, len, ele;
for (i = 0, len = ary.length; i < len; i++) {
ele = ary[i];
...
}

反例 :

var ary = ...
for (var i = 0; i < ary.length; i++) {
ele = ary[i];
...
}

说明 : 在老式的浏览器中， ary.length 会被多次计算，浪费性能。
6. 多次操作同一 Dom 对象， 要预存到变量, 因为操作 Dom 是很性能的
反例 :

var name = $('#txtName').val();
var errorMsg = $('#txtName').next().text();
 正例 :
var $txtName = $('#txtName');
var name = $txtName.val();
var errorMsg = $txtName.next().text();

3.3. 异常处理规约

1. Java 类库中定义的一类 RuntimeException 可以通过预先检查进行规避，而不应该通过 catch来处理，比如 : IndexOutOfBoundsException ， NullPointerException 等等。 说明 : 无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过 catch NumberFormatException 来实现。 正例 : if (obj != null) {…} 反例 : try { obj.method() } catch(NullPointerException e) {…}
2. 异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。
3. 对大段代码进行 try-catch ，这是不负责任的表现。catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。
4. 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。
5. 有 try 块放到了事务代码中， catch 异常后，如果需要回滚事务，一定要注意手动回滚事务。
6. finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch 。 说明 : 如果 JDK7及以上，可以使用 try-with-resources 方式。
7. 不能在 finally 块中使用 return ， finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。
8. 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。 说明 : 如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。
9. 方法的返回值可以为 null ，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题。 说明 : 本手册明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失
   败、序列化失败、运行时异常等场景返回 null 的情况。
10. 防止 NPE ，是程序员的基本修养，注意 NPE 产生的场景 :
11. 返回类型为基本数据类型， return 包装数据类型的对象时，自动拆箱有可能产生 NPE 。
    反例 : public int f() { return Integer 对象}， 如果为 nul，自动解箱抛 NPE。
12. 数据库的查询结果可能为 null 。
13. 集合里的元素即使 isNotEmpty ，取出的数据元素也可能为 null 。
14. 远程调用返回对象时，一律要求进行空指针判断，防止 NPE 。
15. 对于 Session 中获取的数据，建议 NPE 检查，避免空指针。
16. 级联调用 obj.getA().getB().getC()； 一连串调用，易产生 NPE 。
    正例 : 使用 JDK8 的 Optional 类来防止 NPE 问题。
17. 定义时区分 unchecked / checked 异常，避免直接抛出 new RuntimeException() ，更不允许抛出 Exception 或者 Throwable ，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，
    如 : DAOException / ServiceException 等。
18. 在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须使用“错误码”；而应用内部推荐异常抛出；跨应用间 RPC 调用优先考虑使用 Result 方式，封装 isSuccess() 方法、“错误码”、“错误简短信息”。 说明 : 关于 RPC 方法返回方式使用 Result 方式的理由 :
19. 使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。
20. 如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message ，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。
21. 避免出现重复的代码（ Don’t Repeat Yourself ），即 DRY 原则。 说明 : 随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。
    正例 : 一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取 :
    private boolean checkParam(DTO dto) {…}
22. throw 异常时应把异常对应的业务信息一起抛出，比如业务对象的类型、ID
23. 业务场景无法处理的异常类型( IO/Socket/Timeout 等)需要统一封装异常类型(比如： extents
    BusinessMustCheckedException )后抛出，并在书写方法时用throws 显示声明异常类型

 正例：
public class UnderstockException extends BusinessMustCheckedException {
public UnderstockException(String message) {
super(message);
}
}
public void deductingTheInventory() throws UnderstockException {
//....
if (...) {
String errorMessage = String.format("库存不足导致扣减库存失败, 预期扣减数: %d,
WbsOrderDetail#orderDetailId: %s"), wbsOrderDetail.getGoodsCount(),
wbsOrderDetail.getOrderDetailId());
throw new UnderstockException(errorMessage);
}
}

3.4. SQL 语句

1. 不要使用 count(列名) 或 count(常量) 来替代 count() ， count() 是 SQL92 定义的标准
   统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。 说明 : count() 会统计值为 NULL 的行，
   而 count(列名) 不会统计此列为 NULL 值的行。
2. count(distinct col) 计算该列除 NULL 之外的不重复行数，注意 count(distinct col1,
   col2) 如果其中一列全为 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 。
5. NULL<>NULL 的返回结果是 NULL ，而不是 false 。
6. NULL=NULL 的返回结果是 NULL ，而不是 true 。
7. NULL<>1 的返回结果是 NULL ，而不是 true 。
8. 在代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。
9. 不得使用外键与级联，一切外键概念必须在应用层解决。 说明 : 以学生和成绩的关系为例，学生表
   中的 studentid 是主键，那么成绩表中的 studentid 则为外键。如果更新学生表中的 studentid ，
   同时触发成绩表中的 studentid 更新，即为级联更新。外键与级联更新适用于单机低并发，不适合分布
   式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风险；外键影响数据库的插入速度。
10. 禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。
11. 数据订正时，删除和修改记录时，要先 select ，避免出现误删除，确认无误才能执行更新语句。
12. in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控制在 1000
    个之内。
13. 如果有全球化需要，所有的字符存储与表示，均以 utf-8 编码，注意字符统计函数的区别。 说明 :
    SELECT LENGTH(“轻松工作”)； 返回为 12
    SELECT CHARACTERLENGTH(“轻松工作”)； 返回为 4
14. TRUNCATE TABLE 比 DELETE 速度快，且使用的系统和事务日志资源少，但 TRUNCATE 无事务且
    不触发 trigger ，有可能造成事故，故不建议在开发代码中使用此语句。
    说明 : TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。
15. 数据是否存在要使用count 进行判断， 不得查询对象然后判断是否为空进行判断。
16. 非特殊情况不得代码中拼接SQL
17. 数据库操作前未判断参数是否有效，如果参数无效比如参数数组为空，则不要进行数据库操作

3.5. ORM 映射

1. 在表查询中，一律不要使用 作为查询的字段列表，需要哪些字段必须明确写明。 说明 :
2. 增加查询分析器解析成本。
3. 增减字段容易与 resultMap 配置不一致。
4. POJO 类的布尔属性不能加 is ，而数据库字段必须加 is ，要求在 resultMap 中进行字段与
   属性之间的映射。 说明 : 参见定义 POJO 类以及数据库字段定义规定，在中增加映射，是必须的。在
   MyBatis Generator 生成的代码中，需要进行对应的修改。
5. 不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要定义；反过
   来，每一个表也必然有一个与之对应。 说明 : 配置映射关系，使字段与 DO 类解耦，方便维护。
6. sql.xml 配置参数使用 : #{} ， #param# 不要使用${} 此种方式容易出现 SQL 注入。
7. iBATIS 自带的 queryForList(String statementName,int start,int size) 不推荐使用。
   说明 : 其实现方式是在数据库取到statementName 对应的SQL 语句的所有记录，再通过 subList 取
   start,size 的子集合。

正例 :
Map map = new HashMap();
map.put("start", start);
map.put("size", size);

1. 不允许直接拿 HashMap 与 Hashtable 作为查询结果集的输出。 说明 :resultClass=”Hashtable” ，会置入字段名和属性值，但是值的类型不可控。
2. 更新数据表记录时，必须同时更新记录对应的 gmtmodified 字段值为当前时间。
3. 不要写一个大而全的数据更新接口。传入为 POJO 类<?A<?A<?A，不管是不是自己的目标更新字段，都进行update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行 SQL时，不要更新无改动的字
   段，一是易出错；二是效率低；三是增加binlog 存储。
4. @Transactional 事务不要滥用。事务会影响数据库的 QPS ，另外使用事务的地方需要考虑各方面的回滚方案，包括缓存回滚、搜索引擎回滚、消息补偿、统计修正等。
5. isEquals中的 compareValue 是与属性值对比的常量，一般是数字，表示相等时带上此条件；表示不为空且不为 null 时执行；表示不为 null 值时执行。

3.6. 推介图书

《代码整洁之道》
《Javascript模式》
《Javascript语言精粹》

3.7. 专有名词

1. POJO （ Plain Ordinary Java Object ）: 在本手册中， POJO 专指只有 setter / getter /
   toString 的简单类，包括 DO/DTO/BO/VO 等。
2. GAV （ GroupId、ArtifactctId、Version ）: Maven 坐标，是用来唯一标识 jar 包。
3. OOP （ Object Oriented Programming ）: 本手册泛指类、对象的编程处理方式。
4. ORM （ Object Relation Mapping ）: 对象关系映射，对象领域模型与底层数据之间的转换，本文泛指
   iBATIS , mybatis 等框架。
5. NPE （ java.lang.NullPointerException ）: 空指针异常。
6. SOA （ Service-Oriented Architecture ）: 面向服务架构，它可以根据需求通过网络对松散 耦合的粗粒
   度应用组件进行分布式部署、组合和使用，有利于提升组件可重用性，可维护性。
7. 一方库: 本工程内部子项目模块依赖的库（ jar 包）。
8. 二方库: 公司内部发布到中央仓库，可供公司内部其它应用依赖的库（ jar 包）。
9. 三方库: 公司之外的开源库（ jar 包）。
10. IDE （ Integrated Development Environment ）: 用于提供程序开发环境的应用程序，一 般包括代码编辑器、编译器、调试器和图形用户界面等工具，本《手册》泛指 IntelliJ IDEA 和 eclipse 。

3.8. 练习

重构如下类，包括完善注释，修复bug并精简代码。可使用commons-lang3 的工具类
功能主要是三种格式日期与字符串的相互转换
注意线程安全

package com.gfa4j.core.utils;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
 Date utility methods.

@author xiezm
public class DateUtils {
public static final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MMdd");
public static final SimpleDateFormat dateTimeFormat = new SimpleDateFormat("yyyy-
MM-dd HH:mm:ss");
public static final SimpleDateFormat monthFormat = new SimpleDateFormat("yyyy-
MM");
public static Date parse(String source) throws ParseException {
if (source == null || source.trim().length() == 0) {
return null;
}
if (source.length() <= dateTimeFormat.toPattern().length()
&& source.length() >= dateTimeFormat.toPattern().length()
- 5) {
try {
return dateTimeFormat.parse(source);
} catch (ParseException ex) {
}
}
if (source.length() <= dateFormat.toPattern().length()
&& source.length() >= dateFormat.toPattern().length() -
2) {
try {
return dateFormat.parse(source);
} catch (ParseException ex) {
}
}
if (source.length() <= monthFormat.toPattern().length()
&& source.length() >= monthFormat.toPattern().length() -
1) {
try {
return monthFormat.parse(source);
} catch (ParseException ex) {
}
}
return dateTimeFormat.parse(source);
}
/
 Parse the Date using pattern "yyyy-MM-dd"

@param source
 @return
 @throws java.text.ParseException
/
public static Date parseDate(String source) throws ParseException {
if (source == null || source.trim().length() == 0) {
return null;
}
return dateFormat.parse(source);
}
/
 Format the Date using pattern "yyyy-MM-dd"

@param date
 @return
/
public static String formatDate(Date date) {
return formatDate(date, null);
}
public static String formatDate(Date date, String defaultValue) {
if (date == null) {
return defaultValue;
}
return dateFormat.format(date);
}
/
 Parse the Date using pattern "yyyy-MM-dd HH:mm:ss"

@param source
 @return
 @throws java.text.ParseException
/
public static Date parseDateTime(String source) throws ParseException {
if (source == null || source.trim().length() == 0) {
return null;
}
return dateTimeFormat.parse(source);
}
/
 Format the Date using pattern "yyyy-MM-dd HH:mm:ss"

@param date
 @return
/
public static String formatDateTime(Date date) {
return formatDateTime(date, null);
}
public static String formatDateTime(Date date, String defaultValue) {
if (date == null) {
return defaultValue;
}
return dateTimeFormat.format(date);
}
/
 Parse the Date using pattern "yyyy-MM"

@param source
 @return
 @throws java.text.ParseException
/
public static Date parseMonth(String source) throws ParseException {
if (source == null || source.trim().length() == 0) {
return null;
}
return monthFormat.parse(source);
}
/
 Format the Date using pattern "yyyy-MM"

@param date
 @return
/
public static String formatMonth(Date date) {
return formatMonth(date, null);
}
public static String formatMonth(Date date, String defaultValue) {
if (date == null) {
return defaultValue;
}
return monthFormat.format(date);
}
}

3. 常用扩展3. 常用扩展

4. 版本更新4. 版本更新