2025年运销宝平台开发规约

大家好，我是讯享网，很高兴认识大家。

运销宝平台开发规约

数据库表设计

全字段注释
- 所有字段必须都要有明确的注释。
字符集
- 数据库及表必须为utf8mb4。

必需字段

建表语句必须包含如下6条：

`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id', `is_deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '0有效/1删除', `create_user_code` varchar(30) DEFAULT NULL COMMENT '创建用户编码', `update_user_code` varchar(30) DEFAULT NULL COMMENT '更新用户编码', `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'

讯享网

必需索引
- 索引名：唯一索引uidx_xxx；普通索引idx_xxx。
- 必需索引：id、业务唯一标识、update_time。
```
讯享网 PRIMARY KEY (`id`), UNIQUE KEY `uidx_user_code` (`user_code`), KEY `idx_update_time` (`update_time`) 
```
关联字段
- 不能是自增主键（id），而应该是“业务唯一标识”，如uid，user_code，等。
保留字
- 常见的有，name，names，status，type……具体参见MYSQL官方保留字

增删改查代码生成

必须采用封装好的工具类生成数据库表对应的entity、mapper、service、controller、mapping.xml
注意：自动生成的实体类中，可能会出现变量类型不准确的情况，tinyint会被生成为Boolean，应该改为Integer。

重复代码抽离

禁止“整块”的代码出现两次及以上，而应该抽离成为方法被调用多次。

对象创建

禁止在流程代码中直接嵌入“new + set”来创建对象并赋值属性；而应该是抽出一个buildXxx()方法或者使用build（建造者）模式来创建对象。

对象流转

DO：O-R Mapping的原始实体类，类名与数据库表名一致，字段名数据库表字段一一对应。

如：TmsOrder.java -> tms_order。mapper中，所有insert、update语句，接收的参数必须是DO；所有select语句，返回的数据必须是DO。
VO：用于前台展示，数据即展示，前端无需再做映射、转换等操作。由controller层返回给前端。

举例：在TmsOrder.java中有两个字段，分别是【Integer orderStatus = 20】和【Date orderTime = new Date()】，代表订单状态和下单时间；在TmsOrderVo.java中，应该为【String orderStatusTxt=“审核中”】和【String orderTimeTxt=“2020-09-17 08:12:28”】。
Query：用于前台调用后端列表查询接口时的参数封装。由controller接收，传给service，service再传给mapper，作为select语句中where筛选条件。

举例：如果要按【下单时间从】【下单时间至】【订单状态】三个条件来查询订单，则TmsOrderQuery.java中应该有字段【Date orderTimeFrom】【Date orderTimeTo】【Integer orderStatus】。

讯享网
Dto：用于前台调用后端“写”接口时的参数封装，由controller接收，传给service，service将DTO转换为DO，传给mapper做insert/update操作。
对象流转示意图：

基本类型变量包装

对于基本类型，int/long/boolean，作为成员变量时，必须采用其包装形式，Integer/Long/Boolean

POJO类要素

必须有@Data注解（生成getter/setter/toString）。
必须实现java.io.Serializable接口，且补充private static final long serialVersionUID=1L。
DO是与数据库表严格对应的实体类，禁止在DO中补充任何方法和字段。

禁止魔法值

禁止在业务流程代码的任何地方出现“写死”的值，包括字符串、数字、符号、等等。所有常量都应该汇总到常量类中，作为public static final变量出现。

金额比较

禁止使用equals比较两个BigDecimal的值，因为BigDecimal在做equals判断是，不仅仅会比较数值，还会比较精度，如BigDecimal(“1.5”).equals(BigDecimal(“1.50”))是false。
必须使用compareTo来比较两个BigDecimal的值是否相等（返回结果为0）。

ArrayList容量

必须为ArrayList指定预估容量，如在分页查询时，每页100条数据，即可声明List list = new ArrayList(100)。

多线程编程

禁止自己new Thread()创建线程。
必须使用线程池来实现多线程任务处理。
禁止向线程池中提交自定义的Runnable对象或Callable对象，必须为封装好的TraceRunnable或TraceCallable对象。
所有涉及到多线程的实现，包括ThreadLocal相关的代码，必须做代码review。

日志打印

必须使用@Slf4j做日志打印
禁止随意使用AOP的形式来做方法的开始和结束日志打印
必须在所有方法（controller、service）的入口打印关键入参（如果入参过大，考虑只打印能起到标志作用的入参）
禁止打印用户密码等敏感信息
必须在调用远程服务之后，打印远程服务的返回值（大型列表查询接口除外）
必须在catch异常捕获中打印error日志，如log.error(“xxx”,e)

使用封装好的工具

redis【hdd-cloud-redis】
全局唯一id生成【hdd-cloud-uid】
分布式锁【hdd-cloud-redis】
kafka【hdd-cloud-kafka】
多服务日志中打印相同请求的requestId【hdd-cloud-core】
多服务传递登录用户【hdd-cloud-core】
服务注册与发现、feign调用【hdd-cloud-rpc】
全局返回结果封装【hdd-cloud-rpc】
自定义异常以及异常统一处理【hdd-cloud-core/hdd-cloud-rpc】
数据库表实体增删改查代码生成【hdd-cloud-jdbc】

定时任务XXL-JOB

必须将定时任务外置到xxl-job

IDEA规约插件

https://blog.csdn.net/ju_/article/details/

插件安装

File --> Settings
打开设置界面，选择Plugins，在搜索框内输入alibaba，点击搜索
在这里插入图片描述
选择对应的插件，点击右边的Install

安装完成，重启IDEA。

插件使用

选中项目，右键就可以看到“编码规约扫描”，可以使用这个来扫描项目里的代码。
在这里插入图片描述

规约最低标准

扫描结果中，不允许出现“Blocker”级别的问题。

待定：登录TOKEN规则

意义：方便用户信息的链路传输
类型：字符串
长度：无固定长度
组成：base64(用户名+用户编号)

代码样例（用户名n=JohnWinstonLennon，用户编码c=U3）

SessionUser sessionUser = new SessionUser(); sessionUser.setN("JohnWinstonLennon"); sessionUser.setC("U3"); String token = Base64Util.encode(sessionUser); //结果token=eyJjIjoiVTkyODY1MjEzNjIwMyIsIm4iOiJKb2huV2luc3Rvbkxlbm5vbiJ9