铜陵项目后端开发规范

项目背景

项目使用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

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

规范化示例

数据库开发规范

1.1 没有必要且必须的情况下，禁止数据库使用触发器相关配置
1.2 如果有必要的原因需要使用触发器，一定要通知大家。并且做好记录。
1.3 数据库创建使用视图，严禁嵌套视图，视图之前禁止互相引用。视图构成的sql必须也只能是基础表。
1.4 强调表注释，表注释，表注释，创建表之后不要漏掉注释。
1.5 非有特殊情况一些不用的表，不要留着数据库中。前期开发使用的表，后续因为一些特殊情况，还在保留，但是已经不再使用了。清理掉僵尸表和项目中的crud 代码。

项目运维

项目授权

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

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

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

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

java -javaagent:jm-machinecode-en-1.7.jar="-pwd nfZNw0Lf4o5x" -jar jm-machinecode-en-1.7.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

配置同步

同步开发环境到生产环境步骤：

同步之前先备份现场环境表，在本地navicat 选择现场生产环境库，备份。
同步结构，使用navicat 比对开发环境数据库结构和生产环境，比对完执行更新sql.
同步配置信息，使用群里发的sqlyog 配置文件，同步开发环境中报表，流程，在线表单等配置到现场生产环境。

出现问题根据备份文件恢复数据步骤:

根据出现问题的情况，确认需要恢复数据的指定天数的备份文件。
根据备份文件，创建一个新的数据库，名字叫做【业务库】_【日期】来创建将备份文件放到备份功能下面，点击恢复，选择找到要恢复的数据表。点击确认。恢复完成
根据备份库的数据表，同步数据。根据实际情况，是否同步表结构，然后同步数据恢复。

项目规范

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.问题解决流程(严格准守)

开发解决问题思路：
第一步，发现问题，看错误日志，根据错误日志追溯解决问题
第二步，根据问题，查看相关文档或者百度搜索，看是否有相关内容介绍解决问题
第三步，根据出现的问题，以及问题步骤，以及自己要实现的预期结果，详细描述，在开发群里一起讨论解决。

开发规范

1 杜绝垃圾代码

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

变量名称不规范

没有代码注释

变量名称函数名称混淆

等垃圾代码。

2 控制层规范

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

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

}

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

/**
     * 吹炼炉物料
     * @return
     */
    @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);
    }

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

@RequiresPermissions

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

@AutoLog("XXXX接口_XXX")

此注解按需使用，处理 新增 修改 删除 这类的接口添加 @AutoLog 注解，其他查询用的接口，一律不要添加，除非特殊场景需要作分析的。

其他待补充。。。。。。

4 接口文档规范

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

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

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

例如：

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

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

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

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

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.1 编码生成器使用方法：

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

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

例如：

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

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

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

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

6.2 通用自定义自增流水号规则同步生产环境

devDs 开发环境数据源配置，替换开发环境数据库连接地址
prodDs 生产环境数据源配置，替换生产环境数据库连接地址

对应流水自增规则，在开发环境定义好，发布生产环境这个是不能通过配置文件同步的方式的，因为有记录不同的流水码位置，容易和生产环境造成冲突，使用这个测试方法同步，可以将开发环境没有同步到生产的流水规则同步过去。

7 数据字典编码名称规范

字典名称创建规范：

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

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

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

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

8 积木报表功能开发指南

8.0 积木报表常用配置

jeecg:
   # 积木报表参数设置
  jmreport:
    # 接口超时设置（毫秒）30*1000*10 = 300s  = 5min
    connect-timeout: 3000000
    # 列数(设计页面展示多少列)
    col: 1200

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

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

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

/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&查询参数=值新增和查询和编辑全功能通用

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

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

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

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

修改为

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

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

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

报表配置查询属性字段

预览刷新即可生效

8.6 配置填报报表，控件边框不显示样式

.ivu-collapse-content-box  .ivu-input, 
.ivu-collapse-content-box  .ivu-input-number, 
.ivu-collapse-content-box  .ivu-select-selection{
   border: 1px solid #dcdee2;
}
.ivu-input, .ivu-input-number,.ivu-select-selection{
    border: none; /* 完全去除边框 */
}
.ivu-input-number-focused:not(:hover) {
    -webkit-box-shadow: 0 0 0 0px rgba(45, 140, 240, .2);
}

8.7 数据报表区分行不同值情况下渲染验收的单元格表达式

=(let type= '#{info.hour}'; 
if(type== '合计：'){
   return  rowcolor('#{info.hour}','red','yellow');
}elsif(type== '总计：'){
   return  rowcolor('#{info.hour}','black','red');
}else{
   return  rowcolor('#{info.hour}','black','');
})

9 在线表单开发代码生成

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

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

10. 开启嵌套翻译注解`@EnableDictTranslation`

系统翻译功能前提：系统默认的字典翻译功能是不支持嵌套翻译的，系统翻译是对返回值 Result<IPage<?>> 分页类型的数据进行翻译的。
使用这个注解 @EnableDictTranslation 可以开启嵌套翻译，标注在类上类里面的所有方法都生效，标注在方法该方法生效，就近原则方法上的注解配置优先级最高,
考虑到对机器性能，优化功能使用按需使用，哪里需要嵌套翻译，再去使用这个注解开启。
如果有的地方没有用的分页，也需要翻译那么使用@EnableDictTranslation 也可以开启翻译
@EnableDictTranslation 的属性 deep 默认为 true 表示开启嵌套翻译，如果场景情况只是需要翻译表层，优化性能的情况，可以把 deep 设置为false
注意事项,因为spring中对切面代理的返回属性有要求,如果返回类型是实体类这种对象是无法处理的。最后会转换成JSONObject 类型，出现类型转换错误。这时候将方法的返回类型修改为Object即可解决。

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

铜陵项目后端开发规范

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

作者

忘皓

发布于

2024-11-07

更新于

2025-05-26

许可协议

CC BY 4.0

铜陵项目后端开发规范

项目背景

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

数据库规范

建表规范

数据库开发规范

项目运维

项目授权

项目运行

项目打包

配置同步

同步开发环境到生产环境步骤：

出现问题根据备份文件恢复数据步骤:

项目规范

1.开发架构

2.模块创建规范

3.框架结构规范

4.代码提交规范

5.冒烟测试

6.问题解决流程(严格准守)

开发规范

1 杜绝垃圾代码

2 控制层规范

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

4 接口文档规范

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

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

5 上传文件接口

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

6.1 编码生成器使用方法：

6.2 通用自定义自增流水号规则同步生产环境

7 数据字典编码名称规范

8 积木报表功能开发指南

8.0 积木报表常用配置

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

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

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

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

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

8.6 配置填报报表，控件边框不显示样式

8.7 数据报表 区分行 不同值情况下 渲染验收的 单元格表达式

9 在线表单开发代码生成

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

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

10. 开启嵌套翻译注解@EnableDictTranslation

作者

发布于

更新于

许可协议

评论

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

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

8.7 数据报表区分行不同值情况下渲染验收的单元格表达式

10. 开启嵌套翻译注解`@EnableDictTranslation`