代码开发规范

目录

 

一、命名规约

1、各层类名命名规约

类型	说明	示例
Mapi数据实体	业务实体 +Do	AirportShopGroupDo
Web请求返回实体	业务实体 +Bean	AirportTaxiBean
Service接口Jar包中暴露出去的业务实体	业务实体 +DTO	ShopConfigDTO
数据库实体	业务实体 + Entity	ShopConfigEntity
工具	功能 +Utils（业务无关的工具类下沉到vc-sdk中）	PayPlatformUtils
Dao	功能 + Dao（体现与哪张表有关）	ShopConfigDao
枚举	枚举对象 + Enum	OrderStatusEnum
接口实现	接口 + Impl	接口：BookOrderService 接口实现：BookOrderServiceImpl
领域服务	接口：领域服务 + DomainService 接口实现：领域服务 + DomainServiceImpl	接口：BookOrderDomainService 接口实现：BookOrderDomainServiceImpl
展示服务	接口:展示服务+DisplayService 接口实现:展示服务 + DisplayServiceImpl	接口:ProductDisplayService 接口实现:ProductDisplayServiceImpl
聚合服务	接口:业务类型+AggregateService 实现:业务类型+AggregateServiceImpl	接口:ProductAggregateService 实现:ProductAggregateServiceImpl
流程服务	接口:业务类型+ProcessService 实现:业务类型+ProcessServiceImpl	接口:OrderProcessService 实现:OrderProcessServiceImpl

 

2、各层方法命名规约

层次	业务意义	方法命名规则	参数规约	示例
dao层	增加	以add开头	必须是entity	addCarPrice
	删除	以delete开头		deleteCarPrice
	修改	以update		updateCarPrice
	批量查询	以find	非entity	List findCarPricesByCarId
	单个查	以load	非entity	CarPriceEntity loadCarPrice
	数量统计	以count开头
service层/web层的service	查询的结果是集合	以find开头	方法参数值不能超过3个	List findOrders
	查询的结果是单条	以load开头		OrderDTO loadOrder
	查询的是数量统计	get+业务+Count
	修改	以update开头		Response updateStatus
	添加	以add开头		Response addDpPartnerOrderMap
	删除	以delete开头
通用	对象转化	以convert开头		ItemDTO convertCscProductDTO2ItemDTO(CscProductDTO cscProductDTO)
	对象填充的方法名	以build开头		String buildCarSubBrandPageActionUrl(CarBrandDTO carBrandDTO, int platform, int cityId)

 

3、web层API-URL命名规约

URL规范

二、格式规约

1、【强制】禁止代码里出现else/swith/do

2、【强制】单行字符数限制不超过120 个（在IDEA中可以在Code style中 设置Hard wrap at 的值为120）

3、【强制】方法之间必须空一行，类的每个变量定义需要空一行

4、【强制】逻辑分支之间必须有空行

5、【强制】变量申明顺序必须遵循以下顺序:

1)、日志变量

2)、静态变量

3)、bean注入

4)、方法定义

6. 【强制】禁止代码层次超过3层

7. 【强制】禁止一个方法超过50行

8. 【强制】禁止在条件判断中超过2个条件

说明:将复杂逻辑判断的结果赋值给一个有意义的布尔变量名。

正例: //伪代码如下 boolean existed = (file.open(fileName, "w") != null) && (...) || (...);

if (existed) { ...

} 反例: if ((file.open(fileName, "w") != null) && (...) || (...)) { ... }

 

三、oop规约

1. 【强制】禁止for循环体内调用pigeon服务,可以看是否有批量接口或者考虑异步化、并行化。

2. 【强制】pigeon服务依赖必须要设置合理超时时间；

3. 【强制】对外暴露的接口签名，禁止修改方法签名，避免对接口调用方产生影响。

4. 【强制】接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么

5. 【强制】查询服务返回结果是集合，必须选择以下一种处理:

1)参数传limit

2)参数传入的集合必须限制大小

3)1和2都不满足情况下，必须默认一个limit限制条数

6. 【强制】禁止出现重复代码

7. 【强制】POJO以及接口定义对于基本类型需要用简单类型，禁止用包装类型

8. 【强制】类成员与方法访问控制从严: 1) 如果不允许外部直接通过new来创建对象，那么构造方法必须是private。

2) 工具类不允许有public或default构造方法。 3) 类非static成员变量并且与子类共享，必须是protected。 4) 类非static成员变量并且仅在本类使用，必须是private。 5) 类static成员变量如果仅在本类使用，必须是private。

6) 若是static成员变量，必须考虑是否为final。 7) 类成员方法只供类内部调用，必须是private。 8) 类成员方法只对继承类公开，那么限制为protected。

9.【建议】方法内的代码层级应该在一个抽象层次

 

四、异常处理规约

1.【强制】远程调用返回结果必须判空

2.【强制】集合循环必须判空

3.【强制】暴露给外面的服务必须校验参数

4.【强制】调用远程接口，远程接口返回为空时，需要对空进行处理，不允许直接返回上层空对象

 

五、集合处理规约

1. 【强制】禁止手动进行集合判空，使用工具类MapUtils.isEmpty(),CollectionUtils.isEmpty()

2. 【强制】初始化数组时需要使用工具类来初始化，如：Lists.newArrayList(), Maps.newHashMap();

3. 【强制】ArrayList的subList结果不可强转成ArrayList，;

说明:会抛出ClassCastException 异常:java.util.RandomAccessSubList cannot be cast to java.util.ArrayList 。

subList 返回的是 ArrayList 的内部类 SubList，并不是 ArrayList ，而是 ArrayList 的一个视图，对于SubList子列表的所有操作最终会反映到原列表上。

4. 【强制】禁止在 foreach 循环里进行元素的 remove/add 操作。

说明:remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。

 

六、并发处理规约

1.【强制】禁止使用SimpleDateFormat 是线程不安全的类。

2.线程池强制用新垂直线程池:在线程池配置

 

七、注释规约

1.【强制】禁止使用//单行注释

2.【强制】注释的废代码必须删除

3. 注释按以下规则书写

	必须要包含的注释说明
接口	接口的职责，接口方法的职责 每个接口方法的输入输出参数说明（例如：是否必须，长度限制，有哪几种返回错误码）
web api	每个web请求参数的说明（含义，限制等） web api的职责
工具类	每个方法的职责，最好包含使用示例

 

八、日志规则

//TODO runtimeexception滥用

九、超时/重试规则

1、名词解释

• 服务提供方：提供某些功能的服务

• 外部服务：除己以外的服务

• 在线服务：实时提供某些功能的服务。

• 离线服务：时间调度的服务，比如，job任务调用的服务

2、超时时间

【强制】服务调用必须设置超时时间

【强制】在线服务A依赖B、B依赖C，B调用C的超时时间<=A调用B的超时时间

【建议】超时时间设置为外部服务99线响应时间或服务提供方承诺的响应时间

【建议】在线服务最大超时时间不能超过1s

3、调用重试

【强制】只有当网络超时的时候或服务端明确告知可以重试的时候才能重试，除此之外没有其他条件需要重试

【强制】重试要确保服务提供方有幂等能力

【强制】在线服务禁止设置重试

【强制】重试需要设置最大重试次数，禁止无限重试

十、其他

【强制】对象中有嵌套对象，不允许使用浅拷贝复制

十一、其他说明