|
|
@@ -0,0 +1,307 @@
|
|
|
+# 卫星应用软件研究室开发规范V2.0
|
|
|
+
|
|
|
+> 开发前请认真阅读本规范，严格遵循本规范进行开发。
|
|
|
+>
|
|
|
+> 本规范融合了公司编码规范和阿里最佳实践，要求所有项目组将本规范文件复制到项目根目录。
|
|
|
+
|
|
|
+## 第一部分：注释规范
|
|
|
+
|
|
|
+### 后端代码注释规范
|
|
|
+1. 类注释
|
|
|
+```java
|
|
|
+/*
|
|
|
+ * @类名: ${type_name}
|
|
|
+ * @描述: ${todo} 类的设计目的、功能及注意事项
|
|
|
+ * @版本: ${enclosing_type}
|
|
|
+ * @创建日期: ${date}${time}
|
|
|
+ * @作者: ${user}
|
|
|
+ * @JDK: 1.6
|
|
|
+ *
|
|
|
+ * @修改描述: ${todo} 请描述修改内容
|
|
|
+ * @版本: ${enclosing_type}
|
|
|
+ * @修改日期: ${date}${time}
|
|
|
+ * @修改人: ${user}
|
|
|
+ * @JDK: 1.6
|
|
|
+ */
|
|
|
+/*
|
|
|
+* 类的横向关系：${todo} 说明与其它类的关联、调用或依赖等关系。
|
|
|
+*/
|
|
|
+```
|
|
|
+2. 方法注释
|
|
|
+```java
|
|
|
+/*
|
|
|
+ * @描述: ${todo} 描述这个方法的功能、适用条件及注意事项
|
|
|
+ * @作者: ${user}
|
|
|
+ * @创建时间: ${date}${time}
|
|
|
+ *
|
|
|
+ * @修改描述: ${todo} 请描述修改内容
|
|
|
+ * @修改人: ${user}
|
|
|
+ * @修改时间: ${date}${time}
|
|
|
+ * ${tags}
|
|
|
+ * ${todo} 描述每个输入输出参数的作用、量化单位、值域、精度
|
|
|
+ */
|
|
|
+/*
|
|
|
+ * 处理逻辑：${todo} 给出核心方法的处理逻辑
|
|
|
+ * 线程安全设计：${todo} 如果该方法涉及多线程调用，需给出线程安全设计
|
|
|
+ * 异常处理设计：${todo} 给出异常处理设计的考虑及异常处理流程
|
|
|
+ *
|
|
|
+ */
|
|
|
+```
|
|
|
+
|
|
|
+### 前端代码注释规范
|
|
|
+
|
|
|
+1. HTML/CSS/JS文件注释
|
|
|
+```javascript
|
|
|
+/*
|
|
|
+ * @描述: 全局配置
|
|
|
+ * @版本: v1.0
|
|
|
+ * @创建日期: 2022年3月4日17:19:14
|
|
|
+ * @作者: XXX
|
|
|
+ */
|
|
|
+```
|
|
|
+```html
|
|
|
+<!--
|
|
|
+ * @描述: 星地资源管理软件布局文件，嵌套路由的第一级容器
|
|
|
+ * @版本: v1.0.0
|
|
|
+ * @创建日期: 2022年3月4日17:25:45
|
|
|
+ * @作者: XXX
|
|
|
+ -->
|
|
|
+```
|
|
|
+
|
|
|
+2. 方法注释
|
|
|
+```javascript
|
|
|
+/*
|
|
|
+ * @描述: 描述这个方法的功能、适用条件及注意事项
|
|
|
+ * @作者: XXXX
|
|
|
+ * @创建时间: 2022年3月9日11:43:11
|
|
|
+ * @参数：param1 描述
|
|
|
+ * param2 描述
|
|
|
+ */
|
|
|
+```
|
|
|
+## 第二部分：代码提交规范
|
|
|
+
|
|
|
+1. 【约定】主要分支作用说明：
|
|
|
+ > master：主分支，用于对外发布，可用于生产
|
|
|
+ > develop：开发分支，基于master,编码工作在此分支进行
|
|
|
+ > release：测试分支，基于develop,测试阶段测试及小问题修复在此进行，测试完成后，更新版本号，合并回develop
|
|
|
+ > feature：功能特征分支，基于develop分支,用于合作功能特性开发
|
|
|
+ > hotfix：热修复分支，基于master分支,紧急修复对外版本缺陷，修复后更新版本号，合并到master和develop
|
|
|
+
|
|
|
+1. 【强制】原则上完成一个完整功能并自测无异常后，方可检入代码，必须保证无编译报错
|
|
|
+
|
|
|
+1. 【强制】提交代码必须写注释，能够完整描述本次提交变更的内容
|
|
|
+ > 注释格式：**提交类型：提交标题+内容** （如：fix: 修复用户模块启动问题）
|
|
|
+
|
|
|
+ > 提交类型参考以下几种：
|
|
|
+ > - feat: 功能代码
|
|
|
+ > - fix: bug修复
|
|
|
+ > - docs: 文档修改
|
|
|
+ > - style: 代码格式修改；
|
|
|
+ > - refactor: 重构代码；
|
|
|
+ > - test: 测试代码相关；
|
|
|
+ > - log: 日志相关
|
|
|
+ > - db: 数据库相关
|
|
|
+ > - config: 配置相关
|
|
|
+ > - build/shell: 脚本、打包编译相关
|
|
|
+ > - other: 其他，如配置修改，完善等；
|
|
|
+
|
|
|
+## 第三部分：数据库规范
|
|
|
+
|
|
|
+目前项目主要使用MySQL8.0，各列项主要适用于MySQL相关规范。
|
|
|
+
|
|
|
+### 基础规范
|
|
|
+
|
|
|
+1. 【强制】使用InnoDB存储引擎
|
|
|
+
|
|
|
+ > InnoDB存储引擎是MySQL默认存储引擎，支持事务和行级锁，并发性能更好，CPU及内存缓存页优化使得资源利用率更高
|
|
|
+
|
|
|
+1. 【强制】MySQL8中，使用默认字符集utf8mb4，比较规则（collation）默认为utf8mb4_0900_ai_ci
|
|
|
+
|
|
|
+ > 万国码，无需转码，无乱码风险。utf8mb4向下兼容utf8，如果有字段需要存储emoji表情之类的，则字段或表必须设置成utf8mb4
|
|
|
+
|
|
|
+ > 比较规则（collation）默认为utf8mb4_0900_ai_ci，官方宣称有性能优化
|
|
|
+1. 【强制】MySQL8中，行格式为 DYNAMIC 或者 COMPRESSED 情况下，需要索引的字段(如主键)，最大字节不可超过3072byte。
|
|
|
+
|
|
|
+ > 注意utf8mb4格式的varchar的主键长度最大为3072/4=768
|
|
|
+
|
|
|
+ > 另外两种行格式，限制字节数768，utf8mb4格式下字段最长为767/4=191
|
|
|
+
|
|
|
+1. 【强制】数据表、数据字段必须加入中文注释
|
|
|
+
|
|
|
+ > 便于识别表和字段的用途
|
|
|
+ 类status型需指明主要值的含义，如”0-离线，1-在线”
|
|
|
+
|
|
|
+1. 【推荐】适度使用存储过程、视图，禁止使用触发器、事件
|
|
|
+
|
|
|
+
|
|
|
+1. 【强制】所有表都必须要显式指定主键
|
|
|
+
|
|
|
+1. 【强制】禁止数据库中存储图、文件等大数据
|
|
|
+
|
|
|
+> 大文件和照片存储在文件系统，数据库里存URI即可
|
|
|
+
|
|
|
+1. 【强制】数据库中不允许存储明文密码
|
|
|
+
|
|
|
+### 流程规范
|
|
|
+
|
|
|
+1. 【强制】数据库设计遵循流程：概念模型 --> 物理模型 --> 数据库
|
|
|
+
|
|
|
+ > 概念模型视情况是否必须，否则其他一切涉及数据库的修改，必须有对应的物理模型变更。
|
|
|
+
|
|
|
+### 命名规范
|
|
|
+1. 【强制】SQL语句中，所有表名小写，参考第5条。
|
|
|
+
|
|
|
+> 避免因为MySQL数据大小写敏感配置导致的影响，同时也是mysql的通用规范
|
|
|
+
|
|
|
+1. 【强制】库名、表名、字段名禁止超过32个字符。须见名知意
|
|
|
+
|
|
|
+1. 【强制】临时库、表名必须以tmp为前缀，并以日期为后缀
|
|
|
+
|
|
|
+1. 【强制】备份库、表必须以bak为前缀，并以日期为后缀
|
|
|
+
|
|
|
+1. 【强制】库名、表名、字段名：小写字母，下划线风格，禁止数字开头，禁止两个下划线中间只出现数字，禁止复数名词。
|
|
|
+
|
|
|
+ > 正例：getter_admin，task_config，level3_name 反例：GetterAdmin，taskConfig，level_3_name
|
|
|
+
|
|
|
+1. 【强制】库名、表名、字段名禁止使用MySQL保留字，为避免与保留字冲突，单个单词应加下滑线后缀
|
|
|
+
|
|
|
+ > 正例：type_ 反例：type
|
|
|
+
|
|
|
+### 索引规范
|
|
|
+
|
|
|
+1. 【强制】索引命名：主键索引名为pk_字段名；唯一索引名为uk_字段名；普通索引名则为idx_字段名。
|
|
|
+ > 说明：pk_ 即primary key；uk_ 即 unique key；idx_ 即index的简称。
|
|
|
+ 主要的几种索引类型：
|
|
|
+ 普通索引、唯一索引、主键索引、组合索引、全文索引
|
|
|
+
|
|
|
+1. 【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。
|
|
|
+
|
|
|
+2. 【强制】作为查询条件的字段，一律需要建立索引。
|
|
|
+
|
|
|
+### SQL设计
|
|
|
+
|
|
|
+1. 【推荐】避免直接 SELECT * 读取全部字段
|
|
|
+ > 减少网络带宽消耗，能有效利用覆盖索引，表结构变更对程序基本无影响
|
|
|
+
|
|
|
+ > Mybatis中通过使用\<sql\>标签减少重复的sql语句
|
|
|
+
|
|
|
+1. 【强制】代码中书写的SQL语句要求SQL关键字全部大写，表名和字段名小写
|
|
|
+
|
|
|
+
|
|
|
+## 第四部分：后端开发规范
|
|
|
+
|
|
|
+### 命名规范
|
|
|
+
|
|
|
+1. 包命名规范
|
|
|
+ * 【强制】按公司域名，系统，子系统[服务/模块]方式命名， 如：*com.c503.oms.service.xxx*
|
|
|
+ * 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用**单数形式**，但是类名如果有复数含义，类名可以使用复数形式
|
|
|
+
|
|
|
+1. 代码命名规范
|
|
|
+
|
|
|
+ * 【强制】 boolean 类型变量，采取有意义的命名，如：isOpen，禁止使用如flag类的无意义名称
|
|
|
+
|
|
|
+1. 分层规范
|
|
|
+ * 【约定】在子服务下，业务模块一般包含以下几层
|
|
|
+ > * domain：POJO层，定义领域模型,包含DO、DTO、VO、Query等
|
|
|
+ > * mapper：数据访问层，与底层 MySQL、Oracle、Hbase 等进行数据交互。
|
|
|
+ > * service：相对具体的业务逻辑服务层。
|
|
|
+ > * controller：主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。
|
|
|
+ > * rpc：内部接口层，可直接封装 Service 方法暴露接口，提供其他服务调用
|
|
|
+ > * util：工具类
|
|
|
+ > * constant：常量类
|
|
|
+
|
|
|
+1. 配置文件规范
|
|
|
+ * 【推荐】项目配置文件，一般采用YAML语法格式
|
|
|
+ * 【强制】项目动态配置内容，配置文件必须存放于配置中心
|
|
|
+ > 配置中心文件命名规则：**c503-模块-环境标识(Profile).yml**
|
|
|
+ 如：*oms-system-dev.yml*
|
|
|
+ * 【强制】项目普通配置，配置文件文件统一规划在 src/main/resources目录下，按照配置文件类型可以划分为以下几种
|
|
|
+ > mappings/service/应用名：Mybatis的Mapper文件
|
|
|
+ application.yml：应用配置
|
|
|
+ bootstrap.yml：应用引导相关配置
|
|
|
+ logback-spring.xml：logback配置
|
|
|
+
|
|
|
+
|
|
|
+### 基础要求
|
|
|
+
|
|
|
+1. 【强制】应用服务内部用实体DO，服务与服务之间的调用使用Dto，前后端交互使用Vo
|
|
|
+
|
|
|
+1. 【强制】所有接口必须有返回内容，不可使用void
|
|
|
+
|
|
|
+ > 考虑接口失败场景
|
|
|
+
|
|
|
+1. 【强制】Controller层做参数格式的转换，不允许把json，map这类对象传到services去，也不允许services返回json、map
|
|
|
+
|
|
|
+ > 增强可读性，也尽力避免参数字段使用json格式
|
|
|
+
|
|
|
+1. 【注意】使用@ApiModelProperty注解的字段，类型如果为数字类型，需要设置example内容
|
|
|
+
|
|
|
+ > 如：@ApiModelProperty(value="年龄", example = "1")
|
|
|
+
|
|
|
+### RPC层接口规范
|
|
|
+
|
|
|
+1. 【强制】保证接口无状态，避免直接从上下文获取当前用户等情况
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+## 第五部分：Redis缓存规范
|
|
|
+
|
|
|
+### 键值设计
|
|
|
+
|
|
|
+#### key名设计
|
|
|
+
|
|
|
+1. 【强制】可读性和可管理性，Redis的key定义为多个具有独立意义的字符串由冒号“:”拼接而成
|
|
|
+
|
|
|
+> 例：应用名:表名/实体名:id:其他 —— `info:satellite:1:name`
|
|
|
+
|
|
|
+1. 【推荐】hash存储，field的命令方式：标识名称:唯一性标识
|
|
|
+
|
|
|
+1. 【推荐】保证语义的前提下，控制key的长度
|
|
|
+ > 当key较多时，内存占用也不容忽视，例如：
|
|
|
+`user:{uid}:friends:messages:{mid}`可简化为`u:{uid}:fr:m:{mid}`
|
|
|
+
|
|
|
+1. 【强制】: 不要包含特殊字符
|
|
|
+
|
|
|
+ > 反例：包含空格、换行、单双引号以及其他转义字符
|
|
|
+
|
|
|
+#### value设计
|
|
|
+
|
|
|
+1. 【强制】:拒绝bigkey
|
|
|
+
|
|
|
+ > string类型控制在10KB以内，hash、list、set、zset元素个数不要超过5000
|
|
|
+
|
|
|
+### 使用规范
|
|
|
+1. 【推荐】：控制key的生命周期，业务相关数据必须设置TTL
|
|
|
+ > 使用expire设置过期时间(条件允许可以打散过期时间，防止集中过期)，不过期的数据重点关注idletime
|
|
|
+ object idletime命令，通过系统当前时间-lru时间，得到键多久没有被访问的秒数。
|
|
|
+
|
|
|
+1. 【推荐】避免多个应用使用一个Redis实例
|
|
|
+
|
|
|
+> 正例：不相干的业务拆分，通过内部服务调用获取数据
|
|
|
+
|
|
|
+1. 【强制】禁止操作非当前业务模块的缓存数据
|
|
|
+
|
|
|
+1. 【推荐】设置合理的密码，如有必要可以使用SSL加密访问
|
|
|
+
|
|
|
+## 第六部分：日志规范
|
|
|
+
|
|
|
+1. 【强制】Logger的获取方式两种：
|
|
|
+ > - 类使用 @Slf4j 注解
|
|
|
+ > - 使用slf4j提供的Logger，LoggerFactory类，如：
|
|
|
+ private static final Logger logger = LoggerFactory.getLogger(UserService.class);
|
|
|
+
|
|
|
+1. 【强制】业务关键环节必须打印日志
|
|
|
+
|
|
|
+1. 【推荐】大部分日志在service中打印
|
|
|
+
|
|
|
+ > controller层的接口调用日志AOP会打印
|
|
|
+
|
|
|
+1. 【强制】error级别以上的日志，必须记录关键业务信息，如方法的入参，错误发生时的变量现场，以便回溯追踪问题
|
|
|
+
|
|
|
+1. 【强制】禁止打印密码等敏感信息
|
|
|
+
|
|
|
+1. 【强制】禁止使用 `e.printStackTrace();`
|
|
|
+
|
|
|
+ > 使用 `log.warn/error("xxxxx",e);`
|
|
|
+
|
|
|
+
|
hyx
5 місяців тому