以后需要注意的一些Java开发规范

港控/mmm° 2022-06-15 09:09 188阅读 0赞

这两天把《阿里巴巴java开发手册》看了一遍，整个手册页数并不多，里面的内容都挺好，下面这些是选的自己以前没有注意的或者感觉很有用的点。

--------------------

### 编程规范 ###

#### 命名风格 ####

10.【强制】杜绝完全不规范的缩写，避免望文不知义。  
反例： AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类 随意缩写严重降低了代码的可阅读性。  
12.【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁 性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是 与接口方法相关，并且是整个应用的基础常量。  
正例：接口方法签名：void f(); 接口基础常量表示：String COMPANY = “alibaba”;  
反例：接口方法定义：public abstract void f();  
说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默 认实现。  
15. 【参考】各层命名规约：  
A) Service/DAO 层方法命名规约  
1） 获取单个对象的方法用 get 做前缀。  
2） 获取多个对象的方法用 list 做前缀。  
3） 获取统计值的方法用 count 做前缀。  
4） 插入的方法用 save（推荐）或 insert 做前缀。  
5） 删除的方法用 remove（推荐）或 delete 做前缀。  
6） 修改的方法用 update 做前缀

#### 命名风格 ####

1.【强制】不允许任何魔法值（即未经定义的常量）直接出现在代码中。  
反例：  
String key = “Id\#taobao\_” + tradeId;  
cache.put(key, value);  
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 定义。

#### OOP规范 ####

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 方法进行判断。  
8.关于基本数据类型与包装数据类型的使用标准如下：  
1） 【强制】所有的 POJO 类属性必须使用包装数据类型。  
2） 【强制】RPC 方法的返回值和参数必须使用包装数据类型。  
3） 【推荐】所有的局部变量使用基本数据类型。  
说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或者入库检查，都由使用者来保证。  
正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。  
反例：比如显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用 不成功时，返回的是默认值，页面显示：0%，这是不合理的，应该显示成中划线-。所以包装 数据类型的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。  
11.【强制】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中  
12.【强制】POJO 类必须写 toString 方法。使用 IDE 的中工具：source> generate toString 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。 说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排 查问题。  
15.【推荐】 类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter 方法。 说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类 关心，也可能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个 黑盒实现；因为方法信息价值较低，所有 Service 和 DAO 的 getter/setter 方法放在类体最 后。  
16.【推荐】setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在 getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度。

#### 集合处理 ####

1.【强制】关于 hashCode 和 equals 的处理，遵循如下规则： 1） 只要重写 equals，就必须重写 hashCode。 2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的 对象必须重写这两个方法。 3） 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals。 说明：String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象 作为 key 来使用。  
7.【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。  
正例：

Iterator<String> it = a.iterator();  
    while (it.hasNext()) {              
        String temp = it.next();                       
        if (删除元素的条件) {                               
            it.remove();                 
        }      
    }

反例：

List<String> a = new ArrayList<String>();       
    a.add("1");       
    a.add("2");       
    for (String temp : a) {           
        if ("1".equals(temp)) {               
            a.remove(temp);           
        }       
    }

说明：以上代码的执行结果肯定会出乎大家的意料，那么试一下把“1”换成“2”，会是同样的 结果吗？  
9.【推荐】集合初始化时，指定集合初始值大小。  
说明：HashMap 使用 HashMap(int initialCapacity) 初始化， 正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即loader factor）默认为 0.75，如果暂时无法确定初始值大小，请设置为 16。 反例：HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素不断增加，容 量 7 次被迫扩大，resize 需要重建 hash 表，严重影响性能。  
10.【推荐】使用 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 值组合集合。

#### 并发处理（其实这里面的现在都不太明白） ####

5.【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为 static，必须加锁，或者使用 DateUtils 工具类。 正例：注意线程安全，使用 DateUtils。  
亦推荐如下处理：

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

说明：如果是 JDK8 的应用，可以使用 Instant 代替 Date，LocalDateTime 代替 Calendar， DateTimeFormatter代替Simpledateformatter，官方给出的解释：simple beautiful strong immutable thread-safe。  
9.【强制】多线程并行处理定时任务时，Timer 运行多个 TimeTask 时，只要其中之一没有捕获 抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。  
14.【参考】 HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在 开发过程中可以使用其它数据结构或加锁来规避此风险。

#### 控制语句 ####

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

#### 注释规约 ####

8.【参考】合理处理注释掉的代码。在上方详细说明，而不是简单的注释掉。如果无用，则删除。 说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没 有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。  
9.【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含 义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同  
天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看 的，使其能够快速接替自己的工作。  
11.【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描， 经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。 1） 待办事宜（TODO）:（ 标记人，标记时间，\[预计处理时间\]） 表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。  
2） 错误，不能工作（FIXME）:（标记人，标记时间，\[预计处理时间\]） 在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

#### 其它 ####

2.【强制】velocity 调用 POJO 类的属性时，建议直接使用属性名取值即可，模板引擎会自动按 规范调用 POJO 的 getXxx()，如果是 boolean 基本数据类型变量（boolean 命名不需要加 is 前缀），会自动调用 isXxx()方法。 说明：注意如果是 Boolean 包装类对象，优先调用 getXxx()的方法。  
3.【强制】后台输送给页面的变量必须加!var——中间的感叹号。说明：如果var=null或者不存在，那么\{var\}会直接显示在页面上。  
5.【强制】获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime(); 说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime()的方式。在 JDK8 中， 针对统计时间等场景，推荐使用 Instant 类。

### 异常日志 ###

#### 异常处理 ####

9.【推荐】方法的返回值可以为 null，不强制返回空集合，或者空对象等，必须添加注释充分 说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题。 说明：本手册明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用  
者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回 null 的情况。  
10.【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景： 1）返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE。 反例：public int f() \{ return Integer 对象\}， 如果为 null，自动解箱抛 NPE。  
2） 数据库的查询结果可能为 null。 3） 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。 4） 远程调用返回对象时，一律要求进行空指针判断，防止 NPE。 5） 对于 Session 中获取的数据，建议 NPE 检查，避免空指针。 6） 级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。 正例：使用 JDK8 的 Optional 类来防止 NPE 问题。  
12.【参考】在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须 使用“错误码”；而应用内部推荐异常抛出；跨应用间 RPC 调用优先考虑使用 Result 方式，封 装 isSuccess()方法、“错误码”、“错误简短信息”。 说明：关于 RPC 方法返回方式使用 Result 方式的理由： 1）使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。 2）如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message，对于调用 端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输 的性能损耗也是问题。

#### 日志约束 ####

3.【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式： appName\_logType\_logName.log。logType:日志类型，推荐分类有 stats/desc/monitor/visit 等；logName:日志描述。这种命名的好处：通过文件名就可知 道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。  
正例：mppserver 应用中单独监控时区转换异常，如： mppserver\_monitor\_timeZoneConvert.log 说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于 通过日志对系统进行及时监控。  
4.【强制】对 trace/debug/info 级别的日志输出，必须使用条件输出形式或者使用占位符的方 式。 说明：logger.debug(“Processing trade with id: ” + id + ” symbol: ” + symbol); 如果日志级别是 warn，上述日志不会打印，但是会执行字符串拼接操作，如果 symbol 是对象， 会执行 toString()方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。 正例：（条件） if (logger.isDebugEnabled()) \{ logger.debug(“Processing trade with id: ” + id + ” symbol: ” + symbol); \} 正例：（占位符） logger.debug(“Processing trade with id: \{\} symbol : \{\} “, id, symbol);  
5.【强制】避免重复打印日志，浪费磁盘空间，务必在 log4j.xml 中设置 additivity=false。  
正例：  
6.【强制】异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过 关键字 throws 往上抛出。 正例：logger.error(各类参数或者对象 toString + “\_” + e.getMessage(), e);  
7.【推荐】谨慎地记录日志。生产环境禁止输出 debug 日志；有选择地输出 info 日志；如果使 用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘 撑爆，并记得及时删除这些观察日志。 说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。记录日志时请 思考：这些日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？

### MySQL数据库 ###

#### 建表规则 ####

1.【强制】表达是与否概念的字段，必须使用 is\_xxx 的方式命名，数据类型是 unsigned tinyint （ 1 表示是，0 表示否）。 说明：任何字段如果为非负数，必须是 unsigned。 正例：表达逻辑删除的字段名 is\_deleted，1 表示删除，0 表示未删除  
3.【强制】表名不使用复数名词。 说明：表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数 形式，符合表达习惯。  
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 万行或者单表容量超过 2GB，才推荐进行分库分表。 说明：如果预计三年后的数据量根本达不到这个级别，请不要在创建表时就分库分表。

#### 索引约束 ####

1.【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。 说明：不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速度是明  
显的；另外，即使在应用层做了非常完善的校验控制，只要没有唯一索引，根据墨菲定律，必 然有脏数据产生。  
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 放在索引的最前列。  
11.【参考】创建索引时避免有如下极端误解： 1）宁滥勿缺。误认为一个查询就需要建一个索引。 2）宁缺勿滥。误认为索引会消耗空间、严重拖慢更新和新增速度。 3）抵制惟一索引。误认为业务的惟一性一律需要在应用层通过“先查后插”方式解决。

#### 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;  
7.【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。  
9.【推荐】in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控 制在 1000 个之内。

#### ORM映射 ####

1.【强制】在表查询中，一律不要使用 \* 作为查询的字段列表，需要哪些字段必须明确写明。 说明：1）增加查询分析器解析成本。2）增减字段容易与 resultMap 配置不一致。  
2.【强制】POJO 类的布尔属性不能加 is，而数据库字段必须加 is\_，要求在 resultMap 中进行 字段与属性之间的映射。 说明：参见定义 POJO 类以及数据库字段定义规定，在中增加映射，是必须的。 在 MyBatis Generator 生成的代码中，需要进行对应的修改。  
3.【强制】不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需 要定义；反过来，每一个表也必然有一个与之对应。 说明：配置映射关系，使字段与 DO 类解耦，方便维护。  
10.【参考】中的 compareValue 是与属性值对比的常量，一般是数字，表示相等时带 上此条件；表示不为空且不为 null 时执行；表示不为 null 值时 执行。