的实现类和一些结构转化application不应该承载业务逻辑

domain

领域层包含应用的业务模型定义全部业务逻辑可以细分实体entity和领域服务service等子包

infrastructure

基础设施层包含配置、基础工具、切面、枚举、外部服务调用、消息、缓存等中间件

interfaces

服务自身API的定义以及与API定义相关的API结构DTO定义

单模块工程结构示例

接口层通常不依赖应用层/领域层可以依赖部分基础设施层工具、类型

应用层依赖领域层处理业务逻辑

领域层不反向依赖应用层和接口层。

可以依赖部分基础设施层工具和类型

禁止大面积拷贝

Java源代码编译成class文件时会保留一些公共部分如类名公共方法名等。

但是JVM出于一些优化考虑会调整一些细节部分如将内部常量变量方法内联省略形参变量名仅保留类型包装异常块等。

因此根据class文件反向编译出来的源代码与生成class的原始源代码大相径庭。

在代码中直接使用反向编译生成的勉强能工作的源代码严重影响可读性后续也极难维护应该杜绝。

错误示例

BusinessDataWriter.save(dataEntities[0].getDataEntityType(),

dataEntities,

DTXServiceHelper.confirmXid(dbkey,

result

DynamicObjectSerializeUtil.serialize(result,

dataEntities[0].getDynamicObjectType())

null);

RecordSaveFormServiceHelper.recordSaveFormToCache(

dataEntities[0].getDataEntityType().getName());

var7

说明直接拷贝第三方/开源代码有版权问题且直接拷贝源码失去了后续迭代的一切可能性在出现漏洞/升级时补救成本巨大。

按照Open-Close原则应该将依赖显式声明在需要修改依赖包API行为时使用装饰器转换器等模式进行扩展。

直接拷贝其他工程的代码也及容易留下无用代码和产生重复代码应该禁止。

###

命名和分包约束

说明类型变量方法签名必须具备一定的自解释性也是代码可读性的重要基础。

在《阿里巴巴编码规范》基础上禁止使用

mapobject,

CalcPersonEntity/CalcPersonPojo

对于数据库映射对象统一使用

领域层实体模型按照3.2放在entity包下其他非实体领域层模型放在model包下####

3.5

CalPersonQuery对于事务类结构建议使用Command结尾或直接语义化命名

*Query

的命名风格。

对于事务类操作可以使用*Command的命名风格也可以直接按照上下文语义进行命名。

####

3.7

对于枚举类型通常不适合在接口层和领域层重复定义为保持层次依赖关系清晰共用的枚举结构建议定义在基础设施层中作为公共结构。

领域层专用枚举可以直接放在domain层model包下。

###

代码结构约定

说明JAVA是面向对象的语言也是JAVA代码保持良好延展性的重要基石。

在描述格式固定的结构时使用类型和对象非常合适可以有效的进行语义化表达和类型约束让更多的错误在编译阶段即可识别和解决。

而不至于留到运行时。

JsonMap等动态类型仅在描述真正不确定的动态结构时是合理的但是如果结构较为固定如获取/设置固定字符串描述的Key使用动态类型表达会绕过一些编译期检查同时往往伴随着诸多类型转换降低了代码可读性重用性和健壮性。

错误示例Map

param

ConfigPropertiesUtil.getContextProperty(application.appId));

param.put(subAppId,

ConfigPropertiesUtil.getContextProperty(application.subAppId));

ConfigPropertiesUtil.getContextProperty(lite.job.client.jobworkerduid));

param.put(jobName,

ConfigPropertiesUtil.getContextProperty(lite.job.client.jobname));

param.put(taskName,

ConfigPropertiesUtil.getContextProperty(lite.job.client.taskname));

JSONObject

箭头函数是一个临时定义的方法缺省了方法签名在内容较少时比较适用。

箭头函数的代码块中不宜存放过多代码内容会导致更多复杂的缩进和嵌套不利于理解。

如果代码块中需要执行的指令较多应该提取为单独的方法进行合适的方法署名。

错误示例list.stream().forEach(beforeVO

{try

LogRecordVo.builder().tableName(PayElementAttributeDomain.LOG_TABLE_NAME).entities(Arrays.asList(PayElementAttributeDomain.LOG_TABLE_NAME)).moduleName(PayElementAttributeDomain.LOG_MODULE_NAME_DELETE).businessNo(String.valueOf(beforeVO.getAttributeId())).operationEnum(LogOperationEnum.DELETE).beforeObject(beforeVO).afterObject(null).build();AsyncMessage

asyncMessage

AsyncMessage(LogRecordConstant.MSG_LOG_RECORD_SEND);asyncMessage.setContent(logRecordVo);messageSender.send(asyncMessage);}

catch

sendMessage(PayElementAttributeBusinessViewDto

vo)

Inversion五部分过多的使用继承关系来获取已有的父类功能和属性不利于代码的可读性和可维护性应该优先使用接口抽象和组合关系表达功能的组合。

错误示例public

class

**说明在Mybatis等ORM框架中可以使用合适的配置写法将结果映射成复杂对象如Mybatis中的accociation配置。

在API中可以通过

JsonUnwrapped

等注解将属性对象的内容展开到父级json块达到与继承相同的JSON格式。

**####

4.4

Code》中这样描述switch语句写出只做一件事的switch语句也很难switch天生就要做N件事。

switch语句本身很复杂也不容易理解一般时候应该避免/减少使用switch-case关键字的使用。

错误示例switch

(operationType)

授权addPermissions(rolePlanEntity,

personInfoEntity.getGlobalUserId(),

billDispatchRolePlanEntity);break;case

延期break;case

取消deleteRolePerson(personInfoEntity.getGlobalUserId(),

billDispatchRolePlanEntity);break;default

operationType

personInfoEntity.getGlobalUserId(),

actionMap.put(“D”,

deleteRolePerson(personInfoEntity.getGlobalUserId(),

Runnable

actionMap.getOrDefault(operationType,

4.5

避免过多的if-else嵌套switch式的if-else使用map进行简化

if-else嵌套时会让代码的分指数显著增加一般需要对一些代码块进行分割并尽量共用重复逻辑部分。

某些连续的

if-else

分支写法其实是类似于switch的表达同样可以使用Map进行简化。

错误示例

此处明显为固定结构应该使用相应的类型进行描述而不是使用Map。

且变量名mp也明显缺乏含义

MapString,

mp.put(“pageSize”,“3000”);//分页数

等价示例

将searchType、pageInfo、pageSize、curPage等固定内容放在构造函数中统一初始化

RequestParam

injectParamAsDate(requestParam,

search_param,

injectParamAsNumber(requestParam,

search_param));

InvalidSearchTypeException(“search

type

typeActionMap.getOrDefault(search_type,

4.6

boolean类型的断言方法一般只用专注与断言条件极其组合而不需要太多分支控制分支控制中的条件可以直接作为boolean的结果返回让代码看起来更加简洁内聚

错误示例

(!StringUtils.isEmpty(configValues))

String[]

deptQueryDao.findChildrensDeptsByCodes(Arrays.asList(values));

(!CollectionUtils.isEmpty(list)

list.contains(currentDeptCode))

当前部门在此部门体系中则允许异地纳税

StringUtils.isNotEmpty(configValues)

deptQueryDao.findChildrensDeptsByCodes(newArrayList(configValues.split(“,”))).contains(currentDeptCode);

4.7

由于没有指定泛型类型代码可读性变差后续使用时通常需要一些强制转换

对比示例

BusinessI18nException(AccumulatorCalcExceptionDesc.ACC_EXISTS_NEWLY_RESULT);

4.9

禁止脱离业务实际需要堆砌CRUD禁止开发预留、测试、无用的API

说明开发人员开始编写代码时需要有清晰具象化的业务需求和边界而不能基于模棱两可的诉求进行开发。

开发阶段对功能进行测试验证时应优先使用单元测试通过编写符合业务诉求的单元测试开发者测试来验证和确保功能实现的正确性而不是在产品代码中留下一些测试、无用的代码。

虽然大部分模型最终都会需要CRUD等接口但是按Story开发功能需求时也应该首先聚焦Story包含的实际功能和边界而不是站在开发的角度无脑添加CRUD四个接口如此做容易留下一些实际上不会用到的功能和接口。

####

5.2

代码中明显存在重复的部分应该及时重构提取公共部分进行共用。

框架性的公共代码考虑使用AOP等方式通过切面和注解统一处理。

错误示例在每个请求之前需要初始化苍穹平台的请求上下文public

SwitchPolicy

RequestContext.getOrCreate();if

(Objects.isNull(ctx.getAccountId()))

{ctx.setAccountId(System.getProperty(requestContext.accountId));}if

(Objects.isNull(ctx.getTenantId()))

{ctx.setTenantId(System.getProperty(requestContext.tenantId));}

}等价示例//

{Around(annotation(HcmContext))public

Object

{initHcmRequestContext();log.info(Initialized

HCM

不同分支中存在较多相同逻辑时分支只负责差异部分相同的部分不重复书写。

避免在不同分支中出现太多重复逻辑分支专注于差异的部分公共部分抽取方法。

错误示例if

(privateBusiness.get(elementTypeCode)

null)

{privateBusinessSet.add(string);}}privateBusiness.put(elementTypeCode,

privateBusinessSet);

privateBusiness.get(elementTypeCode);for

(String

{privateBusinessSet.add(string);}}privateBusiness.put(elementTypeCode,

privateBusinessSet);

Optional.ofNullable(privateBusiness.get(elementTypeCode)).orElse(new

HashSet());

{privateBusinessSet.add(string);}

privateBusiness.put(elementTypeCode,

####

(city.equals(tlasApplicationVO.getToResidentLocation()))

{isAllow

city.trim().equals(tlasApplicationVO.getToResidentLocation()

));Stream常用操作附录

userList.stream().map(User::getLocation).collect(toList())

filter

user.getEnableFlag())).collect(toList());

peek

isValid(user)).collect(toList())

reduce

userList.stream().allMatch(user

isValid(user));

userList.stream().anyMatch(user

isAbnormal(user));

userList.stream().collect(groupingBy(User::getType));

|####

guava是google提供的开发工具包在Java8提供Lambda写法之前就已经存在其提供的多种函数式编程接口非常流行。

在Java8发布之后许多原有的功能逐渐内置到了JVM中但仍然存在一些方便的工具可供使用。

以其集合包还有数学等其他辅助工具包中的一些常用接口举例如下|

接口名

|构造一个List对象可以接受数组其他List或者可变长的Item列表

ListPerson

|除guava外还有一些Apache提供的Utils工具包对于一些常见模式的问题提供了接口封装如StringUtilJsonXML等相关的常用工具等。

###

####

在不同的层次之间经常需要进行类型转换与其手写转换关系不如使用一些常用的工具如MapStructspring

BeanUtils等。

MapStruct会根据对象结构的字段名称在编译阶段生成转换代码类型安全且自动生成空保护等语句通过声明式配置指定转换关系。

spring

BeanUtils基于反射机制进行对象属性映射也可以省略一部分手工编写的类型转换代码但是需要注意copyProperties自身的特性如需要类型匹配以及不会忽略null属性等。

错误示例UserInfoBean

userInfoBean

userInfoBean.setUid(user.getUid());

userInfoBean.setEmployeeNumber(user.getEmployeeNumber());

userInfoBean.setEmail(user.getEmail());

userInfoBean.setEmployeeType(user.getEmployeeType());

userInfoBean.setCn(user.getCn());

spring)

请求参数的非空性有效性长度范围取值范围校验等属于常用的框架级校验一般应该借助框架工具来控制而不需要手动编写代码逐个字段进行手动校验错误示例public

Boolean

submitVisaToDo(SubmitVisaAndSalaryTaxDto

{VisaInfoDto

submitVisaAndSalaryTaxDto.getVisaInfoDto();//

签证数据基础非空校验if

ResultException(I18nConstant.VISA_CATEGORY_NULL);}if

(StringUtil.isNullOrEmpty(visaInfoDto.getTypeCode()))

{throw

ResultException(I18nConstant.VISA_TYPE_NULL);}if

(StringUtil.isNullOrEmpty(visaInfoDto.getComplianceApproval()))

{throw

ResultException(I18nConstant.SALARY_TAX_COMPLANCE_APPROVAL_NULL);}if

(!StringUtil.isNullOrEmpty(visaInfoDto.getDescription())

visaInfoDto.getDescription().length()

ContractPlanEnum.ONE_THOUSAND.getCode())

{throw

ResultException(I18nConstant.SALARY_TAX_REMIND_BEYOND_ONE_THOUSAND);}//...

business

签证大类*/ApiModelProperty(签证大类id)NotBlank(message

I18nConstant.VISA_CATEGORY_NULL)private

Long

签证类型编码*/ApiModelProperty(签证类型编码)NotBlank(message

I18nConstant.VISA_TYPE_NULL)private

String

是否涉及合格审批*/ApiModelProperty(是否涉及合格审批)NotBlank(message

I18nConstant.SALARY_TAX_COMPLANCE_APPROVAL_NULL)private

String

重要提示*/ApiModelProperty(重要提示)Size(max

1000,

I18nConstant.SALARY_TAX_REMIND_BEYOND_ONE_THOUSAND)private

String

后台服务在发生异常时通常需要对异常信息进行一定的处理和包装结构上可与正常相应存在差异。

在Spring框架中提供了统一的异常处理机制RestControllerAdvice按照异常类型和code进行统一修饰。

无需每个API单独处理一遍。

错误示例:Override

public

{localExcelExportAssistant.submitExportTask(payrollCalcService.PayElementLabel,

queryDTO);return

Named(applicationExceptionHandler)

public

ExceptionMapperApplicationException

{Overridepublic

toResponse(ApplicationException

exception)

Response.status(Response.Status.BAD_REQUEST).type(application/json;charsetUTF-8).entity(BasicResponse.error()).build();}

}####

builder模式提供了一种可联连续设置属性的构造对象方式可以较方便的将属性值构造成对象且避免了临时变量的多次出现。

错误示例PageDTO

pageDTO

pageDTO.setPageSize(pageSize);等价示例

PageDTO

PageDTO.builder.pageNo(curPage).pageSize(pageSize).build();

注意使用Lombok注解Builder时会生成全参构造器覆盖默认的无参构造器如果需要保留无参构造器应叠加NoArgsConstructor注解一起使用

7.5

Lombok相关的注解可以在编译期自动生成一下常用的模板代码如构造函数getter/setter等能有效减少模板代码。

错误示例

说明添加Data注解时除了生成getter/setter外还会生成包含所有属性的equals和hashCode方法在对象属性较多接近1000个左右时会无法编译。

一般而言仅需要Getter/Setter而不需要进行对象比较时可以只添加Getter/Setter注解而不是直接使用

7.6

说明Intellij是一个非常智能的IDE在源代码中会给出诸多优化建议和提示如使用灰色文字表示没有被用到的变量/参数使用黄色背景给出一些优化建议等。

鼠标停留在提示的部分IDE会给出相应的说明使用AltEnter会给出对应的修改建议等价于鼠标点击浮出的灯泡按钮。

IDE提示的范围非常广不一一展开称述编写代码时务必参考IDE进行一些必要的优化举例如下

错误示例

集合类已经自己扩充了forEach接口无需转换为stream便可遍历

IDE

batchPersonList.forEach(batchList

save(batchList));

说明Intellij中还包含许多功能强大的插件代码检查、统计、生成等插件等不展开具体说明。

8.1

说明用于测试的代码直接放到测试类中写成单元测试用例不要遗留在产品代码中弃用的代码直接删除不要以注释/标注的方式遗留在代码中

错误示例

logger.info(“----------local—test—start------------”);

SpringContextUtil.getBean(AutoRetentionDataService.class);

autoRetentionDataService.asyncExecute();

logger.info(“----------local—test—end--------------”);

8.2

存在于代码中的注释初衷是对代码进行说明但是一般的开发习惯中对于编译错误运行错误更为关注而对于说明性的文档通常难以时时确保其正确和及时更新注释极易腐化。

因此应该将精力花在编写可执行可校验的单元测试代码上而非撰写过多说明性注释。

错误示例

should_use_company_code_as_payment_company_when_coa_is_chinese_org()

assertEquals(“test_company_code”,

extractedMethod(someCondition));

Test

should_use_coa_as_payment_company_when_legal_entity_is_not_configured()

extractedMethod(someCondition));

Test

should_use_empty_payment_company_when_legal_entity_is_not_configured_and_coa_is_not_chinese()

assertNull(extractedMethod(someCondition));

8.3

测试代码应该和产品代码严格区分禁止在产品代码中添加静态main方法用于测试。

使用产品代码中的main方法测试不容易自动化也存在污染产品代码的风险需要单元测试时应该将测试用例代码放在test目录下

错误示例

LocalDateTime.of(2022,7,01,12,20,21);

LocalDateTime

LocalDateTime.of(2022,8,29,12,20,21);

Date