# java编码规范
java编码规范
# java命名规范
java命名规范
# 文件命名规范
Java⽂件和变量必须为字⺟、数字或下划线（特殊情况下、⽐如与系统关键字冲突）组成并遵循Java命名规范。
不允许使⽤特殊字符、中⽂和其他字符类型。
Java源⽂件命名必须为⾸字⺟⼤写并遵循骆驼命名法，例：ProjectTest.java。
XML系统配置⽂件必须全部为⼩写并已"-"划线先为单词分隔符，例：project-test.xml。
maven模块名小写,多个单词使用
-连接 正确: lowan-iot-core 错误: lowanIotCore包名全部小写,多个单词使用多个目录层级. 正确: com.lowan.core.common.deserializer 错误: com.lowan.core.commonDeserializer 错误: com.lowan.core.common.Deserializer
类名首字母大写,使用驼峰命名. 正确: GroupInfo 错误: Groupinfo , Group_Info
# Java源文件格式规范
⽂件⻓度应少于2000⾏。
package声明是java源⽂件的第⼀个⾮注释⾏，声明当前源⽂件中的类或接⼝所属的package名称。
import声明所有⽤的的类，不声明没有使⽤到的类，尽量避免在源程序中使⽤完整类名，不使⽤通配符⼀次引⼊多个类，必要时写明注释。
类和接⼝声明，每个Java源⽂件原则上只允许⼀个类或接⼝的声明，并写明类注释，类和接⼝⾥的声明⼀般遵循以下原则：
先声明静态变量，再声明⾮静态成员
先声明变量，再声明⽅法
类成员依次按照public、protected、默认的、private级别声明
同名重载⽅法按照参数的复杂性排序，先简单后复杂
所有类成员都必须写明注释描述它的作⽤或逻辑
# 标识符命名
Package必须全部为⼩写字⺟组成，统⼀前缀为：com.lowan，例： com.lowan.ecms.homepage。
Class必须为单词⾸字⺟⼤写并遵循骆驼命名法，使⽤完整单词（除有更⼴泛的使⽤，像URL、HTML）,例：ProjectTest、URL。
Interface同上Classes命名规则。
Methods必须⾸字⺟⼩写并遵循骆驼命名法，例：test()、testMethods()。约定插⼊、更新的命名分别为insertXxxx、updateXxxx。
Variables变量⾸字⺟⼩写并遵循骆驼命名法，除变量以外的所有实例、类和类常量⾸字⺟⼤写并遵循 骆驼命名法，不允许使⽤中⽂、特殊字符（、$、%）等其他⾮英语单词字符命名。Constants声明的类常量全部⼤写，单词使⽤下划线（'_'）分隔。
变量名称应该易于记忆，即能够指出其⽤途。尽量避免单个字符的变量名，除⾮是⼀次性的临时变量。 临时变量通常被取名为i，j，k。
方法名首字母小写,使用驼峰命名. 名称要见名知义.
正确: findById(String id), deployDeviceInstance(List<String>deviceInstanceIdList) 错误: getData(String arg)
局部变量首字母小写,使用驼峰命名. 名称要见名知义.
正确: String deviceId = device.getId(); 错误: String str = device.getId();
常量使用大写,多个单词使用
_分割.正确: static String DEFAULT_CONFIG = "1"; 错误: static String DEFAULTCONFIG = "1";
# 各层命名规约
Service/Mapper(DAO) 层方法命名规约
- 获取单个对象的方法用 get 做前缀。
- 获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。
- 获取统计值的方法用 count 做前缀。
- 插入的方法用 insert 做前缀。
- 删除的方法用 remove/delete 做前缀。
- 修改的方法用 update 做前缀。
领域模型命名规约
- 数据对象：xxxDO，xxx 即为数据表名。
- 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
- 展示对象：xxxVO，xxx 一般为网页名称。
- POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。
# Restful 接口命名
URL使用小写,多个单词使用
-或者/分割,如:device-info,logger/system.通常情况下应该使用URL来描述资源, 使用HTTP METHOD(GET 查询,POST 新增,PUT 修改,PATCH 修改不存在则新增,DELETE 删除)来描述对资源的操作. 在一些特殊操作无法使用HTTP METHOD来描述操作的时候,使用_开头加动词来描述,如: device/_query正确: GET /device-info/1 错误: GET /deviceInfo/1 GET /device_info/1 正确: GET /device/1 错误: GET /getDevice?id=1 , GET /getDevice/1 正确: GET /device/_query , POST /device/_query 错误: GET /queryDevice , POST /queryDevice
# 编程规约
业务模块使⽤表示层-业务层-数据访问层三层结构 即 Controller-Service-Mapper
业务层层接⼝名和实现类名必须使⽤xxxService和xxxServiceImpl命名⽅式,在Spring的Bean定义中使 ⽤xxxService的命名规则,以保证事务的可拦截性
每个⽅法的⽇志必须为:⼊⼝info,中间处理debug,异常处理error,结束info⽅式,使⽤⽅法参考提供的范
所有Class所导⼊(import)的包(package)必须为最⼩范围,严禁出现 import xxx.xxxx.*,即导⼊范围必须明确⾄Class单位
代码SVN/GIT提交和管理范围仅限于上述⽬录和相关⽂件，.iml、.settings、target、.project和.classpath等Eclipse/IDEA配置⽂件不包含在内
线上应⽤POM只能依赖正式包，以避免SNAPSHOT覆盖冲突
杜绝完全不规范的缩写，避免望文不知义
反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function 缩写”成 Fu，此类随意缩写严重降低了代码的可阅读性。
方法参数在定义和传入时，多个参数逗号后面必须加空格
正例：下例中实参的 args1，后边必须要有一个空格。method(args1, args2, args3);
所有整型包装类对象之间值的比较，全部使用 equals 方法比较。
说明：对于 Integer var = ? 在-128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用 ==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。
任何货币金额，均以最小货币单位且整型类型来进行存储
关于基本数据类型与包装数据类型的使用标准如下：
【强制】所有的 POJO 类属性必须使用包装数据类型。
【强制】RPC 方法的返回值和参数必须使用包装数据类型。
【推荐】所有的局部变量使用基本数据类型。
说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或
者入库检查，都由使用者来保证。
正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。
反例：某业务的交易报表上显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线-。所以包装数据类型的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。
- 类成员与方法访问控制从严：
1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
2） 工具类不允许有 public 或 default 构造方法。
3） 类非 static 成员变量并且与子类共享，必须是 protected。
4） 类非 static 成员变量并且仅在本类使用，必须是 private。
5） 类 static 成员变量如果仅在本类使用，必须是 private。
6） 若是 static 成员变量，考虑是否为 final。
7） 类成员方法只供类内部调用，必须是 private。
8） 类成员方法只对继承类公开，那么限制为 protected。
说明：任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。思考：如果
是一个 private 的方法，想删除就删除，可是一个 public 的 service 成员方法或成员变量，删除一下，不
得手心冒点汗吗？变量像自己的小孩，尽量在自己的视线内，变量作用域太大，无限制的到处跑，那么你
会担心的
13.判断所有集合内部的元素是否为空，使用 isEmpty()方法，而不是 size()==0 的方式。
说明：在某些集合中，前者的时间复杂度为 O(1)，而且可读性更好。
正例：
Map<String, Object> map = new HashMap<>(16);
if(map.isEmpty()) {
System.out.println("no element in this map.");
}
14.不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator
方式，如果并发操作，需要对 Iterator 对象加锁。
正例：
List<String> list = new ArrayList<>();
list.add("1");
list.add("2");
Iterator<String> iterator = list.iterator();
while (iterator.hasNext()) {
String item = iterator.next();
if (删除元素的条件) {
iterator.remove();
}
}
反例：
for (String item : list) {
if ("1".equals(item)) {
list.remove(item);
}
}
说明：以上代码的执行结果肯定会出乎大家的意料，那么试一下把“1”换成“2”，会是同样的结果吗？
# 注释规范
类注释
/**
* @ClassName 类名 * @Description ${类描述}
* @Copyright: Copyright (c) 2021</p>
* @Company: www.lowaniot.com</ p>
* @Author hanwan
* @Date 2021/3/31 21:10
* @Version 1.0
**/
public class SmartMeterServiceImpl implement SmartMeterService{
......
}
构造方法注释
/**
* @Description ${构造方法描述}
* @param: devAddr ${参数描述}
* @param: devTypeCode ${参数描述}
* @Author hanwan
* @Date 2021/3/31 21:10
**/
public SmartMeterService(String devAddr, Byte devTypeCode){
......
}
⽅法注释
/**
* @method: ${方法名}
* @description: ${方法描述}
* @param: devInfo ${参数描述}
* @return: Reponse ${返回参数描述}
* @exception (方法有异常的话加)
* @author: xxx
* @date: 2021/3/31 21:10
**/
public Reponse insertDevInfo(DevInfo devInfo){
......
}
成员变量注释
/** The value is used for characterstorage. */
public final char value[];
/** The offset is the first index of thestorage that is used. */
private final int offset;
/** The count is the number of charactersin the String. */
private final int count;
/** Cache the hash code for the string */
private int hash; // Default to 0
常量注释
/** xxxxxxxxxxxxxxxxx */
public static final String SUCCESS = "1000";
⽅法局部信息注释
public void test(){
String a = x; //xxx
//xxx
String b = x;
}
# 单元测试规范
所有新增service与mapper(dao)⽅法必须有单元测试。
单元测试包结构和源码结构必须保持一致
单元测试文件名称是由"被测试文件名+Test"组成
分层依赖测试时，要求各层能够独立模拟消息队列中数据的收发
# 日志规范
当你遇到问题的时候，只能通过debug功能来确定问题，你应该考虑打日志，良好的系统，是可以通过日志进行问题定为的。
使用slf4j
1.使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
2.实现方式统一使用: Logback框架
什么时候应该打日志
1.当你遇到问题的时候，只能通过debug功能来确定问题，你应该考虑打日志，良好的系统，是可以通过日志进行问题定为的。
2.当你碰到if…else 或者 switch这样的分支时，要在分支的首行打印日志，用来确定进入了哪个分支
3.经常以功能为核心进行开发，你应该在提交代码前，可以确定通过日志可以看到整个流程
打日志的正确方式
1.必须使用参数化信息的方式:
logger.info("Processing trade with id:[{}] and symbol : [{}] ", id, symbol);
2.不要进行字符串拼接,那样会产生很多String对象，占用空间，影响性能。
反例(不要这么做):
logger.info("Processing trade with id: " + id + " symbol: " + symbol);
3.**使用[]进行参数变量隔离，**如有参数变量，应该写成如下写法:
logger.debug("Processing trade with id:[{}] and symbol : [{}] ", id, symbol);
4.对于debug日志，必须判断是否为debug级别后，才进行使用
if (logger.isDebugEnabled()) {
logger.debug("The money is " + getTotalMoney());
}
若没有上述判断代码中会先执行getTotalMoney()，然后调用日志输出方法。
此时若设置日志输出为info，则不会显示此debug日志，但是这样已经浪费时间执行了日志输出
日志级别使用
ERROR
影响到程序正常运行、当前请求正常运行的异常情况:
1.打开配置文件失败
2.所有第三方对接的异常(包括第三方返回错误码)
3.所有影响功能使用的异常，包括:SQLException和除了业务异常之外的所有异常(RuntimeException和Exception)
4.如果有Throwable信息，需要记录完成的堆栈信息:
log.error("获取用户[{}]的用户信息时出错",userName,e);
5.如果进行了抛出异常操作，请不要记录error日志，由最终处理方进行处理：
反例(不要这么做):
try{
....
}catch(Exception ex){
String errorMessage=String.format("Error while reading information of user [%s]",userName);
logger.error(errorMessage,ex);
throw new UserServiceException(errorMessage,ex);
}
WARN
不应该出现但是不影响程序、当前请求正常运行的异常情况:
- 有容错机制的时候出现的错误情况
- 找不到配置文件，但是系统能自动创建配置文件
即将接近临界值的时候，例如：
- 缓存池占用达到警告线
业务异常的记录,比如:
- 当接口抛出业务异常时，应该记录此异常
INFO
系统运行信息
1.Service方法中对于系统/业务状态的变更
2.主要逻辑中的分步骤
外部接口部分
1.客户端请求参数(REST/WS)
2.调用第三方时的调用参数和调用结果
说明
1.并不是所有的service都进行出入口打点记录,单一、简单service是没有意义的(job除外,job需要记录开始和结束,)。
反例(不要这么做):
public List listByBaseType(Integer baseTypeId) {
log.info("开始查询基地");
BaseExample ex=new BaseExample();
BaseExample.Criteria ctr = ex.createCriteria();
ctr.andIsDeleteEqualTo(IsDelete.USE.getValue());
Optionals.doIfPresent(baseTypeId, ctr::andBaseTypeIdEqualTo);
log.info("查询基地结束");
return baseRepository.selectByExample(ex);
}
2.对于复杂的业务逻辑，需要进行日志打点，以及埋点记录，比如预付费系统中的下充值逻辑，以及PayOrderController操作(订单审核业务状态变更)。
3.对于整个系统的提供出的接口(REST/WS)，使用info记录入参
4.如果所有的service为SOA架构，那么可以看成是一个外部接口提供方，那么必须记录入参。
5.调用其他第三方服务时，所有的出参和入参是必须要记录的(因为你很难追溯第三方模块发生的问题)
DEBUG
1.可以填写所有的想知道的相关信息(但不代表可以随便写，debug信息要有意义,***有相关参数)
2.生产环境需要关闭DEBUG信息
3.如果在生产情况下需要开启DEBUG,需要使用开关进行管理，不能一直开启。
说明
如果代码中出现以下代码，可以进行优化:
//1. 获取用户基本薪资
//2. 获取用户休假情况
//3. 计算用户应得薪资
优化后的代码:
logger.debug("开始获取员工[{}] [{}]年基本薪资",employee,year);
logger.debug("获取员工[{}] [{}]年的基本薪资为[{}]",employee,year,basicSalary);
logger.debug("开始获取员工[{}] [{}]年[{}]月休假情况",employee,year,month);
logger.debug("员工[{}][{}]年[{}]月年假/病假/事假为[{}]/[{}]/[{}]",employee,year,month,annualLeaveDays,sickLeaveDays,noPayLeaveDays);
logger.debug("开始计算员工[{}][{}]年[{}]月应得薪资",employee,year,month);
logger.debug("员工[{}] [{}]年[{}]月应得薪资为[{}]",employee,year,month,actualSalary);
TRACE
特别详细的系统运行完成信息，业务代码中，不要使用.(除非有特殊用意，否则请使用DEBUG级别替代)
规范示例说明
@Override
@Transactional
public void createUserAndBindMobile(@NotBlank String mobile, @NotNull User user) throws CreateConflictException{
boolean debug = log.isDebugEnabled();
if(debug){
log.debug("开始创建用户并绑定手机号. args[mobile=[{}],user=[{}]]", mobile, LogObjects.toString(user));
}
try {
user.setCreateTime(new Date());
user.setUpdateTime(new Date());
userRepository.insertSelective(user);
if(debug){
log.debug("创建用户信息成功. insertedUser=[{}]",LogObjects.toString(user));
}
UserMobileRelationship relationship = new UserMobileRelationship();
relationship.setMobile(mobile);
relationship.setOpenId(user.getOpenId());
relationship.setCreateTime(new Date());
relationship.setUpdateTime(new Date());
userMobileRelationshipRepository.insertOnDuplicateKey(relationship);
if(debug){
log.debug("绑定手机成功. relationship=[{}]",LogObjects.toString(relationship));
}
log.info("创建用户并绑定手机号. userId=[{}],openId=[{}],mobile=[{}]",user.getId(),user.getOpenId(),mobile); // 如果考虑安全，手机号记得脱敏
}catch(DuplicateKeyException e){
log.info("创建用户并绑定手机号失败,已存在相同的用户. openId=[{}],mobile=[{}]",user.getOpenId(),mobile);
throw new CreateConflictException("创建用户发生冲突, openid=[%s]",user.getOpenId());
}
}