铜陵项目后端开发规范

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

项目背景

项目使用JEECG框架

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

开发文档 https://help.jeecg.com/java/readme.html

代码生成器 https://help.jeecg.com/java/codegen.html

系统权限控制 https://help.jeecg.com/java/system/auth.html

框架常用注解 https://help.jeecg.com/java/changyongzhujie.html

框架常用功能 https://help.jeecg.com/java/java.html

代码规范 https://help.jeecg.com/java/norm.html

SQL优化技巧 https://help.jeecg.com/java/norm/SQLTuning.html

内存溢出排查 https://help.jeecg.com/java/norm/oomAnalyze.html

WebSocket https://help.jeecg.com/java/advanced/WebSocket.html | https://help.jeecg.com/java/advanced/WebsocketBiz.html

通知消息推送 https://help.jeecg.com/java/advanced/push.html

编码规则生成 https://help.jeecg.com/java/advanced/fillValRule.html

积木报表在线填报 https://help.jeecg.com/jimureport/report/submit.html

积木报表填报数据源 https://help.jeecg.com/jimureport/submit/handler.html

数据库规范

建表规范

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

模块前缀

配料	渣选	熔炼	吹炼	精炼	电解	硫酸	能源	生产
burden	residue	smelt	blow	refine	electrolysis	vitriol	energy	product

建表默认包含以下字段：

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

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

规范化示例

项目运行

项目授权

本项目采用商业版的JEECGBOOT , 需要授权码才能运行。
分为：

框架运行时授权码，主要是OA模块
启动提示：

SN 码随着网络环境的变化使用网口MAC的变化也会重新生成，如何切换如上环境需要重新生成授权码
授权码申请格式：sn@SN号码,使用人手机号,使用人名字 联系单庆超或者王浩发送申请

拿到授权码后替换jeecglic.properties文件的内容，切记此文件之后都不能在Git提交内容内，以免影响其他人使用
积木报表功能授权码，主要应用与积木报表和大屏功能
下载生成SN码JAR包 jm-machinecode-en-1.7.6.jar
执行以下命令获取机器码

java -javaagent:jm-machinecode-en-1.7.6.jar="-pwd nfZNw0Lf4o5x" -jar jm-machinecode-en-1.7.6.jar

备注公司名称和所需许可证类型，将机器码通过邮件发给qinfeng@jeecg.org，生成授权文件 license.lic

备注：中国恩菲工程技术有限公司@积木报表许可证

license.lic配置两种方式
方式一：在运行JAR同级目录创建config目录, 将license.lic放到config目录中即可
方式二：将license.lic放到本地磁盘，例如：D:\opt\jeecglic
修改yml文件增加以下属性，启动程序
jeecg.lic-path=G:\opt\jeecglic

项目启动方式

三种启动方式，可以再不同环境情况下启动。通过切换MAVEN 配置文件来切换。

dev模式启动，引入商业版积木报表和商业版大屏模块
prod模式启动，引入商业版积木报表和商业版大屏模块以及 OA模块
test模式启动，什么都不引入等同于开源版本但是不包含报表和大屏的功能适用于异地开发功能，对商业证书要求网络环境不变的情况去除

切换MAVEN配置在ide 里面的配置方式,选择对应的配置,dev,prod,test 有且只能选一个配置。选择完成后重新加载所有maven项目。启动项目即可。

问题解决：
如果启动后还是不行就用命令行的方式启动，一般都是idea版本太低，无法加载maven相关的配置，在启动项目的时候对应的配置参数不足导致的，下载最新的idea即可解决。
以下是通过命令行是启动,检查项目启动情况：

mvn -pl enfi-module-system\enfi-system-start spring-boot:run -am -D"maven.test.skip"=true -Pdev
mvn -pl enfi-module-system\enfi-system-start spring-boot:run -am -D"maven.test.skip"=true -Pprod
mvn -pl enfi-module-system\enfi-system-start spring-boot:run -am -D"maven.test.skip"=true -Ptest

以下是通过命令行打包项目：

mvn -pl enfi-module-system\enfi-system-start -am clean package -U -D"maven.test.skip"=true -Pdev 
mvn -pl enfi-module-system\enfi-system-start -am clean package -U -D"maven.test.skip"=true -Pprod 
mvn -pl enfi-module-system\enfi-system-start -am clean package -U -D"maven.test.skip"=true -Ptest

项目规范

1.开发架构

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

2.模块创建规范

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

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

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

pom.xml 无需添加其他依赖示例：

3.框架结构规范

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

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

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

4.代码提交规范

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

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 可以用注释进行划分分组。比如同一类功能增删改查

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

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

例如：

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

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

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

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

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

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

例如：

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

生成结果为： ZLMB- $1-$ 220241128002

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

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

6.7 数据字典编码名称规范

字典名称创建规范：

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

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

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

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

6.8 积木报表功能开发指南

因为商业版报表开发功能配置以及普及比较花费时间，在前期以及项目目前阶段并不适用，特部署一商业版本到内网中，可以通过在内网的商业版本的积木报表功能开发报表，在导出到报表的json 文件，然后上传到项目的开源版本中，来节约开发时间。

商业版本内网地址 http://10.10.7.176:8098/ 账号: admin 密码:123456

以下内容 6.8.1 - 6.8.4 是在没有商业版授权的情况下使用，如果有跳过即可

6.8.1 登录后进去积木报表设计页面

点击可视化设计中的报表设计器

6.8.2 创建对应报表功能模块的文件目录

在文件夹下创建对应功能模块的的文件目录
在创建的文件目录下面点击新建报表选中要创建的报表类型

6.8.3 上传excel报表模板和导出报表配置信息

点击上传excel报表模板

上传成功后

没有边框自己添加下边框

导出报表的配置信息

6.8.4 导入报表配置信息到开源版本中

6.8.5 在线填报报表API数据源地址配置规范

积木报表Api 数据源，配置的时候，不用些全路径，直接填写接口地址即可

6.8.6 在线填报报表前端集成格式

/jeecg-boot/jmreport/view/{报表id}/detail/{主键}?token=${token}&tenantId=1 查看指定主键的填报报表
/jeecg-boot/jmreport/view/{报表id}/edit/{主键}?token=${token}&tenantId=1 编辑指定主键的填报报表
/jeecg-boot/jmreport/view/{报表id}/edtor/{主键}?token=${token}&tenantId=1 新增编辑指定主键的填报报表
/jeecg-boot/jmreport/view/{报表id}?token=${token}&tenantId=1&查询参数=值新增和查询和编辑全功能通用

6.8.7 在线填报报表设置子表方式

选择子表区域，且区域内控件绑定数据源（非API）都是统一数据表的属性，右击选择子表/集合设定

6.8.8 在线填报报表查询数据源展示方式

如何查询展示某个字段值配置时可能会设置集合值展示,# 为集合展示，$ 为属性展示.

修改为

查询数据源修改为，去除是否集合和是否分页

6.8.9 在线填报报表配置查询功能

查询数据源配置查询字段属性，需要配合填报数据源，如果是id 必须和填报数据源是同一字段属性。
下面是配置示例配置查询字段为id

报表配置查询属性字段

预览刷新即可生效

6.9 在线表单开发代码生成

6.9.1 修复在线表单开发导入数据库表不含中文注释的,和实体注释不一致的表

WITH table_info AS (SELECT
	table_name,
	table_comment 
FROM
	information_schema.TABLES 
WHERE
	table_schema = DATABASE () 
	AND table_type != 'VIEW' 
	AND (
	table_comment IS NOT NULL 
	AND table_comment != '')
	)
UPDATE
  onl_cgform_head main
	LEFT JOIN table_info info ON main.table_name = info.table_name 
  SET main.table_txt = info.table_comment
WHERE
	main.table_txt NOT REGEXP '[\\u4e00-\\u9fff]' AND info.table_name is NOT NUL

6.9.2 修复在线表单开发同步数据库表不含中文注释的,和实体注释不一致的表

WITH table_info AS (
SELECT
	table_name,
	table_comment 
FROM
	information_schema.TABLES 
WHERE
	table_schema = DATABASE () 
	AND table_type != 'VIEW' 
	AND table_name LIKE 'mes_%'
	AND NOT ( table_comment IS NOT NULL AND table_comment != '' ) 
	)
SELECT
CONCAT('ALTER TABLE ',info.table_name,' COMMENT = ',"'",main.table_txt,"'",';') AS alter_comment_sql,
	info.table_name,
	main.table_txt
FROM
	onl_cgform_head main
	LEFT JOIN table_info info ON main.table_name = info.table_name 
WHERE
	main.table_txt REGEXP '[\\u4e00-\\u9fff]' 
	AND main.table_name LIKE 'mes_%' 
	AND info.table_name IS NOT NULL

如果觉得文章对你有用，请随意赞赏

铜陵项目后端开发规范

https://wuanwanghao.top/archives/tong-ling-xiang-mu-hou-duan-kai-fa-gui-fan

作者

忘皓

发布于

2024-11-07

更新于

2025-02-24

许可协议

CC BY 4.0

铜陵项目后端开发规范

项目背景

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

数据库规范

建表规范

项目运行

项目授权

项目启动方式

项目规范

1.开发架构

2.模块创建规范

3.框架结构规范

4.代码提交规范

5.冒烟测试

6.代码准则

6.1 杜绝垃圾代码

6.2 控制层规范

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

6.4 接口文档规范

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

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

6.5 上传文件接口

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

6.7 数据字典编码名称规范

6.8 积木报表功能开发指南

6.8.1 登录后进去积木报表设计页面

6.8.2 创建对应报表功能模块的文件目录

6.8.3 上传excel报表模板和导出报表配置信息

6.8.4 导入报表配置信息到开源版本中

6.8.5 在线填报报表API数据源地址配置规范

6.8.6 在线填报报表前端集成格式

6.8.7 在线填报报表设置子表方式

6.8.8 在线填报报表查询数据源展示方式

6.8.9 在线填报报表配置查询功能

6.9 在线表单开发代码生成

6.9.1 修复在线表单开发导入数据库表不含中文注释的,和实体注释不一致的表

6.9.2 修复在线表单开发同步数据库表不含中文注释的,和实体注释不一致的表

作者

发布于

更新于

许可协议

评论

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

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