JAVA 编码规范

版本记录

设计者
版本
日期
备注
无涯
V1.0.0
2022-04-19
初始版本
无涯
V1.0.1
2022-06-06
调整文件格式并完善部分章节

1.背景

1.1 愿景

编码是一门艺术,优雅编码,规范编码,愿大家早日成为艺术大师。

1.2 适用读者

  • 初中级程序员,参考编码的一些规范和建议。
  • 代码审批人员,审核代码时,一些参考的指标和方向。
  • 本文所举例的代码缺陷,改造参考方向,难免存在理解错误或偏差之处,欢迎批评指正。
  • 本文中所举案例,主要是用于记录作者在开发中遇到的一些不规范现象,一些编码技巧及调优方向,随着时间沉淀会持续总结和更新。

2. 非规范案例

Set 集合去重

项目
描述
描述
申明一个对象,如xxxDto,却未申明去重的参考标准。Set<xxxDto> xxxSet = new HashSet<>();
潜在风险
集合不会去重,或去重与业务需求不一样。
调整方案
xxxDto类,重写equal,hashCode方法。参考:Set去重问题
备注
暂无。

 避免采用反逻辑运算符

项目
描述
描述
代码中存在大量判空集合:if(!CollectionUtils.isEmpty(reqDto.getList())
潜在风险
反逻辑,容易造成理解偏差;
调整方案
推荐使用: org.apache.commons.collections.CollectionUtils.isEmpty()
org.apache.commons.collections.CollectionUtils.isNotEmpty()
备注
《java开发手册》-控制语句-11

集合函数为空返回null

项目
描述
描述
参考代码:获取list数据,为空时返回null
潜在风险
可能导致NullPointExcepetion
调整方案
推荐使用: return Collections.emptyList();
备注
明确单个对象,为空返回null;集合时不要返回null;

慎用BaseController

项目
描述
描述
每一个controller对外暴露接口时,可能存在异常等情况,或分页等通用的一些功能。编写BaseController,让其他Controller去继承。
潜在风险
BaseController功能需要业务Controller去继承,造成代码冗余且不便扩展。
调整方案
编写统一的WebMvc配置类,基于
@RestControllerAdvice(annotations = RestController.class)做异常兜底处理。
备注
基于BaseController的模式:非常外行。

java 8的LocalDate代替Date

项目
描述
描述
日期,时间,大量基于Date做日期处理
潜在风险
Date是存在多线程不安全性。
调整方案
建议使用LocalDate
扩展了解java 8的一些新特性,基于java 8编码。
备注
Java 18都出来了,先进入java 8吧,一定要快!!!

枚举类使用

项目
描述
描述
可列举的变量大量使用了静态字符串。如 4表示审批中,直接定义了静态变量值为4。
比较数据是否为某一种类型时,直接使用魔法值处理。如:getStatus()==4。
潜在风险
避免使用魔法值,避免使用静态字符串,变量混用容易造成业务混乱;
调整方案
全局统一的一些状态,变量等使用枚举值统一控制。针对状态值,建议使用枚举。
且枚举申明要满足规范,定义变量值时,定义为final。
备注
枚举扩展性高,便于做类型判断

代码注释规范

项目
描述
描述
注释,命名等大量非规范的情况。如:
函数命名不规范,错误的定义返回类型;
代码注释不完整,在接口的实现类上写注释;
潜在风险
错误或混乱的注释,造成代码可读性变差。
调整方案
idea安装
Alibaba Java Coding Guidelines 插件
安装阿里巴巴编码规范插件,可以自动识别不规范的编码。
备注
1.代码注释格式要统一
2.变量命名应遵循规范,统一定义规则,如驼峰。
3.混乱的编写注释,显得外行。

命名规范性

项目
描述
描述
外部系统,或部分业务对象,命名混乱。
如is_enable,a_b_ddd;
部分函数,接口,类等命令不具有可读性,命名不规范;
潜在风险
代码可读性差;
调整方案
建议统一使用驼峰命名方式。对接外部系统或特殊情况:
1.可在对应变量上编写@JsonProperty做自动转义;
2.若驼峰需要转换下划线,编写统一工具类实现
备注
命名请参考:《java开发手册》-命名风格-1

@ResponseBody使用混乱

项目
描述
描述
在Controller中,定义对外提供的api接口时,在方法上,在类上混乱使用@ResponseBody的情况
潜在风险
带偏新同事;
调整方案
参考@restController的作用,可不必写@ResponseBody
默认就是返回json对象。
备注
使用注解时,了解该注解的使用场景,不要滥用。

String字符串非空拦截

项目
描述
描述
String 字符串非空使用@NotNull
潜在风险
若是空字符串,拦截失效
调整方案
根据业务场景,建议使用@NotBlank
备注
暂无

验证完整性问题

项目
描述
描述
功能验证逻辑写在前端,后端提供的接口,未编写逻辑验证;
潜在风险
前端验证失效时,或直接调用接口时,造成业务异常。
调整方案
验证逻辑:
后端一定要编写严格的业务验证;
前端做第一层验证,后端要编写第二层验证,数据层做第三次验证;
备注
暂无

深拷贝问题

项目
描述
描述
使用序列化做深拷贝对象的处理。
将对象转换为json字符串,将字符串再转换为对象。
潜在风险
降低了函数的性能。
调整方案
1.避免在循环中,采用序列化做深拷贝。
2.设计功能时,部分逻辑是可以不用深拷贝实现的,应避免。
备注
字符串做深拷贝,性能不好。

数据库字段类型规范定义

项目
描述
描述
态类型字段避免使用varchar存储;
日期使用date,不做默认值设置等;
潜在风险
不合理的数据类型,在数据表后续优化时,如建立索引,会造成空间浪费,性能差等情况。
调整方案
1.类型字段:建议使用tinyint。避免浪费数据库资源。
2.建议非特殊业务字段,所有字段设置默认值,不允许为空。
备注
新建数据表时,考虑数据的可能情况,用合理的最小的空间,建立数据字段。
新建数据表时,考虑该表的业务使用场景,构建好唯一索引,普通索引。

数据表关键字作为字段名称

项目
描述
描述
xxx表中的state字段。
潜在风险
造成部分场景下,sql识别失败。
调整方案
避免使用数据库关键字。
备注
暂无。

布尔字段申明为isXXX

项目
描述
描述
isDetete字段,申明类型为Boolean;
潜在风险
不同序列化工具,产生序列结果不同。
调整方案
所有字段类型,避免这样的申明。
备注
《java开发手册》-编程规约-命名风格-8暂无。

数据物理删除

项目
描述
描述
数据物理删除,在数据库执行Delete的场景
潜在风险
物理删除,数据不能留痕。存在误删等巨大的风险。
调整方案
物理删除,数据不能留痕。存在误删等巨大的风险。
备注

字符串代表数组

项目
描述
描述
使用字段如a:
a 表示模板id,且表示多个,用逗号隔开;
用一个变量表示集合字段,如:String a="2,3,4";
潜在风险
不合理的数据类型,代码可读性差,不便于系统扩展和前后端接口对接。
调整方案
字段表示集合,数组含义时,不要定义为字符串。
建议使用数组,如 String[] reviewTemplateIds;
备注
明确参数类型,不要基于字符串做特殊的处理。不便于功能扩展。(如数组数量@size()限制)

正确使用事务

项目
描述
描述
事务使用的场景,格式不对,显得混乱;
潜在风险
编写大事务,系统性能差,占用了数据库资源。
调整方案
1.避免编写大事务,后续数据量大以后,系统性能不好。
2.单表操作,不使用事务。
3.注解使用@Transactional
propagation = Propagation.REQUIRED, isolation = Isolation.DEFAULT, 这个配置是系统默认的,可不编写。
4.注意事务传递性等
备注
注意事务的传递性,慎用。

正确创建线程池

项目
描述
描述
代码中,存在周期性任务脚本,线程池构建代码:Executors.newScheduledThreadPool(2);
潜在风险
创建不会限制最大线程数,会造成OOM风险。
调整方案
基于ScheduledThreadPoolExecutor,自定义线程池。
备注
建议修改,后期数据量大,会造成jvm频繁FullGc,影响性能或造成系统死掉。

正确使用异步

项目
描述
描述
异步使用,使用的Spring boot 默认的线程。
潜在风险
造成OOM风险。
调整方案
配置自定义线程池,代替默认的线程。参考:Async配置自定义线程池
备注
微服务若使用了@Async,必须配置异步线程池。

循环中操作外部资源

项目
描述
描述
直接在循环中,多次操作数据库的情况。如:
for(i=0;i<100;i++){
xxxMapper.select(i);
xxxMapper.update(i);
}
直接在循环中,单次调用远程接口;
潜在风险
严重拉低系统性能,拖死服务。
调整方案
1.建议将操作的最小模块,独立出来,判断是否可以异步单个处理最小模块。
2.单条数据查询,更新等考虑一次批量处理,获取数据到内存后,在处理。
备注
采用批量接口做逻辑处理,避免在循环中单条处理。

使用非序列化对象做参数

项目
描述
描述
使用非序列化出入参问题,如使用Map结构:Map<String,Object> data
潜在风险
非对象模式,容易引发null等不确定问题。不便于对象的扩展和维护。
调整方案
采用对象的模式。避免前后过程式处理。
备注
面向对象编程。

大函数问题

项目
描述
描述
部分函数代码太长,表示了多个含义,如500行的功能函数。
潜在风险
函数功能不唯一,函数逻辑复杂,行数多,不便于后期扩展和维护。
调整方案
建议一个函数至多50行代码。
1.小函数代表一个明确的功能。
2.多用设计方法达到函数复用,函数剥离的效果。
备注
先把函数写小,控制行数。

3.编码调优参考

数据对象设置安全对象

项目
描述
描述
远程调用其他系统后,业务代码存在重复的判空,验证等流程。如:
Response<xxxDto> sampleNumRes = xxxFeignClient.query(xxxxTemp);
if(sampleNumRes!=null && sampleNumRes.getData() != null && sampleNumRes.getData().getTotal_num()!=null){
}
缺陷
调用其他API接口,获取数据对象时,总会要做各种判空处理,代码严重冗余;
调整方案
编写:ResponseUtils工具类,并提供安全方法,非安全方法。改造如下:
xxxxDto= ResponseUtils.safe(xxxFeignClient.query(xxxTemp));
基于泛型,穷举判断返回是数组,列表,对象等是否为空。
安全性:接口返回成功,返回的对象最终data是一定存在值的。
非安全性:接口返回成功,返回的对象不一定存在值。
请求异常:调用接口失败,或对方返回非成功状态的信息。直接拦截报错。
备注
参数代码:
/**
* 返回内容解析工具类 参考Objects.requireNonNull(T, String)源码,便于把为空的数据,在一个地方抛出异常 方便在调用的地方,不再做 空(null,empty) 判断
*
* @author wangling
* @date 2022/5/25
*/
public class FeignResponseBodyUtil {
 
/**
* 获取安全的数据 接口返回的内容一定存在值
*
* @param responseBody 接口返回体
* @param exceptionMessage 可变参数,异常文本描述
* @param <T> 数据类型
* @return 一定存在值的数据
*/
public static <T> T getSaleData(FeignResponse<T> responseBody, String... exceptionMessage) {
String messageInfo = null;
if (exceptionMessage.length > 0) {
messageInfo = exceptionMessage[0];
}
checkDataSuccess(responseBody);
T object = responseBody.getData();
if (object == null
|| (object instanceof Collection && ((Collection<?>) object).isEmpty())
|| (object.getClass().isArray() && Array.getLength(object) < 1)
|| (object instanceof String && StringUtils.isBlank((String) object))) {
String dataType = object.getClass().getTypeName();
String exceptionMess = String.format("返回数据类型 %s 数据为空", dataType);
String message = Optional.ofNullable(messageInfo).orElse(exceptionMess);
throwException(message);
}
return responseBody.getData();
}
 
public static void throwException(String message) {
throw new BusinessException(String.format("data_null:%s", message));
}
 
/**
* 获取非安全数据
*
* @param responseBody 接口返回体
* @param <T> 数据类型
* @return 返回数据(数据可能为空)
*/
public static <T> T getUnsaleData(FeignResponse<T> responseBody) {
checkDataSuccess(responseBody);
return responseBody.getData();
}
 
/**
* 检查接口返回体是否为成功状态
*
* @param responseBody 接口返回体
* @param <T> 数据类型
*/
public static <T> void checkDataSuccess(FeignResponse<T> responseBody) {
if (Objects.isNull(responseBody)) {
throw new BusinessException("404:远程服务返回对象为空");
}
if (!Objects.equals(responseBody.getCode(), ResultCodeEnum.SUCCESS.getCode())) {
String failCode =
Objects.nonNull(responseBody.getCode()) ? String.valueOf(responseBody.getCode())
: "SERVICE_FALL_BACK";
String failMsg =
StringUtils.isNotEmpty(responseBody.getMessage()) ? responseBody.getMessage() : "远程服务不可用";
throw new BusinessException(failCode + "->" + failMsg);
}
}
}
View Code

判断对象是否为空

项目
描述
描述
eqDto.getStatus() != null等判空
缺陷
暂无
调整方案
建议使用: Objects.isNull(),Objects.nonNull()

判断对象是否相等

项目
描述
描述
xxx.DISEASE_POSITIVE == xxxDto.getDiseaseType()
缺陷
避免直接使用equal,==比较,对象为空时,报错。
调整方案
建议采用:Objects.equals()

集成测试用例代码

项目
描述
描述
系统中无测试用例代码;
存在部分单元测试,缺乏对controller提供接口的集成测试;
缺陷
测试用例未在代码中体现,不能留痕;
调整方案
为每一个controller编写对应的集成测试。
完整验证该接口是否正常。
备注
强制编写测试用例,便于提高开发人员的自测工作效率,并为后续开发人员,测试人员提供测试参考的示例。

巧用反射

项目
描述
描述
如一个对象中,对所有类型为Decimal的字段,统一加密翻译为另外一个字段;
代码遍历处理对象中的所有Decimal字段;
缺陷
功能重复,代码可重用度低,不便于扩展。
调整方案
针对不同对象,属性字段逻辑处理一致的功能,建议采用反射机制代替穷举模式。
基于反射的模式,批量处理一个对象,做逻辑处理。
备注
统一处理代替逐个处理,编码时,一定不要写死代码。

面向对象编程

项目
描述
描述
许多业务代码,基本是面向过程编码,缺乏对象的封装,抽样,导致代码冗余,过程繁杂。如:
基于if/else,switch等模式做过程是分支;
基于方法编程,未做接口封装;
缺陷
面向过程编码,后期代码缺乏剥离,冗余复杂,难以维护。
调整方案
建议看看《重构》,《代码整洁之道》,面向对象编码思维。
1.多用设计方法,如模板方法,策略设计模式,代理等替换过程是编码;
2.复杂过程做DDD领域分层,做功能模块化拆分;
备注
实现一个功能,一定要考虑后期的扩展性和可维护性。

函数性能考量

项目
描述
描述
许多业务函数,存在性能不高,如重复计算,轮询获取数据等。
缺陷
低性能函数,拉低系统性能。
调整方案
编写函数后,建议思考该函数是否还存在性能优化的空间。
1.内存逻辑代替循环取数逻辑。
2.函数功能单一,避免大而全的函数,导致函数性能下降。
备注
性能考量应该作为代码评审的一个标准。

优雅关闭

项目
描述
描述
系统关闭时,还存在运行的异步线程等如何优雅关闭。
缺陷
不做处理,系统在特殊条件下,存在问题且难以排查。
调整方案
1.编写全局配置文件,重新实现SmartLifecycle接口,重写stop()方法实现优雅关闭。
2.系统关闭时,系统内部设置等待时间,便于执行未完成的任务。
3.记录关闭时,执行异常的日志信息。
备注
单个微服务,应包括优雅关闭模块。

4.感谢

  • 作为一名程序员,您一定在研发过程中,或多或少有过排雷采坑的经历。欢迎留言,分享更多编码调优的经验。
  • 本文参考《java-开发手册-泰山版》,《代码整洁之道》,《重构2》等编码规范,编码理论知识。欢迎留言探讨书中的相关知识。 
posted @ 2022-06-06 13:38  无涯Ⅱ  阅读(563)  评论(0编辑  收藏  举报