# 卫星应用软件研究室开发规范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 ``` 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语句 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);`