init

卫星应用软件研究室开发规范.md

@@ -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);`
+
+