完整下载链接(资源审核中)
前 言
《Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结,经历了多次大规模
一线实战的检验及不断完善,公开到业界后,众多社区开发者踊跃参与,共同打磨完善,系统化地整理成册。现代软件行业的高速发展对开发者的综合素质要求越来越高,因为不仅是编程知识点,其它维度的知识点也会影响到软件的最终交付质量。比如:数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险;工程结构混乱导致后续维护艰难;没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角,划分为编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约七个维度,再根据内容特征,细分成若干二级子目录。
另外,依据约束力强弱及故障敏感性,规约依次分为强制、推荐、参考三大类。在延伸信息中,
“说明”对规约做了适当扩展和解释;“正例”提倡什么样的编码和实现方式;“反例”说明需要提防的雷区,以及真实的错误案例。
手册的愿景是码出高效,码出质量。现代软件架构的复杂性需要协同开发完成,如何高效地协
同呢?无规矩不成方圆,无规范难以协同,比如,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全,试想如果没有限速,没有红绿灯,谁还敢上路行驶?对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率,降低沟通成本。代码的字里行间流淌的是软件系统的血液,质量的提升是尽可能少踩坑,杜绝踩重复的坑,切实提升系统稳定性,码出质量。
我们已经在 2017 杭州云栖大会上发布了配套的 Java 开发规约 IDE 插件,阿里云效也集成了
代码规约扫描引擎。次年,发布 36 万字的配套详解图书《码出高效》,本书秉持“图胜于表,表胜于言”的理念,深入浅出地将计算机基础、面向对象思想、JVM 探源、数据结构与集合、并发与多线程、单元测试等知识客观、立体地呈现出来。紧扣学以致用、学以精进的目标,结合阿里巴巴实践经验和故障案例,与底层源码解析融会贯通,娓娓道来。此书所得收入均捐赠公益事情,希望用技术情怀帮助更多的人。
目录
前言 |
|
一、编程规约 .................................................................................................................................. 1
|
二、异常日志 ............................................................................................................... 24 (一) 异常处理 ................................................................................................................ 24 (二) 日志规约 ................................................................................................................. 26
三、单元测试 ......................................................................................................................... 28 |
四、安全规约 .......................................................................................................................... 30 |
五、MySQL 数据库 ........................................................................................................... 31
|
七、设计规约 ...............................................................................................................................41 |
附 1:版本历史 ...........................................................................................................................43 |
附 2:专有名词解释 .................................................................................................................... 44 |
版本号 |
制定团队 |
更新日期 |
备注 |
1.5.0 |
阿里巴巴与 Java 社区开发者 |
2019.06.19 |
华山版,新增 21 条,修改描述 112 处 |
1. 【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。
正例:JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion 反例:javaserverlessplatform / UserDo / XMLService / TCPUDPDeal / TAPromotion
正例: localValue / getHttpMessage() / inputUserId
正例:MAX_STOCK_COUNT / CACHE_EXPIRED_TIME 反例:MAX_COUNT / EXPIRED_TIME
正例:定义整形数组 int[] arrayDemo; 反例:在 main 参数中,使用 String args[]来定义。
反例:定义为基本数据类型 Boolean isDeleted 的属性,它的方法也是 isDeleted(),RPC 框架在反向解析的时候,“误以为”对应的属性名称是 deleted,导致属性获取不到,进而抛出异常。
正例:应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils(此规则参考 spring 的框架结构)
说明:子类、父类成员变量名相同,即使是 public 类型的变量也是能够通过编译,而局部变量在同一方法内的不同代码块中同名也是合法的,但是要避免使用。对于非 setter/getter 的参数名称也要避免与成员变量名称相同。
反例:
public class ConfusingName { public int age;
// 非 setter/getter 的参数名称,不允许与本类成员变量同名
public void getData(String alibaba) { if(condition) { final int money = 531; // ...
}
for (int i = 0; i < 10; i++) {
// 在同一方法体中,不允许与其它代码块中的 money 命名相同 final int money = 615; // ...
}
}
}
class Son extends ConfusingName {
// 不允许与父类的成员变量名称相同
public int age;
}
反例:AbstractClass“缩写”命名成 AbsClass;condition“缩写”命名成 condi,此类随意缩写严重降低了代码的可阅读性。
正例:在 JDK 中,表达原子更新的类名为:AtomicReferenceFieldUpdater。反例:int a 的随意命名方式。
正例:startTime / workQueue / nameList / TERMINATED_THREAD_COUNT 反例:startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD
说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计理念。
正例: public class OrderFactory; public class LoginProxy; public class ResourceObserver;
正例:接口方法签名 void commit(); 接口基础常量 String COMPANY = "alibaba"; 反例:接口方法定义 public abstract void f(); 说明:JDK8 中接口允许有默认实现,那么这个 default 方法,是对所有实现类都有价值的默认实现。
cache.put(key, value);
// 缓存 get 时,由于在代码复制时,漏掉下划线,导致缓存击穿而出现问题
说明:Long a = 2l; 写的是数字的 21,还是 Long 型的 2。
反例:易懂变量也要统一定义成应用内共享常量,两位工程师在两个类中分别定义了“YES”的变量: 类 A 中:public static final String YES = "yes"; 类 B 中:public static final String YES = "y";
A.YES.equals(B.YES),预期是 true,但实际返回为 false,导致线上问题。
public enum SeasonEnum {
SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
private int seq; SeasonEnum(int seq) { this.seq = seq;
} public int getSeq() { return seq;
}
}
反例:if (空格 a == b 空格)
说明:运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。
说明:如果使用 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");
// 在右大括号后直接结束,则必须换行
}
}
6. 【强制】注释的双斜线与注释内容之间有且仅有一个空格。
// 这是示例注释,请注意在双斜线之后有一个空格
String param = new String();
long first = 1000000000000L; int second = (int)first + 2;
StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下,换行缩进 4 个空格,点号和方法名称一起换行 sb.append("Jack").append("Ma")...
.append("alibaba")...
.append("alibaba")...
.append("alibaba");
反例:
StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下,不要在括号前换行
sb.append("Jack").append("Ma")...append
("alibaba");
// 参数很多的方法调用可能超过 120 个字符,不要在逗号前换行 method(args1, args2, args3, ...
, argsX);
method(args1, args2, args3);
80 行。
正例:代码逻辑分清红花和绿叶,个性和共性,绿叶逻辑单独出来成为额外方法,使主干代码更加清晰;共性逻辑抽取成为共性方法,便于复用和维护。
int one = 1; long two = 2L; float three = 3F;
StringBuilder sb = new StringBuilder();
说明:增加 sb 这个变量,如果需要对齐,则给 one、two、three 都要增加几个空格,在变量比较多的情况下,是非常累赘的事情。
说明:任何情形,没有必要插入多个空行进行隔开。
说明:getObject()与 get0bject()的问题。一个是字母的 O,一个是数字的 0,加@Override 可以准确判断是否覆盖成功。另外,如果在抽象类中对方法签名进行修改,其实现类会马上编译报错。
说明:可变参数必须放置在参数列表的最后。(提倡同学们尽量不用可变参数编程)正例:public List
说明:java.net.URLDecoder 中的方法 decode(String encodeStr) 这个方法已经过时,应该使用双参数
decode(String source, String encode)。接口提供方既然明确是过时接口,那么有义务同时提供新的接口;作为调用方来说,有义务去考证过时方法的新实现是什么。
正例:"test".equals(object); 反例:object.equals("test");
说明:推荐使用 java.util.Objects#equals(JDK7 引入的工具类)。
说明:对于 Integer var = ? 在-128 至 127 范围内的赋值,Integer 对象是在 IntegerCache.cache 产生,会复用已有对象,这个区间内的 Integer 值可以直接使用==进行判断,但是这个区间之外的所有数据,都会在堆上产生,并不会复用已有对象,这是一个大坑,推荐使用 equals 方法进行判断。
说明:浮点数采用“尾数+阶码”的编码方式,类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分的十进制小数,具体原理参考《码出高效》。
float a = 1.0f - 0.9f; float b = 0.9f - 0.8f;
if (a == b) {
// 预期进入此代码快,执行其它业务逻辑
// 但事实上a==b的结果为false
}
Float x = Float.valueOf(a); Float y = Float.valueOf(b); if (x.equals(y)) {
// 预期进入此代码快,执行其它业务逻辑
// 但事实上equals的结果为false
}
if (Math.abs(a - b) < diff) {
System.out.println("true");
}
BigDecimal a = new BigDecimal("1.0");
BigDecimal b = new BigDecimal("0.9");
BigDecimal c = new BigDecimal("0.8");
BigDecimal x = a.subtract(b);
BigDecimal y = b.subtract(c);
if (x.equals(y)) {
System.out.println("true");
}
正例:数据库字段的 bigint 必须与类属性的 Long 类型相对应。
反例:某个案例的数据库表 id 字段定义类型 bigint unsigned,实际类对象属性为 Integer,随着 id 越来越大,超过 Integer 的表示范围而溢出成为负数。
如:BigDecimal g = new BigDecimal(0.1f); 实际的存储值为:0.10000000149
正例:优先推荐入参为 String 的构造方法,或使用 BigDecimal 的 valueOf 方法,此方法内部其实执行了 Double 的 toString,而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。
BigDecimal recommend1 = new BigDecimal("0.1");
BigDecimal recommend2 = BigDecimal.valueOf(0.1);
说明:POJO 类属性没有初值是提醒使用者在需要使用时,必须自己显式地进行赋值,任何 NPE 问题,或者入库检查,都由使用者来保证。
正例:数据库的查询结果可能是 null,因为自动拆箱,用基本数据类型接收有 NPE 风险。
反例:比如显示成交总额涨跌情况,即正负 x%,x 为基本数据类型,调用的 RPC 服务,调用不成功时,返回的是默认值,页面显示为 0%,这是不合理的,应该显示成中划线。所以包装数据类型的 null 值,能够表示额外的信息,如:远程调用失败,异常退出。
反例:POJO 类的 createTime 默认值为 new Date(),但是这个属性在数据提取时并没有置入具体值,在更新其它字段时又附带更新了此字段,导致创建时间被修改成当前时间。
说明:注意 serialVersionUID 不一致会抛出序列化运行时异常。
说明:在方法执行抛出异常时,可以直接调用 POJO 的 toString()方法打印其属性值,便于排查问题。
说明:框架在调用属性 xxx 的提取方法时,并不能确定哪个方法一定是被优先调用到。
String str = "a,b,c,,";
String[] ary = str.split(",");
// 预期大于 3,结果是 3
System.out.println(ary.length);
说明:公有方法是类的调用者和维护者最关心的方法,首屏展示最好;保护方法虽然只是子类关心,也可能是“模板设计模式”下的核心方法;而私有方法外部一般不需要特别关心,是一个黑盒实现;因为承载的信息价值较低,所有 Service 和 DAO 的 getter/setter 方法放在类体最后。
反例:
public Integer getData() { if (condition) {
return this.data + 100;
} else {
return this.data - 100;
}
}
21. 【推荐】循环体内,字符串的连接方式,使用 StringBuilder 的 append 方法进行扩展。
说明:下例中,反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象,然后进行 append 操作,最后通过 toString 方法返回 String 对象,造成内存资源浪费。
反例:
String str = "start";
for (int i = 0; i < 100; i++) { str = str + "hello";
}
说明:对象 clone 方法默认是浅拷贝,若想实现深拷贝需覆写 clone 方法实现域对象的深度遍历式拷贝。
说明:任何类、方法、参数、变量,严控访问范围。过于宽泛的访问范围,不利于模块解耦。思考:如果是一个 private 的方法,想删除就删除,可是一个 public 的 service 成员方法或成员变量,删除一下,不得手心冒点汗吗?变量像自己的小孩,尽量在自己的视线内,变量作用域太大,无限制的到处跑,那么你会担心的。
说明:subList 返回的是 ArrayList 的内部类 SubList,并不是 ArrayList 而是 ArrayList 的一个视图,对于 SubList 子列表的所有操作最终会反映到原列表上。
反例:如果查询无结果,返回 Collections.emptyList()空集合对象,调用方一旦进行了添加元素的操作,就
会触发 UnsupportedOperationException 异常。
反例:直接使用 toArray 无参方法存在问题,此方法返回值只能是 Object[]类,若强转其它类型数组将出
现 ClassCastException 错误。
List
String[] array = list.toArray(new String[0]); 说明:使用 toArray 带参方法,数组空间大小的 length:
说明:在 ArrayList#addAll 方法的第一行代码即 Object[] a = c.toArray(); 其中 c 为输入集合参数,如果为 null,则直接抛出异常。
String[] str = new String[] { "yang", "hao" }; List list = Arrays.asList(str);
第一种情况:list.add("yangguanbao"); 运行时异常。第二种情况:str[0] = "changed"; 也会随之修改,反之亦然。
说明:扩展说一下 PECS(Producer Extends Consumer Super)原则:第一、频繁往外读取内容的,适合用 extends T>。第二、经常往里插入的,适合用 super T>
说明:毕竟泛型是在 JDK5 后才出现,考虑到向前兼容,编译器是允许非泛型集合与泛型集合互相赋值。反例:
List<String> generics = null; List notGenerics = new ArrayList(10); notGenerics.add(new Object()); notGenerics.add(new Integer(1));
generics = notGenerics;
// 此处抛出 ClassCastException 异常
String string = generics.get(0);
List
Iterator
String item = iterator.next(); if (删除元素的条件) { iterator.remove(); }
}
反例:
for (String item : list) { if ("1".equals(item)) { list.remove(item);
}
}
说明:以上代码的执行结果肯定会出乎大家的意料,那么试一下把“1”换成“2”,会是同样的结果吗?
Collections.sort 会抛 IllegalArgumentException 异常。
说明:三个条件如下
反例:下例中没有处理相等的情况,交换两个对象判断结果并不互反,不符合第一个条件,在实际使用中 可能会出现异常。
new Comparator
@Override public int compare(Student o1, Student o2) { return o1.getId() > o2.getId() ? 1 : -1; }
};
说明:菱形泛型,即 diamond,直接使用<>来指代前边已经指定的类型。
// diamond 方式,即<>
HashMap
// 全省略方式
ArrayList
说明:HashMap 使用 HashMap(int initialCapacity) 初始化。
正例:initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子(即 loader factor)默认为 0.75,如果暂时无法确定初始值大小,请设置为 16(即默认值)。
反例:HashMap 需要放置 1024 个元素,由于没有设置容量初始大小,随着元素不断增加,容量 7 次被迫扩大,resize 需要重建 hash 表,严重影响性能。
正例:values()返回的是 V 值集合,是一个 list 集合对象;keySet()返回的是 K 值集合,是一个 Set 集合对象;entrySet()返回的是 K-V 值组合集合。
集合类 |
Key |
Value |
Super |
说明 |
Hashtable |
不允许为 null |
不允许为 null |
Dictionary |
线程安全 |
ConcurrentHashMap |
不允许为 null |
不允许为 null |
AbstractMap |
锁分段技术(JDK8:CAS) |
TreeMap |
不允许为 null |
允许为 null |
AbstractMap |
线程不安全 |
HashMap |
允许为 null |
允许为 null |
AbstractMap |
线程不安全 |
反例:由于 HashMap 的干扰,很多人认为 ConcurrentHashMap 是可以置入 null 值,而事实上,存储 null 值时会抛出 NPE 异常。
说明:有序性是指遍历的结果是按某种比较规则依次排列的。稳定性指集合每次遍历的元素次序是一定的。如:ArrayList 是 order/unsort;HashMap 是 unorder/unsort;TreeSet 是 order/sort。
public class UserThreadFactory implements ThreadFactory {
private final String namePrefix; private final AtomicInteger nextId = new AtomicInteger(1);
// 定义线程组名称,在jstack问题排查时,非常有帮助
UserThreadFactory(String whatFeaturOfGroup) { namePrefix = "From UserThreadFactory's " + whatFeaturOfGroup + "-Worker-"; }
@Override
public Thread newThread(Runnable task) {
String name = namePrefix + nextId.getAndIncrement();
Thread thread = new Thread(null, task, name, 0, false);
System.out.println(thread.getName()); return thread; }
}
说明:Executors 返回的线程池对象的弊端如下:
1) FixedThreadPool 和 SingleThreadPool:
允许的请求队列长度为 Integer.MAX_VALUE,可能会堆积大量的请求,从而导致 OOM。
允许的创建线程数量为 Integer.MAX_VALUE,可能会创建大量的线程,从而导致 OOM。
private static final ThreadLocal
@Override protected DateFormat initialValue() { return new SimpleDateFormat("yyyy-MM-dd");
}
};
说明:如果是 JDK8 的应用,可以使用 Instant 代替 Date,LocalDateTime 代替 Calendar,
DateTimeFormatter 代替 SimpleDateFormat,官方给出的解释:simple beautiful strong immutable thread-safe。
尽量在代理中使用 try-finally 块进行回收。正例:
objectThreadLocal.set(userInfo); try { // ... } finally { objectThreadLocal.remove();
}
说明二:如果 lock 方法在 try 代码块之内,可能由于其它方法抛出异常,导致在 finally 代码块中, unlock 对未加锁的对象解锁,它会调用 AQS 的 tryRelease 方法(取决于具体实现类),抛出
IllegalMonitorStateException 异常。说明三:在 Lock 对象的 lock 方法实现中可能抛出 unchecked 异常,产生的后果与说明二相同。
正例:
Lock lock = new XxxLock();
// ...
lock.lock(); try {
doSomething(); doOthers();
} finally { lock.unlock();
} 反例:
Lock lock = new XxxLock();
// ... try {
// 如果此处抛出异常,则直接执行 finally 代码块
doSomething();
// 无论加锁是否成功,finally 代码块都会执行 lock.lock(); doOthers();
} finally { lock.unlock();
}
10. 【强制】在使用尝试机制来获取锁的方式中,进入业务代码块之前,必须先判断当前线程是否持有锁。锁的释放规则与锁的阻塞等待方式相同。
说明:Lock 对象的 unlock 方法在执行时,它会调用 AQS 的 tryRelease 方法(取决于具体实现类),如果当前线程不持有锁,则抛出 IllegalMonitorStateException 异常。正例:
Lock lock = new XxxLock();
// ...
boolean isLocked = lock.tryLock(); if (isLocked) { try { doSomething();
doOthers(); } finally { lock.unlock();
}
}
ScheduledExecutorService 则没有这个问题。
说明:注意,子线程抛出异常堆栈,不能在主线程 try-catch 到。
说明:Random 实例包括 java.util.Random 的实例或者 Math.random()的方式。
正例:在 JDK7 之后,可以直接使用 API ThreadLocalRandom,而在 JDK7 之前,需要编码保证每个线程持有一个实例。
问题隐患(可参考 The "Double-Checked Locking is Broken" Declaration),推荐解决方案中较为简单一种(适用于 JDK5 及以上版本),将目标属性声明为 volatile 型。
反例:
public class LazyInitDemo { private Helper helper = null; public Helper getHelper() { if (helper == null) synchronized(this) { if (helper == null) helper = new Helper();
} return helper;
}
// other methods and fields...
}
说明:如果是 count++操作,使用如下类实现:AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 如果是 JDK8,推荐使用 LongAdder 对象,比 AtomicLong 性能更好(减少乐观锁的重试次数)。
的)都可以操控这个变量。
public class SwitchString { public static void main(String[] args) { method(null);
}
public static void method(String param) { switch (param) {
// 肯定不是进入这里 case "sth":
System.out.println("it's sth"); break;
// 也不是进入这里 case "null":
System.out.println("it's null"); break;
// 也不是进入这里 default:
System.out.println("default");
}
}
}
说明:即使只有一行代码,避免采用单行的编码方式:if (condition) statements;
反例:判断剩余奖品数量等于 0 时,终止发放奖品,但因为并发处理错误导致奖品数量瞬间变成了负数,这样的话,活动无法终止。
if (condition) { ...
return obj;
}
// 接着写 else 的业务逻辑代码; 说明:如果非使用 if()...else if()...else...方式表达逻辑,避免后续代码维护困难,【强制】请勿超过 3 层。 正例:超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现,其中卫语句即代码逻辑先考虑失败、异常、中断、退出等直接返回的情况,以方法多个出口的方式,解决代码中判断分支嵌套的问题,这是逆向思维的体现。示例如下:
public void findBoyfriend(Man man) { if (man.isUgly()) {
System.out.println("本姑娘是外貌协会的资深会员");
return;
}
if (man.isPoor()) {
System.out.println("贫贱夫妻百事哀");
return;
}
if (man.isBadTemper()) {
System.out.println("银河有多远,你就给我滚多远");
return;
}
System.out.println("可以先交往一段时间看看");
}
6. 【推荐】除常用方法(如 getXxx/isXxx)等外,不要在条件判断中执行其它复杂的语句,将复杂逻辑判断的结果赋值给一个有意义的布尔变量名,以提高可读性。说明:很多 if 语句内的逻辑表达式相当复杂,与、或、取反混合运算,甚至各种方法纵深调用,理解成本非常高。如果赋值一个非常好理解的布尔变量名字,则是件令人爽心悦目的事情。
// 伪代码如下
final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed) {
...
}
反例:
public final void acquire(long arg) { if (!tryAcquire(arg) &&
acquireQueued(addWaiter(Node.EXCLUSIVE), arg)) { selfInterrupt();
}
}
7. 【推荐】不要在其它表达式(尤其是条件表达式)中,插入赋值语句。
说明:赋值点类似于人体的穴位,对于代码的理解至关重要,所以赋值语句需要清晰地单独成为一行。
反例:
public Lock getLock(boolean fair) {
// 算术表达式中出现赋值操作,容易忽略 count 值已经被改变 threshold = (count = Integer.MAX_VALUE) - 1;
// 条件表达式中出现赋值操作,容易误认为是 sync==fair
return (sync = fair) ? new FairSync() : new NonfairSync();
}
说明:取反逻辑不利于快速理解,并且取反逻辑写法必然存在对应的正向逻辑写法。
正例:使用 if (x < 628) 来表达 x 小于 628。
反例:使用 if (!(x >= 628)) 来表达 x 小于 628。
// xxx 方式。
说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。
说明:对子类的实现要求,或者调用注意事项,请一并说明。
反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。
说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。
说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没有备注信
息,难以知晓注释动机。后者建议直接删掉(代码仓库已然保存了历史代码)。
// put elephant into fridge put(elephant, fridge);
方法名 put,加上两个有意义的变量名 elephant 和 fridge,已经说明了这是在干什么,语义清晰的代码不需要额外的注释。
11. 【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc 还没 有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个 Javadoc 标签)。
在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况。
说明:不要在方法体内定义:Pattern pattern = Pattern.compile(“规则”);
说明:注意如果是 Boolean 包装类对象,优先调用 getXxx()的方法。
说明:如果 var 等于 null 或者不存在,那么${var}会直接显示在页面上。
说明:如果想获取更加精确的纳秒级时间值,使用 System.nanoTime()的方式。在 JDK8 中,针对统计时间等场景,推荐使用 Instant 类。
说明:日期格式化时,yyyy表示当天所在的年,而大写的YYYY代表是week in which year
(JDK7 之后引入的概念),意思是当天所在的周属于的年份,一周从周日开始,周六结束,只要本周跨年,返回的YYYY就是下一年。另外需要注意:
正例:表示日期和时间的格式如下所示:
new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
说明:根据 MVC 理论,视图的职责是展示,不要抢模型和控制器的活。
说明:对于垃圾代码或过时配置,坚决清理干净,避免程序过度臃肿,代码冗余。
正例:对于暂时被注释掉,后续可能恢复使用的代码片断,在注释代码上方,统一规定使用三个斜杠(///)
来说明注释掉代码的理由。
过 catch 的方式来处理,比如:NullPointerException,IndexOutOfBoundsException 等等。
说明:无法通过预检查的异常除外,比如,在解析字符串形式的数字时,可能存在数字格式错误,不得不通过 catch NumberFormatException 来实现。
正例:if (obj != null) {...}
反例:try { obj.method(); } catch (NullPointerException e) {…}
说明:异常设计的初衷是解决程序运行中的各种意外情况,且异常的处理效率比条件判断方式要低很多。
对于非稳定代码的 catch 尽可能进行区分异常类型,再做对应的异常处理。
说明:对大段代码进行 try-catch,使程序无法根据不同的异常做出正确的应激反应,也不利于定位问题,这是一种不负责任的表现。
正例:用户注册的场景中,如果用户输入非法字符,或用户名称已存在,或用户输入密码过于简单,在程序上作出分门别类的判断,并提示给用户。
说明:如果 JDK7 及以上,可以使用 try-with-resources 方式。
说明:try 块中的 return 语句执行成功后,并不马上返回,而是继续执行 finally 块中的语句,如果此处存在 return 语句,则在此直接返回,无情丢弃掉 try 块中的返回点。
private int x = 0; public int checkReturn() { try {
// x 等于 1,此处不返回 return ++x;
} finally {
// 返回的结果是 2 return ++x;
}
}
说明:如果预期对方抛的是绣球,实际接到的是铅球,就会产生意外情况。
说明:通过反射机制来调用方法,如果找不到方法,抛出 NoSuchMethodException。什么情况会抛出
NoSuchMethodError 呢?二方包在类冲突时,仲裁机制可能导致引入非预期的版本使类的方法签名不匹
配,或者在字节码修改框架(比如:ASM)动态创建或修改类时,修改了相应的方法签名。这些情况,即
使代码编译期是正确的,但在代码运行期时,会抛出 NoSuchMethodError。
说明:本手册明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象,对调用者来说,也并非高枕无忧,必须考虑到远程调用失败、序列化失败、运行时异常等场景返回 null 的情况。
反例:public int f() { return Integer 对象}, 如果为 null,自动解箱抛 NPE。
正例:使用 JDK8 的 Optional 类来防止 NPE 问题。
说明:关于 RPC 方法返回方式使用 Result 方式的理由:
说明:随意复制和粘贴代码,必然会导致代码的重复,在以后需要修改时,需要修改所有的副本,容易遗漏。必要时抽取共性方法,或者抽象公共类,甚至是组件化。
正例:一个类中有多个 public 方法,都需要进行数行相同的参数校验操作,这个时候请抽取:
private boolean checkParam(DTO dto) {...}
import org.slf4j.Logger; import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(Test.class);
appName_logType_logName.log。logType:日志类型,如 stats/monitor/access 等;logName:日志描述。这种命名的好处:通过文件名就可知道日志文件属于什么应用,什么类型,什么目的,也有利于归类查找。说明:推荐对日志进行分类,如将错误日志和业务日志分开存放,便于开发人员查看,也便于通过日志对系统进行及时监控。
正例:force-web 应用中单独监控时区转换异常,如:force_web_timeZoneConvert.log
说明:因为 String 字符串的拼接会使用 StringBuilder 的 append()方式,有一定的性能损耗。使用占位符仅是替换动作,可以有效提升性能。
正例:logger.debug("Processing trade with id: {} and symbol: {}", id, symbol);
说明:虽然在 debug(参数)的方法体内第一行代码 isDisabled(Level.DEBUG_INT)为真时(Slf4j 的常见实现 Log4j 和 Logback),就直接 return,但是参数可能会进行字符串拼接运算。此外,如果 debug(getName())这种参数内有 getName()方法调用,无谓浪费方法调用的开销。
// 如果判断为真,那么可以输出trace和debug级别的日志
if (logger.isDebugEnabled()) { logger.debug("Current ID is: {} and name is: {}", id, getName()); }
正例:
正例:logger.error(各类参数或者对象 toString() + "_" + e.getMessage(), e);
说明:大量地输出无效日志,不利于系统性能提升,也不利于快速定位错误点。记录日志时请思考:这些日志真的有人看吗?看到这条日志你能做什么?能不能给问题排查带来好处?
说明:注意日志输出的级别,error 级别只记录系统逻辑出错、异常或者重要的错误信息。
说明:单元测试在线上运行时,感觉像空气(AIR)一样并不存在,但在测试质量的保障上,却是非常关键的。好的单元测试宏观上来说,具有自动化、独立性、可重复执行的特点。
反例:method2 需要依赖 method1 的执行,将执行结果作为 method2 的输入。
说明:单元测试通常会被放到持续集成中,每次有代码 check in 时单元测试都会被执行。如果单测对外部环境(网络、服务、中间件等)有依赖,容易导致持续集成机制的不可用。
正例:为了不受外界环境影响,要求设计代码时就把 SUT 的依赖改成注入,在测试时用 spring 这样的 DI 框架注入一个本地(内存)实现或者 Mock 实现。
说明:只有测试粒度小才能在出错时尽快定位到出错位置。单测不负责检查跨类或者跨系统的交互逻辑,那是集成测试的领域。
说明:新增代码及时补充单元测试,如果新增代码影响了原有单元测试,请及时修正。
说明:在工程规约的应用分层中提到的 DAO 层,Manager 层,可重用度高的 Service,都应该进行单元测试。
反例:删除某一行数据的单元测试,在数据库中,先直接手动增加一行作为删除目标,但是这一行新增数据并不符合业务插入规则,导致测试结果异常。
正例:在企业智能事业部的内部单元测试中,使用ENTERPRISE_INTELLIGENCE _UNIT_TEST_的前缀来标识单元测试相关代码。
说明:多层条件语句建议使用卫语句、策略模式、状态模式等方式重构。
说明:防止没有做水平权限校验就可随意访问、修改、删除别人的数据,比如查看他人的私信内容、修改他人的订单。
说明:中国大陆个人手机号码显示为:137****0969,隐藏中间 4 位,防止隐私泄露。
说明:忽略参数校验可能导致:
说明:Java 代码用正则来验证客户端的输入,有些正则写法验证普通用户输入没有问题,但是如果攻击人员使用的是特殊构造的字符串来验证,有可能导致死循环的结果。
说明:CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在 CSRF 漏洞的应用
/网站,攻击者可以事先构造好 URL,只要受害者用户一访问,后台便在用户不知情的情况下对数据库中用户参数进行相应修改。
说明:如注册时发送验证码到手机,如果没有限制次数和频率,那么可以利用此功能骚扰到其它用户,并造成短信平台资源浪费。
说明:任何字段如果为非负数,必须是 unsigned。
注意:POJO 类中的任何布尔类型的变量,都不要加 is 前缀,所以,需要在<resultMap>设置从 is_xxx 到 Xxx 的映射关系。数据库表示是与否的值,使用 tinyint 类型,坚持 is_xxx 的命名方式是为了明确其取值含义与取值范围。
正例:表达逻辑删除的字段名 is_deleted,1 表示删除,0 表示未删除。
说明:MySQL 在 Windows 下不区分大小写,但在 Linux 下默认是区分大小写。因此,数据库名、表名、字段名,都不允许出现任何大写字母,避免节外生枝。
正例:aliyun_admin,rdc_config,level3_name
反例:AliyunAdmin,rdcConfig,level_3_name
说明:表名应该仅仅表示表里面的实体内容,不应该表示实体数量,对应于 DO 类名也是单数形式,符合表达习惯。
说明:pk_ 即 primary key;uk_ 即 unique key;idx_ 即 index 的简称。
说明:在存储的时候,float 和 double 都存在精度损失的问题,很可能在比较值的时候,得到不正确的结果。如果存储的数据范围超过 decimal 的范围,建议将数据拆成整数和小数并分开存储。
说明:其中 id 必为主键,类型为 bigint unsigned、单表时自增、步长为 1。create_time, update_time 的类型均为 datetime 类型。
正例:alipay_task / force_project / trade_config
正例:商品类目名称使用频率高,字段长度短,名称基本一不变,可在相关联的表中冗余存储类目名 称,避免关联查询。
说明:如果预计三年后的数据量根本达不到这个级别,请不要在创建表时就分库分表。
正例:如下表,其中无符号值可以避免误存负数,且扩大了表示范围。
对象 |
年龄区间 |
类型 |
字节 |
表示范围 |
人 |
150 岁之内 |
tinyint unsigned |
1 |
无符号值:0 到 255 |
龟 |
数百岁 |
smallint unsigned |
2 |
无符号值:0 到 65535 |
恐龙化石 |
数千万年 |
int unsigned |
4 |
无符号值:0 到约 42.9 亿 |
太阳 |
约 50 亿年 |
bigint unsigned |
8 |
无符号值:0 到约 10 的 19 次方 |
说明:不要以为唯一索引影响了 insert 速度,这个速度损耗可以忽略,但提高查找速度是明显的;另外,即使在应用层做了非常完善的校验控制,只要没有唯一索引,根据墨菲定律,必然有脏数据产生。
说明:即使双表 join 也要注意表索引、SQL 性能。
说明:索引的长度与区分度是一对矛盾体,一般对字符串类型数据,长度为 20 的索引,区分度会高达
90%以上,可以使用 count(distinct left(列名, 索引长度))/count(*)的区分度来确定。
说明:索引文件具有 B-Tree 的最左前缀匹配特性,如果左边的值未确定,那么无法使用此索引。
正例:where a=? and b=? order by c; 索引:a_b_c
反例:索引如果存在范围查询,那么索引有序性无法利用,如:WHERE a>10 ORDER BY b; 索引 a_b 无法排序。
说明:如果一本书需要知道第 11 章是什么标题,会翻开第 11 章对应的那一页吗?目录浏览一下就好,这个目录就是起到覆盖索引的作用。
正例:能够建立索引的种类分为主键索引、唯一索引、普通索引三种,而覆盖索引只是一种查询的一种效果,用 explain 的结果,extra 列会出现:using index。
说明: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
反例:explain 表的结果,type=index,索引物理文件全扫描,速度非常慢,这个 index 级别比较 range 还低,与全表扫描是小巫见大巫。
正例:如果 where a=? and b=? ,如果 a 列的几乎接近于唯一值,那么只需要单建 idx_a 索引即可。说明:存在非等号和等号混合时,在建索引时,请把等号条件的列前置。如:where c>? and d=? 那么即使 c 的区分度更高,也必须把 d 放在索引的最前列,即索引 idx_d_c。
说明:count(*)会统计值为 NULL 的行,而 count(列名)不会统计此列为 NULL 值的行。
正例:使用如下方式来避免 sum 的 NPE 问题:SELECT IFNULL(SUM(column), 0) FROM table;
说明:NULL 与任何值的直接比较都为 NULL。
说明:以学生和成绩的关系为例,学生表中的 student_id 是主键,那么成绩表中的 student_id 则为外
键。如果更新学生表中的 student_id,同时触发成绩表中的 student_id 更新,即为级联更新。外键与级联更新适用于单机低并发,不适合分布式、高并发集群;级联更新是强阻塞,存在数据库更新风暴的风险;外键影响数据库的插入速度。
SELECT LENGTH("轻松工作"); 返回为 12
SELECT CHARACTER_LENGTH("轻松工作"); 返回为 4
如果需要存储表情,那么选择 utf8mb4 来进行存储,注意它与 utf-8 编码的区别。
11. 【参考】TRUNCATE TABLE 比 DELETE 速度快,且使用的系统和事务日志资源少,但
TRUNCATE 无事务且不触发 trigger,有可能造成事故,故不建议在开发代码中使用此语句。
说明:TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。
说明:1)增加查询分析器解析成本。2)增减字段容易与 resultMap 配置不一致。3)无用字段增加网络消耗,尤其是 text 类型的字段。
说明:参见定义 POJO 类以及数据库字段定义规定,在
MyBatis Generator 生成的代码中,需要进行对应的修改。
说明:配置映射关系,使字段与 DO 类解耦,方便维护。
说明:其实现方式是在数据库取到 statementName 对应的 SQL 语句的所有记录,再通过 subList 取 start,size 的子集合。
正例:Map
map.put("start", start); map.put("size", size);
说明:resultClass=”Hashtable”,会置入字段名和属性值,但是值的类型不可控。
字段,都进行 update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行 SQL 时,不要更新无改动的字段,一是易出错;二是效率低;三是增加 binlog 存储。
Web 层,也可以直接依赖于 Service 层,依此类推:
行 catch,使用 catch(Exception e)方式,并 throw new DAOException(e),不需要打印日志,因为日志在 Manager/Service 层一定需要捕获并打印到日志文件中去,如果同台服务器再打日志,浪费性能和存储。在 Service 层出现异常时,必须记录出错日志到磁盘,尽可能带上参数信息,相当于保护案发现场。如果 Manager 层与 Service 同机部署,日志方式与 DAO 层处理一致,如果是单独部署,则采用与 Service 一致的处理方式。Web 层绝不应该继续往上抛异常,因为已经处于顶层,如果意识到这个异常将导致页面无法正常渲染,那么就应该直接跳转到友好错误页面,加上用户容易理解的错误提示信息。开放接口层要将异常处理成错误码和错误信息方式返回。
说明:{公司/BU} 例如:alibaba/taobao/tmall/aliexpress 等 BU 一级;子业务线可选。
正例:com.taobao.jstorm 或 com.alibaba.dubbo.register
正例:dubbo-client / fastjson-api / jstorm-tool
说明:注意起始版本号必须为:1.0.0,而不是 0.0.1,正式发布的类库必须先去中央仓库进行查证,使版本号有延续性,正式版本号不允许覆盖升级。如当前版本:1.3.3,那么下一个合理的版本号:1.3.4 或
1.4.0 或 2.0.0
说明:不依赖 SNAPSHOT 版本是保证应用发布的幂等性。另外,也可以加快编译时的打包构建。
说明:在升级时,进行 dependency:resolve 前后信息比对,如果仲裁结果完全不一致,那么通过 dependency:tree 命令,找出差异点,进行
说明:依赖 springframework-core,-context,-beans,它们都是同一个版本,可以定义一个变量来保存版本:${spring.version},定义依赖的时候,引用该版本。
Version。
说明:在本地调试时会使用各子项目指定的版本号,但是合并成一个 war,只能有一个版本号出现在最后的 lib 目录中。可能出现线下调试是正确的,发布到线上却出故障的问题。
<dependencyManagement>语句块中。
说明:
赖,version 和 scope 都读取自父 pom。而
类、常量、枚举等。如果依赖其它二方库,尽量是 provided 引入,让二方库使用者去依赖具体版本号;无 log 具体实现,只依赖日志框架。
除非用户主动升级版本,否则公共二方库的行为不应该发生变化。
说明:操作系统默认 240 秒后,才会关闭处于 time_wait 状态的连接,在高并发访问下,服务器端会因为
处于 time_wait 的连接数太多,可能无法建立新的连接,所以需要在服务器上调小此等待值。
正例:在 linux 服务器上请通过变更/etc/sysctl.conf 文件去修改该缺省值(秒): net.ipv4.tcp_fin_timeout = 30
说明:主流操作系统的设计是将 TCP/UDP 连接采用与文件一样的方式去管理,即一个连接对应于一个
fd。主流的 linux 服务器默认所支持最大 fd 数量为 1024,当并发连接数很大时很容易因为 fd 不足而出现 “open too many files”错误,导致新的连接无法建立。建议将 linux 服务器所支持的最大句柄数调高数倍(与服务器的内存数量相关)。
OOM 场景时输出 dump 信息。
说明:OOM 的发生是有概率的,甚至相隔数月才出现一例,出错时的堆内信息对解决问题非常有帮助。
说明:有缺陷的底层数据结构容易导致系统风险上升,可扩展性下降,重构成本也会因历史数据迁移和系统平滑过渡而陡然增加,所以,存储方案和数据结构需要认真地进行设计和评审,生产环境提交执行后,需要进行 double check。
正例:评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发展、表或字段之间的辩证关系、字段名称、字段类型、索引等;数据结构变更(如在原有表中新增字段)也需要进行评审通过后上线。
说明:状态图的核心是对象状态,首先明确对象有多少种状态,然后明确两两状态之间是否存在直接转换关系,再明确触发状态转换的条件是什么。
正例:淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。
说明:时序图反映了一系列对象间的交互与协作关系,清晰立体地反映系统的调用纵深链路。
说明:类图像建筑领域的施工图,如果搭平房,可能不需要,但如果建造蚂蚁 Z 空间大楼,肯定需要详细的施工图。
说明:活动图是流程图的扩展,增加了能够体现协作关系的对象泳道,支持表示并发等。
反例:用户在淘宝付款过程中,银行扣款成功,发送给用户扣款成功短信,但是支付宝入款时由于断网演练产生异常,淘宝订单页面依然显示未付款,导致用户投诉。
说明:单一原则最易理解却是最难实现的一条规则,随着系统演进,很多时候,忘记了类设计的初衷。
说明:不得已使用继承的话,必须符合里氏代换原则,此原则说父类能够出现的地方子类一定能够出现,比如,“把钱交出来”,钱的子类美元、欧元、人民币等都可以出现。
说明:低层次模块依赖于高层次模块的抽象,方便系统间的解耦。
说明:极端情况下,交付线上生产环境的代码都是不可修改的,同一业务域内的需求变化,通过模块或类的扩展来实现。
说明:随着代码的重复次数不断增加,维护成本指数级上升。
说明:敏捷开发是快速交付迭代可用的系统,省略多余的设计方案,摒弃传统的审批流程,但核心关键点上的必要设计和文档沉淀是需要的。
反例:某团队为了业务快速发展,敏捷成了产品经理催进度的借口,系统中均是勉强能运行但像面条一样的代码,可维护性和可扩展性极差,一年之后,不得不进行大规模重构,得不偿失。
说明:避免为了设计而设计,系统设计文档有助于后期的系统维护和重构,所以设计结果需要进行分类归档保存。
说明:世间众多设计模式目的是相同的,即隔离系统变化点。
附 1:版本历史
版本号 |
版本名 |
更新日期 |
备注 |
-- |
-- |
2016.12.07 |
试读版本首次对外发布 |
1.0.0 |
正式版 |
2017.02.09 |
阿里巴巴集团正式对外发布 |
1.0.1 |
-- |
2017.02.13 |
|
1.0.2 |
-- |
2017.02.20 |
1)去除文底水印。2)数据类型中引用太阳系年龄问题。3)修正关于异常和方法签名的部分描述。4)修正 final 描述。5)去除 Comparator 部分描述。 |
1.1.0 |
-- |
2017.02.27 |
1)增加前言。2)增加 extends T>描述和说明。3)增加版本历史。4)增加专有名词解释。 |
1.1.1 |
-- |
2017.03.31 |
修正页码总数和部分示例。 |
1.2.0 |
完美版 |
2017.05.20 |
1)根据云栖社区的“聚能聊”活动反馈,对手册的页码、排版、描述进行修正。2)增加 final 的适用场景描述。3)增加关于锁的粒度的说明。4)增加“指定集合大 小”的详细说明以及正反例。5)增加卫语句的示例代码。6)明确数据库表示删除概念的字段名为 is_deleted |
1.3.0 |
终极版 |
2017.09.25 |
增加单元测试规约,阿里开源的 IDE 代码规约检测插件:点此下载 |
1.3.1 |
纪念版 |
2017.11.30 |
修正部分描述;采用和 P3C 开源 IDE 检测插件相同的 Apache2.0 协议。 |
1.4.0 |
详尽版 |
2018.05.20 |
增加设计规约大类,共 16 条。 |
1.5.0 |
华山版 |
2019.06.19 |
|
附 2:专有名词解释
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. |
IDE |
(Integrated Development Environment): 用于提供程序开发环境的应用程序,一般包括 |
|
代码编辑器、编译器、调试器和图形用户界面等工具,本《手册》泛指 IntelliJ IDEA 和 |
|||
eclipse。
8. |
OOM |
(Out Of Memory): 源于 java.lang.OutOfMemoryError,当 JVM 没有足够的内存来 |
为对象分配空间并且垃圾回收器也无法回收空间时,系统出现的严重状况。 |
Java |
开发手册 |
|