一、整体概述
该规范参考 「Java开发手册(黄山版)」,本着向优秀者学习的态度,同时不给学习者增加负担。该文档精简了其中重要的部分,大多为【强制】 级别。
目的如下:
- 提高团队协作效率。
- 便于开发和后期优化维护。
- 方便新进成员上手。
- 输出高质量的代码。
二、规范内容
1、编程规约
1.命名风格
-
所有编程相关的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。
反例:_name / __name / $Object / name_ / name$ / Object$
-
所有编程相关的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。
说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式也要避免采用。 正例:ali / alibaba / taobao / kaikeba / aliyun / youku / hangzhou 等国际通用的名称,可视同英文。 反例:DaZhePromotion【打折】/ getPingfenByName()【评分】 / String fw【福娃】/ int 变量名 = 3
-
类名使用 UpperCamelCase 风格,以下情形例外:DO / PO / DTO / BO / VO / 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 结尾。
-
类型与中括号紧挨相连来定义数组。
正例:定义整形数组 int[] arrayDemo。 反例:在 main 参数中,使用 String args[] 来定义
-
POJO 类中的任何布尔类型的变量,都不要加 is 前缀,否则部分框架解析会引起序列化错误。
说明:本文 MySQL 规约中的建表约定第 1 条,表达是与否的变量采用 is_xxx 的命名方式,所以需要在<resultMap> 设置从 is_xxx 到 xxx 的映射关系。 反例:定义为布尔类型 Boolean isDeleted 的字段,它的 getter 方法也是 isDeleted(),部分框架在反向解析时,“误以为”对应的字段名称是 deleted,导致字段获取不到,得到意料之外的结果或抛出异常。
-
包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形 式,但是类名如果有复数含义,类名可以使用复数形式。
正例:应用工具类包名为 com.alibaba.ei.kunlun.aap.util;类名为 MessageUtils(此规则参考 spring 的框架结构)。
-
避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名,使可理 解性降低。
说明:子类、父类成员变量名相同,即使是 public 也是能够通过编译,而局部变量在同一方法内的不同代码块中同名 也是合法的,但是要避免使用。对于非 setter / getter 的参数名称也要避免与成员变量名称相同。 反例: public class ConfusingName { protected int stock; protected String alibaba; // 非 setter/getter 的参数名称,不允许与本类成员变量同名 public void access(String alibaba) { if (condition) { final int money = 666; // ... } for (int i = 0; i < 10; i++) { // 在同一方法体中,不允许与其它代码块中的 money 命名相同 final int money = 15978; // ... } } } class Son extends ConfusingName { // 不允许与父类的成员变量名称相同 private int stock; }
-
杜绝完全不规范的英文缩写,避免望文不知义。
反例:AbstractClass“缩写”成 AbsClass;condition“缩写”成 condi;Function“缩写”成 Fu,此类随意缩写严重降低了代码的可阅读性。
2.常量定义
-
不允许任何魔法值(即未经预先定义的常量)直接出现在代码中。
反例: // 开发者 A 定义了缓存的 key。 String key = "Id#taobao_" + tradeId; cache.put(key, value); // 开发者 B 使用缓存时直接复制少了下划线,即 key 是"Id#taobao" + tradeId,导致出现故障。 String key = "Id#taobao" + tradeId; cache.get(key);
-
long 或 Long 赋值时,数值后使用大写 L,不能是小写 l,小写容易跟数字混淆,造成误解。
说明:public static final Long NUM = 2l; 写的是数字的 21,还是 Long 型的 2?
-
浮点数类型的数值后缀统一为大写的 D 或 F。
正例:public static final double HEIGHT = 175.5D; public static final float WEIGHT = 150.3F;
-
不要使用一个常量类维护所有常量,要按常量功能进行归类,分开维护。
说明:大而全的常量类,杂乱无章,使用查找功能才能定位到要修改的常量,不利于理解,也不利于维护。 正例:缓存相关常量放在类 CacheConsts 下;系统配置相关常量放在类 SystemConfigConsts 下。
-
如果变量值仅在一个固定范围内变化用 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; } }
3.OOP规约
-
避免通过一个类的对象引用访问此类的静态变量或静态方法,无谓增加编译器解析成本,直接用 类名来访问即可。
-
所有的覆写方法,必须加 @Override 注解。
说明:getObject() 与 get0bject() 的问题。一个是字母的 O,一个是数字的 0,加 @Override 可以准确判断是否覆盖 成功。另外,如果在抽象类中对方法签名进行修改,其实现类会马上编译报错。
-
相同参数类型,相同业务含义,才可以使用的可变参数,参数类型避免定义为 Object。
说明:可变参数必须放置在参数列表的最后。(建议开发者尽量不用可变参数编程) 正例:public List<User> listUsers(String type, Long... ids) {...}
-
外部正在调用的接口或者二方库依赖的接口,不允许修改方法签名,避免对接口调用方产生影 响。接口过时必须加 @Deprecated 注解,并清晰地说明采用的新接口或者新服务是什么。
-
不能使用过时的类或方法。
说明:java.net.URLDecoder 中的方法 decode(String encodeStr) 这个方法已经过时,应该使用双参数 decode(String source, String encode)。接口提供方既然明确是过时接口,那么有义务同时提供新的接口;作为调用 方来说,有义务去考证过时方法的新实现是什么。
-
Object 的 equals 方法容易抛空指针异常,应使用常量或确定有值的对象来调用 equals。
正例:"test".equals(param); 反例:param.equals("test"); 说明:推荐使用 JDK7 引入的工具类 java.util.Objects#equals(Object a, Object b)
-
所有整型包装类对象之间值的比较,全部使用 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.compareTo(y) == 0) { System.out.println("true"); }
-
BigDecimal 的等值比较应使用 compareTo() 方法,而不是 equals() 方法。
说明:equals() 方法会比较值和精度(1.0 与 1.00 返回结果为 false),而 compareTo() 则会忽略精度。
-
定义数据对象 DO 类时,属性类型要与数据库字段类型相匹配。
正例:数据库字段的 bigint 必须与类属性的 Long 类型相对应。 反例:某业务的数据库表 id 字段定义类型为 bigint unsigned,实际类对象属性为 Integer,随着 id 越来越大, 超过 Integer 的表示范围而溢出成为负数,此时数据库 id 不支持存入负数抛出异常产生线上故障。
-
禁止使用构造方法 BigDecimal(double) 的方式把 double 值转化为 BigDecimal 对象。
说明:BigDecimal(double) 存在精度损失风险,在精确计算或值比较的场景中可能会导致业务逻辑异常。如: BigDecimal g = new BigDecimal(0.1F);实际的存储值为:0.100000001490116119384765625 正例:优先推荐入参为 String 的构造方法,或使用 BigDecimal 的 valueOf 方法,此方法内部其实执行了 Double 的toString,而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。 BigDecimal recommend1 = new BigDecimal("0.1"); BigDecimal recommend2 = BigDecimal.valueOf(0.1);
-
关于基本数据类型与包装数据类型的使用标准如下:
1)【强制】所有的 POJO 类属性必须使用包装数据类型。 2)【强制】RPC 方法的返回值和参数必须使用包装数据类型。 3)【推荐】所有的局部变量使用基本数据类型。 说明:POJO 类属性没有初值是提醒使用者在需要使用时,必须自己显式地进行赋值,任何 NPE 问题,或者入库检查,都由使用者来保证。 正例:数据库的查询结果可能是 null,因为自动拆箱,用基本数据类型接收有 NPE 风险。 反例:某业务的交易报表上显示成交总额涨跌情况,即正负 x%,x 为基本数据类型,调用的 RPC 服务,调用不成功时,返回的是默认值,页面显示为 0%,这是不合理的,应该显示成中划线-。所以包装数据类型的 null 值,能够表示额外的信息,如:远程调用失败,异常退出。
-
定义 DO / PO / DTO / VO 等 POJO 类时,不要设定任何属性默认值。
反例:某业务的 DO 的 createTime 默认值为 new Date();但是这个属性在数据提取时并没有置入具体值,在更新其它字段时又附带更新了此字段,导致创建时间被修改成当前时间。
-
序列化类新增属性时,请不要修改 serialVersionUID 字段,避免反序列失败;如果完全不兼 容升级,避免反序列化混乱,那么请修改 serialVersionUID 值。
说明:注意 serialVersionUID 不一致会抛出序列化运行时异常。
-
构造方法里面禁止加入任何业务逻辑,如果有初始化逻辑,请放在 init 方法中。
-
禁止在 POJO 类中,同时存在对应属性 xxx 的 isXxx() 和 getXxx() 方法。
说明:框架在调用属性 xxx 的提取方法时,并不能确定哪个方法一定是被优先调用到,神坑之一。
4.日期时间
-
日期格式化时,传入 pattern 中表示年份统一使用小写的 y。
说明:日期格式化时,yyyy 表示当天所在的年,而大写的 YYYY 代表是 week in which year(JDK7 之后引入的概念), 意思是当天所在的周属于的年份,一周从周日开始,周六结束,只要本周跨年,返回的 YYYY 就是下一年。 正例:表示日期和时间的格式如下所示: new SimpleDateFormat("yyyy-MM-dd HH:mm:ss") 反例:某程序员因使用 YYYY/MM/dd 进行日期格式化,2017/12/31 执行结果为 2018/12/31,造成线上故障。
-
获取当前毫秒数:System.currentTimeMillis();而不是 new Date().getTime()。
说明:获取纳秒级时间,则使用 System.nanoTime 的方式。在 JDK8 中,针对统计时间等场景,推荐使用 Instant 类。
-
不允许在程序任何地方中使用:1)java.sql.Date 2)java.sql.Time 3)java.sql.Timestamp。
说明:第 1 个不记录时间,getHours() 抛出异常;第 2 个不记录日期,getYear() 抛出异常;第 3 个在构造方法 super((time / 1000) * 1000),在 Timestamp 属性 fastTime 和 nanos 分别存储秒和纳秒信息。 反例:java.util.Date.after(Date) 进行时间比较时,当入参是 java.sql.Timestamp 时,会触发 JDK BUG(JDK9 已修复),可能导致比较时的意外结果。
-
禁止在程序中写死一年为 365 天,避免在公历闰年时出现日期转换错误或程序逻辑错误。
正例: // 获取今年的天数 int daysOfThisYear = LocalDate.now().lengthOfYear(); // 获取指定某年的天数 LocalDate.of(2011, 1, 1).lengthOfYear(); 反例: // 第一种情况:在闰年 366 天时,出现数组越界异常 int[] dayArray = new int[365]; // 第二种情况:一年有效期的会员制,2020 年 1 月 26 日注册,硬编码 365 返回的却是 2021 年 1 月 25 日 Calendar calendar = Calendar.getInstance(); calendar.set(2020, 1, 26); calendar.add(Calendar.DATE, 365);
-
使用枚举值来指代月份。如果使用数字,注意 Date,Calendar 等日期相关类的月份 month 取 值范围从 0 到 11 之间。
说明:参考 JDK 原生注释,Month value is 0-based. e.g., 0 for January. 正例:Calendar.JANUARY,Calendar.FEBRUARY,Calendar.MARCH 等来指代相应月份来进行传参或比较。
5.控制语句
-
在一个 switch 块内,每个 case 要么通过 continue / break / return 等来终止,要么注释说明 程序将继续执行到哪一个 case 为止;在一个 switch 块内,都必须包含一个 default 语句并且放在最 后,即使它什么代码也没有。当 switch 括号内的变量类型为 String 并且此变量为外部参数时,必须先进行 null 判断。
说明:注意 break 是退出 switch 语句块,而 return 是退出方法体。
-
在 if / else / for / while / do 语句中必须使用大括号。即使只有一行代码,也要采用大括号的编码方式。
6.注释规约
-
类、类属性、类方法的注释必须使用 Javadoc 规范,使用 /** 内容 */ 格式,不得使用 // xxx 方式。
说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。
-
所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数异常说明 外,还必须指出该方法做什么事情,实现什么功能。
说明:对子类的实现要求,或者调用注意事项,请一并说明。
-
方法内部单行注释,在被注释语句上方另起一行,使用 // 注释。方法内部多行注释使用 /* */ 注释,注意与代码对齐。
-
所有的枚举类型字段必须要有注释,说明每个数据项的用途。
-
好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的另一个极 端:过多过滥的注释,代码的逻辑一旦修改,修改注释又是相当大的负担。
2、SQL开发规范
-
禁止使用 SELECT * / COUNT(*) 等语句;
反例: SELECT * FROM table_name; SELECT COUNT(*) FROM table_name; 正例: SELECT id, name, xxx FROM table_name; SELECT COUNT(1) FROM table_name;
-
使用 ISNULL 判断是否为 NULL值;
-- 语法:ISNULL(check_expression , replacement_value) SELECT AVG(ISNULL(weight, 0)) FROM table_goods;
-
不得使用外键与级联,一切外键概念必须在应用层解决。
-
禁止使用存储过程,存储过程难以调试和扩展,更没一致性。
-
数据库中涉及多表查询,需要在列名前加表别名进行限定。
-
尽量避免使用视图(有些规范禁止使用)。
-
SQL中IN的元素个数在500以下(有的建议1000以下,主要看数据库版本),若超过需拆分多个SQL语句。效率不高尽量不使用。
-- 原逻辑: list 元素数量 1000 以内
SELECT id, name, xxx FROM table_name WHERE id IN('1','2','xxx');
-- 拆分逻辑:定义 ${ids}, 程序中 将 list 进行拆分为 SQL 语句(注意拼接防SQL注入), ids = '(id IN(1,2,xxx) OR id IN(yyy,zzz,xxx))', 应用系统可提供统一的拆分逻辑支持
SELECT id, name, xxx FROM table_name WHERE 1 = 1 AND ${ids}
-- 建议使用场景
SELECT id, name, xxx FROM table_name WHERE id IN(SELECT pk_id FROM other_table WHERE filed = 'query value');
数据库 | 限制 | 备注 |
Oracle | 1000 个 | Oracle 10g + |
256 个 | Oracle 9i | |
MySQL | 4MB | 5.7 |
64MB | 8.0 | |
Sql Server | 5W 个 |
-
禁止使用 NOT IN 语句,需改为 NOT EXISTS 语句。
-- NOT IN 案例 SELECT a.id, a.name FROM table_name a WHERE a.id NOT IN(SELECT pk_id FROM other_table b); -- NOT EXISTS 性能更好 SELECT a.id, a.name FROM table_name a WHERE NOT EXISTS (SELECT pk_id FROM other_table b WHERE a.id = b.pk_id)
-
禁止使用 UNION,如业务需要,需拆分两个查询。
-
禁止在一条SQL语句中使用 3 层以上的嵌套查询,如果有,建议使用临时表或中间结果集。
-
字符串连接必须用 ”||“ 符号,不使用 ”+“。(DB2和SqlServer数据库差异)。
-
在CASE WHEN 语句中只能出现 =、>=、<= 以及 IS NULL 运算符,不能出现 <、>、<>、!= 以及 IS NOT NULL 运算符。(ORACLE数据库差异)。
-
只可使用标准SQL 函数,不可使用数据库特性的函数(如需使用,需告知项目负责人)。
3、Java开发规范(补充编程规约)
- 注释!注释!注释!所有注释要符合javadoc标准,同时一些业务复杂逻辑在接口上必须说明实现逻辑,方便接手者熟悉业务。同时修改逻辑前需先修改完善实现逻辑说明!!!
- 超大数据/浮点数据 传递前端时,必须转为String类型,避免 JS 数值溢出 或 浮点不准。
- 所有POJO类属性和RPC方法返回值和参数必须使用包装数据类型。POJO类必须重写toString()方法,日志输出POJO类时禁止使用JSON序列化方法转换。
- 线程资源必须通过线程池提供,不允许在应用中自行显式创建线程,线程池不允许使用Executors去创建,而是通过ThreadPoolExecutor的方式,规避资源耗尽的风险。
- 高并发时,同步调用应该去考量锁的性能损耗。能用无锁数据结构,就不要用锁;能锁区块,就不要锁整个方法体;能用对象锁,就不要用类锁。
- 并发修改时,要加锁。
- 前后端数据列表相关接口返回,如果为空,则返回空数组或空集合,避免前端null判断。
- 异常处理:尽量往外抛(事务场景,如果需要回滚,需注意手动回滚事务),交给最外层业务使用者。其他特殊情况特殊处理。
- 单元测试:这个务必做。
- 安全规约:
- 各分层命名规约:
- Service / DAO 层方法命名规约
- 获取单个对象用get前缀。
- 获取多个对象用list做前缀。
- 获取统计值用count做前缀。
- 插入用 save / insert 做前缀。
- 删除用 remove / delete 做前缀。
- 修改用 update 做前缀。
- 领域模型命名规约
- 数据对象:xxxDO,xxx即为数据表名。
- 数据传输对象:xxxDTO, xxx 为业务领域相关名称。
- 展示对象:xxxVO,xxx ,xxxPO一般为网页名称。
- POJO是 DO/DTO/BO/VO的统称,禁止命名为 xxxPOJO。
- Service / DAO 层方法命名规约
分层建议
[阿里业务分层]
4、RestFul设计规范
典型用法如下(REST + RPC 混合):
方法 | 用法 | 规范 | 安全 | 幂等 |
---|---|---|---|---|
GET | 获取资源(简单查询) | /资源/[子资源n]/query*(或其他)?参数k=v | 是 | 是 |
/资源/[子资源n]?参数k=v | ||||
DELETE | 删除资源 | /资源/[子资源n]/delete*(或其他)?参数k=v | 否 | 是 |
/资源/[子资源n]?参数k=v | ||||
PUT | 更新资源(也可用于新增资源) | /资源/[子资源]/update*(或其他) | 否 | 是 |
/资源/[子资源] | ||||
POST | 新增资源(更新资源或复杂查询资源) | /资源/[子资源]/add*(或其他) | 否 | 否 |
(注POST:参数值用body传送) | /资源/[子资源] |
5、数据库表、字段命名规范
5.1 数据表命名规范
-
表命名采用26个英文字母,全部小写命名,多个单词用下划线 “_” 分隔,一般建议 3 个单词以内。
-
禁止使用数据库关键字命名(如: time、date time、name…),且表必须填写描述信息。
-
表名称均采用名称或动宾短语,名词需为单数形式。
-- 明细表名称: 主表名称 + 字符 dtl (detail 缩写) -- 例:采购订单表,名称为:po_order, 则采购订单明细表为:po_orderdtl
-
表命名建议:
[t_ / v_ /]
+ 模块名称 + 功能点名称,其中 “t_” 表示当前项目基础表,“v _” 表示当前项目视图(不建议使用,若使用需遵循规范)。-- 系统 用户信息表, t_ 表示本系统表(v_ 表示本系统视图),主要为了第三方库命名规范一致,如 Activiti 框架库以 act_开头, Quartz 框架以 quartz_ 开头; sys 表示 属于基础系统模块; userinfo 表示用户信息表。 SELECT id, user_name, password FROM t_sys_userinfo;
5.2 数据库字段命名规范
- 大致与表命名规范一致。
- 字段命名使用完整名称,禁止缩写,且必须填写描述信息。
- 所有字段在设计时,除以下数据类型timestamp、image、datetime、smalldatetime、uniqueidentifier、binary、sql_variant、binary 、varbinary外,必须有默认值(原则上不建议出现null值列)— 不强制。
- 系统中所有逻辑中数值 0 表示 ‘假’, 1 表示 ‘真’。(注意:有些银行系统比较妖,0 位真,1 为假)。
- 用合适的字段 类型和长度 节约存储空间,比如 手机号 可定义为 varchar(15) 可适当容错,校验逻辑在业务中处理。
t_ 表示本系统表(v_ 表示本系统视图),主要为了第三方库命名规范一致,如 Activiti 框架库以 act_开头, Quartz 框架以 quartz_ 开头; sys 表示 属于基础系统模块; userinfo 表示用户信息表。
SELECT id, user_name, password FROM t_sys_userinfo;
5.2 数据库字段命名规范
- 大致与表命名规范一致。
- 字段命名使用完整名称,禁止缩写,且必须填写描述信息。
- 所有字段在设计时,除以下数据类型timestamp、image、datetime、smalldatetime、uniqueidentifier、binary、sql_variant、binary 、varbinary外,必须有默认值(原则上不建议出现null值列)— 不强制。
- 系统中所有逻辑中数值 0 表示 ‘假’, 1 表示 ‘真’。(注意:有些银行系统比较妖,0 位真,1 为假)。
- 用合适的字段 类型和长度 节约存储空间,比如 手机号 可定义为 varchar(15) 可适当容错,校验逻辑在业务中处理。
- 尽量遵守第三范式标准(表中的所有数据元素不但要能唯一地被主关键字所标识,而且它们之间还必须相互独立,不存在其他的函数关系)。