良好的后端开发规范

后端框架地址：https://gitee.com/xiaoZ1712/fz-cloud-partent

1.基本准则

1.1程序员的基本素养

1.抱有怀疑心： 对任何其他地方过来的数据都充分抱有怀疑态度，优先考虑数据异常时的处理情况；

2.不要让错误传递： 要求所有的系统（包括前端）都具备容错的能力，考虑到发生错误时的解决方式，不要让错误影响其他的功能；后端发生的所有错误都要自己吸收，不要传递到前端影响客户体验；

3.系统环境支持快速切换： 至少支持开发环境和生产环境两个环境的快速切换（要求必须知道现场环境的地址）；

1.2后端开发流程

为了能够快速的响应前端以及客户需求，现提出后端开发五步走：
1.编写接口文档，包含接口参数和接口说明，设计出具有支撑前端的接口，并标明接口参数和接口说明，设计完成后于前端以及模型组统一对接；
要求：设计时充分考虑系统的扩展性和健壮性能，这是一个程序员基本的素养，要考虑这些接口不会只被这一个服务调用。
2.编写演示系统，只写web接口，web层接口直接返回测试数据（编写的和真实数据一样，可以一直使用）；
3.在公司环境部署演示版本，将接口发布到中台，前端可以直接调用接口进行开发；
4.设计数据库，开发后端功能和业务逻辑；
5.部署开发环境版本，进行接口自测和前端联调；

2.数据库规范

2.1数据库表命名规范

表命名格式：ad(应用层)_项目名称_功能_实体类名
例如：ad_ljshow_countbyday_usernum

2.2数据库公有字段名称（应用层）

关于业务相关的常用字段，指定出统一的名称；
包含主叫号码、被叫号码、主叫位置、被叫位置、小区名称等，制定好统一的名称发布出来；

2.3 数据库建表语句规范

建表每一行要有COMMENT 备注，表要有整体描述，如：

3.项目工程规范

3.1工程命名规范

如大屏展示：lj-show

3.2打包规范

包命名：工程名-端口-版本（将打包日期V20201124暂定为版本）
打完包需要添加《工程名-端口-版本-readme.txt》文件说明包更新内容，现场部署人员部署完成后回填部署地址；

3.3工程端口规范

一个具体系统从9100开始，依次向下；
将管局部署的所有系统统一收集，做好管理工作；

3.4接口调用路径规范

接口调用地址统一遵照格式:/lj /工程名称/应用名称/接口名称；
接口命名方式统一参照开发规范.接口调用及命名规范；

4.项目编码命名规范

4.1基本原则

1.类名采⽤“⼤驼峰式”命名，例如：DataOpenApiInfo
2.变量名、⽅法名采⽤“⼩驼峰式”命名，例如：apiId、toString()。
3.日期数据统一采用yyyy-MM-dd HH:mm:ss字符串格式
如：2020-11-24 22:40:00
4.所有工程包命名为com.comleader.lj.系统名称
包命名全小写：
实体类包：domain
工具类包：util
公共类包：common
持久层:dao
服务层:service
web层：controller
5.常量命名、枚举命名采⽤全大写，多个单词以_分割的命名方式，例如：TASK_TIME，枚举SUCCESS。

4.2实体类

包名：domain
类名：大驼峰式，与数据库同名，不带_：
如：ad_ljshow_usernum_countbyday --> UsernumCountbyday

4.3持久层

框架：MyBatis
包名：mapper
类名：实体类名+Mapper
xml名：与类名同名,xml，xml放在resource资源目录下与类同名同路径；

4.4服务层

包名：service
命名规范：实体类+Service
注意：暂时去除接口与impl实现类，直接编写Service实体类
4.5控制层
包名：web.controller
类名：实体类+Controller

4.6工具类

包名：util

4.7公共类

包名：common
下属包：config、bean、util
config：配置类型+Config
bean：前后端交互所用类如：ResponseResult:返回的json格式实体类,返回数据接口统一调用该类，以及枚举类
工具类：util,类名：工具操作类型+Util

4.8定时任务

包名：task
实体类名：服务功能+task

4.9配置文件

4.9.1SpringBoot配置文件
application.yml
注意: 每个系统必须支持生产环境切换，生产环境命名为pro-+application.yml，开发环境命名为dev-application.yml，要支持切换
4.9.2系统配置文件
命名：win-+config.properties/linux-+config.properties，放在resource、config目录下
配置内容命名规范：
模块.功能.配置属性=配置内容
映射配置类位于common/config/ConfigProperties

5.Web编程规范

5.1Mybatis逆向工程

前提：idea中安装idea-mybatis-generator插件
使用：修改resources下generatorConfig.xml信息，设置表明与要生成的类型，需要修改的地方已用TODO标识出来;
结果：会自动生成实体类和Mapper接口以及Mapper.xml；

5.2Ctroller层

5.2.1开发规范
功能内聚：负责参数校验，空值处理，调用service层查询，不写任何业务逻辑；
空值校验统一采用ResponseCodeEnum.INVALIDPARAM枚举抛出空值异常，由ExceptionCatch类统一处理
代码示例：参考工程中DemoCtroller类

5.2.2接口调用规范
调用规范采用Restful，要求如下：
查询接口：get请求，参数放在url中；
后端参照格式：@GetMapping(“/getXxx/{page}/{size}”)，
命名：getXxxBy参数1And参数2/参数1/参数2
参数取出示例：@PathVariable(“page”) int page, @PathVariable(“size”) int size
示例：getDemoById,getDemoListByPageAndSize;
注意：如果是单条按照以上命名，列表查询时采用getXxxList，且By后面的条件必须要少；

添加接口：post请求,参数放在body中
后端参照：@PostMapping(“/add”)
命名：/addXxx
参数取出示例：@RequestBody Xxx xxx

修改接口：put请求，标识参数放在url中，具体的修改数据放在body中；
后端参照：@PutMapping(“/editXxx/{id}”)
命名：/editXxx/{id}
参数取出示例：@PathVariable(“id”) String id,@RequestBody Xxx xxx

删除接口：delete请求，参数放在url中;
后端参照：@DeleteMapping(“/del/{id}”)
命名：/delXxx/{id}
参数取出示例：@PathVariable(“id”) String id

5.2.3接口返回数据规范
返回数据采取统一格式：
{
“success”:true, // 运行是否成功，值true或者false
“code”:200, // 操作代码
“message”:”成功”,//提示信息
“data”:{ // data内放页面具体所需信息，使用类名作为属性名，多条（list）加上List后缀
“userList”:[]
}
}

5.3Service层

功能内聚：负责返回值空值校验，编写业务逻辑，当逻辑判断出现问题时直接使用ExceptionCast.cast(ResponseCodeEnum.NULL_RESULT)抛出异常，注意：枚举类中需要编写异常代码，暂时不要写接口，直接以实体类+Service作为实现类；
代码示例：参考工程中DemoService类
注意：
1.单表查询统一使用example查询，多表关联查询需要自己写xml配置（也可以通过代码逻辑进行关联）；
2.查询类返回结果统一采用List集合，操作类统一采用ResponseResult；

5.4Dao层

功能内聚：使用Mapper接口来统一进行数据查询，在需要自己编写Mapper接口时优先选用@Select注解方式；

5.5异常处理

调用ExceptionCast.case处理可预知的异常，ResponseCodeEnum枚举类中可以添加自定义的错误信息。用这种方式抛出的异常会被ExceptionCatch类统一处理返回给前端异常信息;

6.其他规范

6.1代码注释规范

类注释: 要有创建人，时间，类简要说明；
方法注释: 要有作者，方法调用路径（不包含ip端口），方法功能说明；

6.2接口文档规范

文件命名：系统名称-功能模块名称-开发人员名称.doc

后端框架地址：https://gitee.com/xiaoZ1712/fz-cloud-partent