Skip to content

Latest commit

 

History

History
105 lines (57 loc) · 4.13 KB

BACKEND.md

File metadata and controls

105 lines (57 loc) · 4.13 KB

福大时光机后端开发规范

1.领域结构设计

前言

为了项目的解耦,方便日后扩展以及提高其安全性,简单地引入三种模型,分别为 DTO,PO,VO,每一种模型担任不同的角色。下面通过数据传输过程进行介绍

数据流图

数据流图

前端---->DAO层

前端生成DTO(传输对象),控制层接收,并通过简单的参数校验之后继续传递到服务层。服务层对DTO进行业务处理,将其转换为PO(持久化对象),PO传递到DAO层,进行与业务有关的DAO操作

DAO层---->前端

DAO层生成PO(可选,仅当与查询相关操作的情况下发生),服务层接收DAO层返回的PO,并将其转换为VO(视图对象),继续传递给控制层,控制层继续包装VO,将VO注入到ApiResult中的Data,最后返回给前端

命名

PO:实体名称,例如User;DTO:实体名称DTO,例如LoginDTO,VO:实体名称VO,例如UserVO

模型转换

统一通过org.modelmapper转换

其他

禁止不同种类的模型之间相互嵌套

当层与层之间传递的参数小于等于2时,可直接通过传参,但参数大于2时必须采用模型进行封装

2.错误处理

前言

错误一共分为两种,一种为参数错误,另一种为业务逻辑错误。为提高整体的性能,应该尽可能地在上层对非法的请求进行拦截,减小下层的处理压力。因此,参数校验在控制层完成,业务逻辑校验在服务层完成

参数错误

通过JavaX验证框架Spring验证框架进行校验,前者可校验RequestParam对象,后者可校验ReqeustBody对象。以注解的形式完成校验,具体参照项目已有代码

业务逻辑错误

针对每一个服务层,如UserService,设计一个错误枚举类,例如UserErrorEnum,并实现ApiError接口,定义各种逻辑错误的错误代码和提示信息。服务层遇到逻辑错误时则直接抛出异常,例如,执行Login的业务处理时,服务层检测到登录验证码错误,则直接抛出异常,如throw new ApiException(UserErrorEnum.CAPTCHA_INVALID);

3.注释

类注释

所有的类(除了服务层的实现类及DAO层的类)都必须包含注释,注释模板如下(可通过IDE自动导入):

/**
* @description: 
* @author: hlx ${YEAR}-${MONTH}-${DAY}
**/

PS:@description写上关于该类的描述,不超过一行

函数注释

所有的函数(除控制层的函数)必须包含注释,包括函数的作用说明(必选),参数的说明(必选),返回值说明(可选)

变量注释

对变量进行说明,例如一些比较重要的变量,可选

代码注释

对一些较为关键的代码进行注释,增加阅读性,可选

4.Api文档

前言

为加快开发效率,引入 swagger ,快速生成 Api 文档,唯一缺点是代码侵入性

Swagger

所有控制层的接口和 DTO 模型(前端传输过来的对象)均加上 swagger 相关注解,具体看项目已有代码
控制层: @ApiOperation (必选) + @ApiImplicitParam (可选,当参数不为DTO时必须加上)
DTO: @ApiModel (必选) + @ApiModelProperty (必选)

5.控制层响应

所有的接口均要有返回,统一返回 ApiResult<?>,接口返回分为两种情况
第一种为无数据返回,即前端不需要任何响应数据,则返回一个 ApiResult<String>,并通过 setText(),填充提示信息
第二种情况为有数据返回,根据数据对象,创建一个 ApiResult<Data>,并通过 setData()填充需要的数据

6.命名规范

DAO

以 save,delete,update 和 get 开头,并根据所需要的参数进行补充,例如:通过 openId 获取用户,则命名为getByOpenId,如果参数多个则参数之间通过And连接
例外: 当条件参数为主键,例如 id,则直接命名为 get

PO

持久化对象与数据库中的表相对应,类名以及其成员变量名均需要项目组共同讨论和商议确定,任何私自定义的持久化对象均不予接受