Home Explore Help
Register Sign In
huyx
/
cadv
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: develop
Branches Tags
cadv
/
卫星应用软件研究室开发规范.md

卫星应用软件研究室开发规范.md 11 KB
Permalink History Raw

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

开发前请认真阅读本规范，严格遵循本规范进行开发。

本规范融合了公司编码规范和阿里最佳实践，要求所有项目组将本规范文件复制到项目根目录。

第一部分：注释规范

后端代码注释规范

  1. 类注释

    /*
* @类名: ${type_name}
* @描述: ${todo} 类的设计目的、功能及注意事项
* @版本: ${enclosing_type}
* @创建日期: ${date}${time}
* @作者: ${user}
* @JDK: 1.6
* 
* @修改描述: ${todo} 请描述修改内容
* @版本: ${enclosing_type}
* @修改日期: ${date}${time}
* @修改人: ${user}
* @JDK: 1.6
*/
/*
* 类的横向关系：${todo} 说明与其它类的关联、调用或依赖等关系。
*/

  2. 方法注释

    /*
* @描述: ${todo} 描述这个方法的功能、适用条件及注意事项
* @作者: ${user}
* @创建时间: ${date}${time}
* 
* @修改描述: ${todo} 请描述修改内容
* @修改人: ${user}
* @修改时间: ${date}${time}
* ${tags}
*  ${todo} 描述每个输入输出参数的作用、量化单位、值域、精度
*/
/*
* 处理逻辑：${todo} 给出核心方法的处理逻辑
* 线程安全设计：${todo} 如果该方法涉及多线程调用，需给出线程安全设计
* 异常处理设计：${todo} 给出异常处理设计的考虑及异常处理流程
* 
*/

前端代码注释规范

  1. HTML/CSS/JS文件注释

    /*
* @描述: 全局配置
* @版本: v1.0
* @创建日期: 2022年3月4日17:19:14
* @作者: XXX
*/

    <!--
* @描述: 星地资源管理软件布局文件，嵌套路由的第一级容器
* @版本: v1.0.0
* @创建日期: 2022年3月4日17:25:45
* @作者: XXX
-->

  2. 方法注释

    /*
* @描述: 描述这个方法的功能、适用条件及注意事项
* @作者: XXXX
* @创建时间: 2022年3月9日11:43:11
* @参数：param1 描述
* 		 param2 描述
*/

    第二部分：代码提交规范

  3. 【约定】主要分支作用说明：

    master：主分支，用于对外发布，可用于生产 develop：开发分支，基于master,编码工作在此分支进行 release：测试分支，基于develop,测试阶段测试及小问题修复在此进行，测试完成后，更新版本号，合并回develop feature：功能特征分支，基于develop分支,用于合作功能特性开发 hotfix：热修复分支，基于master分支,紧急修复对外版本缺陷，修复后更新版本号，合并到master和develop

  4. 【强制】原则上完成一个完整功能并自测无异常后，方可检入代码，必须保证无编译报错

  5. 【强制】提交代码必须写注释，能够完整描述本次提交变更的内容

    注释格式：提交类型：提交标题+内容 （如：fix: 修复用户模块启动问题）

    提交类型参考以下几种：

    • feat: 功能代码
    • fix: bug修复
    • docs: 文档修改
    • style: 代码格式修改；
    • refactor: 重构代码；
    • test: 测试代码相关；
    • log: 日志相关
    • db: 数据库相关
    • config: 配置相关
    • build/shell: 脚本、打包编译相关
    • other: 其他，如配置修改，完善等；

第三部分：数据库规范

目前项目主要使用MySQL8.0，各列项主要适用于MySQL相关规范。

基础规范

  1. 【强制】使用InnoDB存储引擎

    InnoDB存储引擎是MySQL默认存储引擎，支持事务和行级锁，并发性能更好，CPU及内存缓存页优化使得资源利用率更高

  2. 【强制】MySQL8中，使用默认字符集utf8mb4，比较规则（collation）默认为utf8mb4_0900_ai_ci

    万国码，无需转码，无乱码风险。utf8mb4向下兼容utf8，如果有字段需要存储emoji表情之类的，则字段或表必须设置成utf8mb4

    比较规则（collation）默认为utf8mb4_0900_ai_ci，官方宣称有性能优化

  3. 【强制】MySQL8中，行格式为 DYNAMIC 或者 COMPRESSED 情况下，需要索引的字段(如主键)，最大字节不可超过3072byte。

    注意utf8mb4格式的varchar的主键长度最大为3072/4=768

    另外两种行格式，限制字节数768，utf8mb4格式下字段最长为767/4=191

  4. 【强制】数据表、数据字段必须加入中文注释

    便于识别表和字段的用途
    类status型需指明主要值的含义，如”0-离线，1-在线”

  5. 【推荐】适度使用存储过程、视图，禁止使用触发器、事件

  6. 【强制】所有表都必须要显式指定主键

  7. 【强制】禁止数据库中存储图、文件等大数据

大文件和照片存储在文件系统，数据库里存URI即可

  1. 【强制】数据库中不允许存储明文密码

流程规范

  1. 【强制】数据库设计遵循流程：概念模型 --> 物理模型 --> 数据库

    概念模型视情况是否必须，否则其他一切涉及数据库的修改，必须有对应的物理模型变更。

命名规范

  1. 【强制】SQL语句中，所有表名小写，参考第5条。

避免因为MySQL数据大小写敏感配置导致的影响，同时也是mysql的通用规范

  1. 【强制】库名、表名、字段名禁止超过32个字符。须见名知意

  2. 【强制】临时库、表名必须以tmp为前缀，并以日期为后缀

  3. 【强制】备份库、表必须以bak为前缀，并以日期为后缀

  4. 【强制】库名、表名、字段名：小写字母，下划线风格，禁止数字开头，禁止两个下划线中间只出现数字，禁止复数名词。

    正例：getter_admin，task_config，level3_name 反例：GetterAdmin，taskConfig，level_3_name

  5. 【强制】库名、表名、字段名禁止使用MySQL保留字，为避免与保留字冲突，单个单词应加下滑线后缀

    正例：type_ 反例：type

索引规范

  1. 【强制】索引命名：主键索引名为pk_字段名；唯一索引名为uk_字段名；普通索引名则为idx_字段名。

    说明：pk_ 即primary key；uk_ 即 unique key；idx_ 即index的简称。 主要的几种索引类型：
    普通索引、唯一索引、主键索引、组合索引、全文索引

  2. 【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。

  3. 【强制】作为查询条件的字段，一律需要建立索引。

SQL设计

  1. 【推荐】避免直接 SELECT * 读取全部字段

    减少网络带宽消耗，能有效利用覆盖索引，表结构变更对程序基本无影响

    Mybatis中通过使用<sql>标签减少重复的sql语句

  2. 【强制】代码中书写的SQL语句要求SQL关键字全部大写，表名和字段名小写

第四部分：后端开发规范

命名规范

  1. 包命名规范

    • 【强制】按公司域名，系统，子系统[服务/模块]方式命名， 如：com.c503.oms.service.xxx
    • 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式

  2. 代码命名规范

    • 【强制】 boolean 类型变量，采取有意义的命名，如：isOpen，禁止使用如flag类的无意义名称

  3. 分层规范

    • 【约定】在子服务下，业务模块一般包含以下几层 > * domain：POJO层，定义领域模型,包含DO、DTO、VO、Query等
      > * mapper：数据访问层，与底层 MySQL、Oracle、Hbase 等进行数据交互。 > * service：相对具体的业务逻辑服务层。 > * controller：主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。 > * rpc：内部接口层，可直接封装 Service 方法暴露接口，提供其他服务调用 > * util：工具类
      > * constant：常量类

  4. 配置文件规范

    • 【推荐】项目配置文件，一般采用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

  2. 【强制】所有接口必须有返回内容，不可使用void

    考虑接口失败场景

  3. 【强制】Controller层做参数格式的转换，不允许把json，map这类对象传到services去，也不允许services返回json、map

    增强可读性，也尽力避免参数字段使用json格式

  4. 【注意】使用@ApiModelProperty注解的字段，类型如果为数字类型，需要设置example内容

    如：@ApiModelProperty(value="年龄", example = "1")

RPC层接口规范

  1. 【强制】保证接口无状态，避免直接从上下文获取当前用户等情况

第五部分：Redis缓存规范

键值设计

key名设计

  1. 【强制】可读性和可管理性，Redis的key定义为多个具有独立意义的字符串由冒号“:”拼接而成

例：应用名:表名/实体名:id:其他 —— info:satellite:1:name

  1. 【推荐】hash存储，field的命令方式：标识名称:唯一性标识

  2. 【推荐】保证语义的前提下，控制key的长度

    当key较多时，内存占用也不容忽视，例如： user:{uid}:friends:messages:{mid}可简化为u:{uid}:fr:m:{mid}

  3. 【强制】: 不要包含特殊字符

    反例：包含空格、换行、单双引号以及其他转义字符

value设计

  1. 【强制】:拒绝bigkey

    string类型控制在10KB以内，hash、list、set、zset元素个数不要超过5000

使用规范

  1. 【推荐】：控制key的生命周期，业务相关数据必须设置TTL

    使用expire设置过期时间(条件允许可以打散过期时间，防止集中过期)，不过期的数据重点关注idletime
    object idletime命令，通过系统当前时间-lru时间，得到键多久没有被访问的秒数。

  2. 【推荐】避免多个应用使用一个Redis实例

正例：不相干的业务拆分，通过内部服务调用获取数据

  1. 【强制】禁止操作非当前业务模块的缓存数据

  2. 【推荐】设置合理的密码，如有必要可以使用SSL加密访问

第六部分：日志规范

  1. 【强制】Logger的获取方式两种：

    • 类使用 @Slf4j 注解
    • 使用slf4j提供的Logger，LoggerFactory类，如：
      private static final Logger logger = LoggerFactory.getLogger(UserService.class);

  2. 【强制】业务关键环节必须打印日志

  3. 【推荐】大部分日志在service中打印

    controller层的接口调用日志AOP会打印

  4. 【强制】error级别以上的日志，必须记录关键业务信息，如方法的入参，错误发生时的变量现场，以便回溯追踪问题

  5. 【强制】禁止打印密码等敏感信息

  6. 【强制】禁止使用 e.printStackTrace();

    使用 log.warn/error("xxxxx",e);