命名规约
- 包名统一使用小写单数形式,点分隔符之间有且仅有一个自然语义的英语单词。类名可以使用复数形式
应用工具类包名为 com.alibaba.ei.kunlun.aap.util、类名为 MessageUtils - 类名使用UpperCamelCase风格,但以下情形例外:DO / BO / DTO / VO / AO / PO / UID等
正例:ForceCode / UserDO / HtmlDTO / XmlService / TcpUdpDeal / TaPromotion
反例:forcecode / UserDo / HTMLDto / XMLService / TCPUDPDeal / TAPromotion - 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格
正例: localValue / getHttpMessage() / inputUserId - 常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长
正例:MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
反例:MAX_COUNT / EXPIRED_TIME - 抽象类命名使用 Abstract 或 Base 开头
- 异常类命名使用 Exception 结尾
- 测试类命名以它要测试的类的名称开始,以Test结尾
- POJO类中的任何布尔类型的变量,都不要加is前,否则部分框架解析会引起序列化错误
- 避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名,使可读性降低。
说明:子类、父类成员变量名相同,即使是 public 类型的变量也是能够通过编译,而局部变量在同一方法内的不同代码块中同名也 是合法的,但是要避免使用对于非 setter/getter 的参数名称也要避免与成员变量名称相同反例: public class ConfusingName { public int stock; // 非setter/getter 的参数名称,不允许与本类成员变量同名 public void get(String alibaba) { if (condition) { final int money = 666; // ... } for (int i = 0; i < 10; i++) { // 在同一方法体,不允许与其它代码块中的money命名相同 final int money = 15978; // ... } } } class Son extends ConfusingName { // 不允许与父类的成员变量名称相同 public int stock; }
- 在常量与变量的命名时,表示类型的名词放在词尾,以提升辨识度
正例:startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
反例:startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD - 如果模块、接口、类、方法使用了设计模式,在命名时需体现出具体模式。说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计理念
正例: public class OrderFactory; public class LoginProxy; public class ResourceObserver; - 接口类中的方法和属性不要加任何修饰符号(public 也不要加),保持代码的简洁性,。尽量不要在接口里定义变量,如果一定要定义变量,确定与接口方法相关,并且是整个应用的基础常量
正例:接口方法签名 void commit(); 接口基础常量 String COMPANY = "alibaba";
反例:接口方法定义 public abstract void f();
说明:JDK8 中接口允许有默认实现,那么这个 default 方法,是对所有实现类都有价值的默认实现 - 接口和实现类的命名有两套规则:
1.对于 Service 和 DAO 类,基于 SOA 的理念,暴露服务是接口,内部的实现类用 Impl 的后与接口区别
正例:CacheServiceImpl 实现 CacheService 接口
2.如果是形容能力的接口名称,取对应的形容词为接口名(通常是 –able 的形容词)
正例:AbstractTranslator 实现 Translatable 接口 - 枚举类名带上Enum后,枚举成员名称需要全大写,单词间用下划线隔开。枚举其实就是特殊的常量类,且构造方法被默认强制是私有
正例:枚举名字为 ProcessStatusEnum 的成员名称:SUCCESS / UNKNOWN_REASON - 各层命名规约:
- Service/DAO 层方法命名规约
获取单个对象的方法用 get 做前
获取多个对象的方法用 list 做前,复数结尾,如:listObjects
获取统计值的方法用 count 做前
插入的方法用 save/insert 做前
删除的方法用 remove/delete 做前
修改的方法用 update 做前 - 领域模型命名规约
数据对象:xxxDO,xxx 即为数据表名
数据传输对象:xxxDTO,xxx为业务领域相关的名称
展示对象:xxxVO,xxx一般为网页名称
POJO是 DO/DTO/BO/VO 的统称,禁止命名成 xxxPOJO
- Service/DAO 层方法命名规约
常量定义
-
不允许任何魔法值(即未经预先定义的常量)直接出现在代码中
-
在 long 或者 Long 赋值时, 数值后使用大写的 L,不能是小写的 l,小写容易跟数字混淆,造成误解
说明:Long a = 2l; 写的是数字的 21,还是 Long 型的 2 -
不要使用一个常量类维护所有常量,要按常量功能进行归类,分开维护
说明:大而全的常量类,杂乱无章,使用查找功能才能定位到修改的常量,不利于理解,也不利于维护
正例:缓存相关常量放在类 CacheConsts 下;系统配置相关常量放在类 ConfigConsts 下 -
常量复用有五层:跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量
跨应用共享常量:放置在二方库中,通常是 client.jar 中的 constant 目录下
应用内共享常量:放置在一方库中,通常是子模块中的 constant 目录下
反例:易懂变量也要统一定义成应用内共享常量,两位工程师在两个类中分别定义了“YES” 的变量:
类 A 中: public static final String YES = "yes";
类 B 中: public static final String YES = "y";
A.YES.equals(B.YES),预期是 true,但实际返回为 false,导致线上问题
子工程内部共享常量:即在当前子工程的 constant 目录下
包内共享常量:即在当前包下单独的 constant 目录下
类内共享常量:直接在类内部 private static final 定义 -
如果变量值仅在一个固定范围内变化用 enum 类型来定义
如果存在名称之外的延伸属性应使用 enum 类型,下面正例中的数字就是延伸信息,表示一年中的第几季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 空格) {...} -
if / for / while / switch / do 等保留字与括号之间都必须加空格
-
任何二目、三目运算符的左右两边都需要加一个空格
说明:包括赋值运算符=、逻辑运算符&&、加减乘 除符号等 -
注释的双斜线与注释内容之间有且仅有一个空格
正例:// 这是示例注释,请注意在双斜线之后有一个空格 String commentString = new String(); -
单行字符数限制不超过 120 个,超出需要换行,换行时遵循如下原则:
1.第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进
2.运算符与下文一起换行
3.方法调用的点符号与下文一起换行
4.方法调用中的多个参数需要换行时,在逗号后进行
5.在括号前不要换行,见反例正例:StringBuilder sb = new StringBuilder(); // 超过120个字符的情况下,换行缩进4个空格,并且方法前的点号一起换行 sb.append("zi").append("xin")... .append("huang")... .append("huang")... .append("huang"); 反例:StringBuilder sb = new StringBuilder(); // 超过 120 个字符的情况下,不要在括号前换行 sb.append("you").append("are")...append("lucky"); // 参数很多的方法调用可能超过 120 个字符,逗号后才是换行处 method(args1, args2, args3, ... , argsX);
-
在进行类型强制转换时,右括号与强制转换值之间不需要任何空格隔开
正例:long first = 1000000000000L; int second = (int)first + 2; -
方法参数在定义和传入时,多个参数逗号后边必须加空格
正例: method(args1, args2, args3); -
没有必要增加若干空格来使变量的赋值等号与上一行对应位置的等号对齐
-
不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性
OOP规约
- 避免通过一个类的对象引用访问此类的静态变量或静态方法,无谓增加编译器解析成本,直接类名访问
- 所有的覆写方法,必须加 @Override 注解
说明:getObject() 与 get0bject()的问题。一个是字母的 O,一个是数字的 0,加@Override 可以准确判断是否覆盖成功。另外,如果在抽象类中对方法签名进行修改,其实现类会马上编译报错 - 相同参数类型,相同业务含义,才可以使用 Java 的可变参数,避免使用 Object
说明:可变参数必须放置在参数列表的后。(提倡尽量不用可变参数编程)
正例:public ListlistUsers(String type, Long... ids) {...} - 外部正在调用或者二方库依赖的接口,不允许修改方法签名,避免对接口调用方产生影响。
接口过时必须加@Deprecated 注解,并清晰地说明采用的新接口或者新服务是什么 - 不能使用过时的类或方法
- Object 的 equals 方法容易抛空指针异常,应使用常量或确定有值的对象来调用 equals
正例: "test".equals(object);
反例: object.equals("test"); - 所有整型包装类对象之间值的比较,全部使用 equals 方法比较
对于 Integer var = ? 在 -128 至 127 之间的赋值,Integer 对象是在 IntegerCache.cache 产生,会复用已有对象,这个区间内的 Integer 值可以直接使用 == 进行判断,但是这个区间之外的所有数据,都会在堆上产 生,并不会复用已有对象,这是一个大坑,推荐使用 equals 方法进行判断 - 任何货币金额,均以小货币单位且整型类型来进行存储
- 浮点数之间的等值判断,基本数据类型不能用 == 来比较,包装数据类型不能用 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 } 正例: (1) 指定一个误差范围,两个浮点数的差值在此范围之内,则认为是相等的。 float a = 1.0f - 0.9f; float b = 0.9f - 0.8f; float diff = 1e-6f; if (Math.abs(a - b) < diff) { System.out.println("true"); } (2) 使用 BigDecimal 来定义值,再进行浮点数的运算操作 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"); }
- 定义数据对象 DO 类时,属性类型要与数据库字段类型相匹配
正例:数据库字段的 bigint 必须与类属性的 Long 类型相对应
反例:某个案例的数据库表 id 字段定义类型 bigint unsigned,实际类对象属性为 Integer,随 着 id 越 来越大,超过 Integer 的表示范围而溢出成为负数 11.禁止使用构造方法 BigDecimal(double)的方式把 double 值转化为 BigDecimal 对象
说明:BigDecimal(double)存在精度损失风险,在精确计算或值比较的场景中可能会导致业务逻辑异常,如: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); - 定义 DO/DTO/VO 等 POJO 类时,不要设定任何属性默认值
反例:POJO 类的 createTime 默认值为 new Date(),但是这个属性在数据提取时并没有置入具体值,在更新其它字段时又附带更新了此字段,导致创建时间被修改成当前时间 - 序列化类新增属性时,请不要修改 serialVersionUID 字段,避免反序列失败;
如果完全不兼容升级,避免反序列化混乱,那么请修改 serialVersionUID 值
说明: 注意 serialVersionUID 不一致会抛出序列化运行时异常 - 构造方法里面禁止加入任何业务逻辑,如果有初始化逻辑,请放在 init 方法中
- POJO 类必须写 toString 方法。使用IDE中的工具:source->generate->toString 时,若继承 另一 POJO类,在前面加一下 super.toString。说明:在方法执行抛出异常时,可以直接调用 POJO 的 toString()方法打印其 属性值,便于排查问题
- 禁止在 POJO 类中,同时存在对应属性 xxx 的 isXxx()和 getXxx()方法。
说明:框架在调用属性 xxx 的提取方法时,并不能确定哪个方法一定是被优先调用到,神坑之一 - 使用索引访问用 String 的 split()得到的数组时,需对后一个分隔符后有无内容的检查,否则抛 IndexOutOfBoundsException
String str = "a,b,c,,";
String[] ary = str.split(","); // 预期大于 3,结果是 3
System.out.println(ary.length); - 当一个类有多个构造方法,或者多个同名方法,这些方法应该按顺序放置在一起,便于阅读
- 循环体内,字符串的连接方式,使用 StringBuilder 的 append 方法进行扩展
说明:下例中,反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象,然后进 行 append 操作,后通过
日期时间
-
日期格式化时,传入 pattern 中表示年份统一使用小写的 y
正例:表示日期和时间的格式如下所示:new SimpleDateFormat("yyyy-MM-dd HH🇲🇲ss") -
在日期格式中分清楚大写和小写分别指代的意义
表示当天所在的年是yyyy
代表当天所在的周week in which year属于的年份是YYYY
表示月份是大写的 M
表示分钟则是小写的 m
24 小时制的是大写的 H
12 小时制的则是小写的 h -
获取当前毫秒数:System.currentTimeMillis(); 而不是 new Date().getTime()
-
不要在程序中写死一年为 365 天,避免在公历闰年时出现日期转换错误或程序逻辑错误
正例:// 获取今年的天数 int daysOfThisYear = LocalDate.now().lengthOfYear(); // 获取指定某年的天数 LocalDate.of(2011, 1, 1).lengthOfYear(); 反例:// 第一种情况:在闰年 366 天时,出现数组越界异常 int[] dayArray = new int[365]; // 第二种情况:一年有效期的会员制,今年 1 月 26 日注册,硬编码 365 返回的却是 1 月 25 日 Calendar calendar = Calendar.getInstance(); calendar.set(2020, 1, 26); calendar.add(Calendar.DATE, 365);
-
使用枚举值来指代月份。如果使用数字,注意 Date,Calendar 等日期相关类的月份 month 取值在 0-11
正例: Calendar.JANUARY, Calendar.FEBRUARY, Calendar.MARCH 等来指代相应月份来进行传参