铜陵项目后端开发规铜陵项目后端发范

项目背景

项目使用JEECG框架

框架参考文档(优先查看)

数据库规范

建表规范

所有业务表前缀 mes_ 后面跟模块前缀(例如：硫酸：vitriol) 后面跟 业务表名称 如:mes_vitriol_xxxx
后面还有业务含义 继续追加 _XXXX 如 mes_product_operating_order 生产模块_作业指令_作业指令主表

模块前缀

配料渣选熔炼吹炼精炼电解硫酸能源生产
burdenburdensmeltblowrefineelectrolysisvitriolenergyproduct

建表默认包含以下字段：

id varchar(50),
create_by varchar(50),
create_time datetime,
update_by varchar(50),
update_time datetime

表注释规范：
模块名称_业务名称 后面还有业务含义 继续追加 _业务名称
如 生产模块_作业指令_作业指令主表

项目规范

1.开发架构

开发采用mvc 三层架构。这里不多做赘述。
但是要求，一定要保持控制层的干净，将业务拿到服务层去处理。

2.模块创建规范

参照视频创建 https://help.jeecg.com/java/java/gen/module.html

模块名称要求 enfi-business-{模块代号} 例如：enfi-business-vitriol

要求模块创建在 enfi-module-business 模块下面

image-tljx.png
pom.xml 无需添加其他依赖示例：

image-u8uj.png

3.框架结构规范

enfi-module-business 添加了 enfi-module-common 模块

要求公共代码统一放入 enfi-module-common 模块 里面,在前缀为模块前缀的包路径下面例如:

ima5e-gkjc.png

image-xti8.png
将entity 实体类、 mapper包括xml 持久层、service 接口 放在公共模块
将controller 和 service.impl 的接口实现层放到各自的业务模块

4.代码提交规范

代码提交参照 约定式提交
提交信息包含前缀:

image-stuj.png

5.冒烟测试

每个开发都应对自己开发的功能进行自测。严谨是每个程序员的必修课。
不怕一万，就怕万一。
每个功能在开发完成后必须进行冒烟测试(自测)!!!!

6.代码准则

6.1 杜绝垃圾代码

参考垃圾代码书写准则
杜绝项目中出现的垃圾代码，例如：

  • 变量名称不规范
  • 没有代码注释
  • 变量名称函数名称混淆

等垃圾代码。

6.2 控制层规范

要求创建控制层
类名必须包含注解
@Api等注解
例如:

@Api(tags = "{}") //{} 替换为控制层业务名称
@RestController
@RequestMapping("/{}/operate") //{} 替换为当前业务模块前缀
public class XXXController {

}

接口方法必须包含注解
@AutoLog 接口日志记录
@ApiOperation 接口名称
@ApiOperationSupport 接口排序和作者
非必须包含
@ApiParam,@RequestParam GET请求参数名称 GET请求必须包含
@RequestBody POST请求必须包含
例如:

/**
     * 吹炼炉物料
     * @return
     */
    @AutoLog("吹炼主操作工作台接口_吹炼炉物料")
    @GetMapping(value = "/material")
    @ApiOperation(value="吹炼炉物料", notes="吹炼炉物料")
    @ApiOperationSupport(order = 1, author = "xuecxiang")
    public Result<?> XXXX(
            @ApiParam(value = "姓名")
            @RequestParam(name = "name") String name,
            @ApiParam(value = "年龄")
            @RequestParam(name = "age") Integer age){
        List<Map<String, Object>> list =  mainOperatingConsoleService.material();
        return Result.ok(list);
    }

6.3 开发阶段不能添加的注解

@RequiresPermissions

  • 此注解是接口请求权限认证使用的注解，在项目后期需要权限认证的时候，在添加。
  • 此注解是代码生成自带生成的包含在代码中，生成后请自行注释掉
    其他待补充。。。。。。

6.4 接口文档规范

6.4.1 根据不同类型功能，Controller 可以用注释进行划分分组。 比如 同一类功能增删改查

c6b9078a10c7060b882992a2cdc1aee.png
如果功能比较多，接口层代码臃肿的话 可以采用 下面区块方法进行分组。

// region {?}区块名称
代码 
//endregion

例如：
image-umpq.png

6.4.2 界面不需要的冗余接口去除

一般接口文档以模块分组，以界面作为归档一类接口。

但是代码生成器生成的是按照业务表归档的。所以按照各自开发的界面把无用接口去除，或者注释掉。

只保留当前界面需要的接口，不用把接口文档弄得混杂无序。

6.5 上传文件接口

bucket tongling

上传文件 以日期分割路径 yyyy/MM/dd
例如: 2024 的文件路径下 11 文件路径下 25 日下面的文件
2024/11/25/文件.jpg

文件查看下载使用 http://10.10.7.178:9000/ + bucketName/路径/文件名

例如 http://10.10.7.178:9000/tongling/2024/11/25/gold.jpg
d86ae818b3feb8aaba06a5993a08a5f.png

关于业务功能涉及上传文件的，需要保存文件全路径名称 例如 http://10.10.7.178:9000/tongling/2024/11/25/gold.jpg

  • 对记录文件地址操作记录操作:
    • 有删除的，相应关联的文件也要进行删除-指minio里面的文件同步删除，
    • 有更新的，删除旧文件，替换为新文件。此操作必须这样执行。

6.6 编码生产器 通用自定义自增规则流水号表

一般系统中采用生成编码用代码生成，统计当前业务表中最大的单据号自增。 且以日期分割，月分割，年分割，统计最大流水。这样处理效率在数据量变大时会非常的困难，现在设计一套定位当前自增位置，根据日期规则，刷新流水的自定义自增规则流水号方法。

image-y4d0.png

含有流水号编码 流水号前缀 日期格式 流水号长度 当前日期 流水号位置 备注信息

例如：

流水号前缀： ZLMB-1-2
日期格式：%Y%m%d
流水号长度：3
当前日期：20241128
流水号位置：1

生成结果为： ZLMB-1-220241128002

可以通过系统中 CodeRuleUtils.getCodeByRule(流水号编码); 调用

结合jeecg 自身的规则编码生成,可以自定义替换前缀中的占位符号 例如 $1。

image-ospb.png

6.7 数据字典编码名称规范

字典名称创建规范：

单业务情况：业务名称_字典名称
多个业务名称: 业务名称_业务名称1_字典名称 以此类推

字典编码创建规范亦是如此：

单业务情况：[业务编码][字典编码]
多个业务名称: [业务编码][业务编码1]_[字典编码] 以此类推

基础功能类字典， 前面业务名称 统一为基础资料 ， 编码前缀为 base