Daizc
count.articles42
count.tags21
count.categories3
研发编码规范

研发编码规范

研发编码规范

产品-应用关系描述

  • 产品是进行缺陷管理需求管理的最小单位
    • 按照业务线作区分
  • 应用是进行代码开发的最小单位
    • 一个应用对应一个代码仓库

产品与应用为一对多的关系,即一个产品有多个应用。

产品具有以下基本属性

  • displayName 显示名称(中文名称,仅做显示之用)
  • name 英文全称
  • perfix 前缀(5个字符以内)

应用具有以下基本属性

  • displayName 显示名称(中文名称,仅做显示之用)
  • name 英文全称(默认为Maven工件Id)
  • simpleName 简短名称(14个字符以内)

命名规则

项目命名规则

  1. Maven项目名:(由脚手架自动生成)

    • 项目名(artifactId)统一使用小写,以中划线-作为分隔符
    • API模块的artifactId应该以-api结尾
    • 应用模块如果与API包在同一个仓库中,则artifactId应以’-biz’结尾。
    • 应用模块位于单独的代码仓库中,则artifactId无需添加后缀。
  2. Java单体项目名规则: <语言>-<业务名称>-<项目类型>

    • 语言
      • java
      • php
      • node
    • 业务名称
      • auth
      • product
      • resource-center
    • 项目类型
      • cloud
      • boot
        1
        2
        3
        4
        5
        6
        7
        8
        9

        单体项目
        java-xxxxx-cloud
        java-xxxxx-cloud-api

        聚合项目
        ng-xxxxx
        |- ng-xxxxx-api
        |- ng-xxxxx-biz
  3. Maven GroupId必须满足以下正则表达式

    • ^com.kailin.*

类命名规则

功能 后缀 例子 备注
表名 - user_detail 表名仅做建议,根据业务可自行添加前缀后缀
复合实体 - UserDetail 简单CRUD场景下,用于代替领域对象、数据对象的功能
无法替代DTO和VO
领域对象 Domian UserDetailDomain 胖实体,拥有业务上的方法,无法从数据库直接得到,

简单CRUD无需领域对象/复合实体的,可与DO混用
数据对象 DO UserDetailDO 从数据库中直接查询得到的对象,一般会类上存在ORM相关的注解

简单CRUD场景下可用复合实体/领域对象代替
数据传输对象 DTO UserDetailDTO 一般是放在Api包中提供出去
用与前端展示的POJO类 VO UserDetailVO -
数据库映射接口 Mapper UserMapper Mybatis用
数据库映射接口 Repository UserRepository JPA用
数据Service接口 IService UserDetailIService 使用MybatisPlus时,用于区分业务Service数据Service
数据Service实现 IServiceImpl UserDetailIServiceImpl -
Service接口 Service UserDetailService 真实提供业务的Service接口
Service实现 ServiceImpl UserDetailServiceImpl -
web接口 Controller UserDetailController -
web接口入参 Param UserDetailParam 执行特定业务时所需的入参
web接口查询复合参数 Query UserDetailQuery 【仅建议】执行特定查询时所用的查询参数
工具类 Utils DateUtils 一个工具类是一个工具集,因此用复数
自己编写工具类之前先看看项目内已引入工具能不能满足需求
使用优先顺序为 commons.lang3 > hutool > spring > 自己编写
常量类 Constants UserTypeConstants 一个常量类中含有多个常量,因此用复数
枚举类 Enum UserTypeEnum 枚举不是一个集合,而是一个类型定义,

数据访问层命名规则

接口方法规范(参照JPA规范)
  • 使用getfindliststreamupdatesavedelete作为前缀
  • 使用ByOrderByGroupBy作为谓词
  • 方法命名规则: <前缀><实体名or字段名><谓词1><字段名1><谓词2><字段名2>
  • 当查询结果为实体时,实体名可省略:
    • getUserById()省略实体名为getById()
  • 当查询结果为实体的派生对象时时,实体名可省略为后缀:
    • getUserVOById()省略实体名为getVOById()
  • 当查询结果为字段名或者特定对象时,不可省略
    • getPasswordById()无法省略
    • getLoginSlatAndPasswordById()无法省略
前缀规范
  1. 获取单个对象的方法用 get 做前缀时,返回T或者null
    • 如: UserDetailDO getUserDetailById();
  2. 【推荐】获取单个对象的方法用 find 做前缀时,返回Optional<T>
    • 如: Optional<UserDetailDO> findUserDetailByName()
    • 如: Optional<UserDetailDO> findUserDetailByName()
  3. 获取多个对象的方法用 list 做前缀时,实体采用复数结尾,返回<? extend Collection><T>即Collection的子类
    • 如: List<UserDetailDO> list()(省略对象名)。
    • 如: List<UserDetailDO> listUserDetails()
    • 如: Set<UserDetailDO> listUserDetailsByCreateTime(Date createTime)
    • 如: Queue<UserDetailDO> listUserDetailsByAge(Long age)
  4. 【推荐】获取多个对象的方法用 stream 做前缀时,实体采用复数结尾,返回Stream<T>
    • 如: Stream<UserDetail> stream()(省略对象名)。
    • 如: Stream<UserDetail> streamUserDetails()
  5. 分页查询对象的方法用 page 做前缀,复数结尾。
    • 如: Page<UserDetail> pageUserDetails(PageParam param)
  6. 统计总数的方法用 count 做前缀。
    • 如: Long countByAge(Long age)
  7. 插入的方法用 save 做前缀。 返回保存的实体.
    • 如: UserDetailDO save(UserDetailDO saveDO)
  8. 删除的方法用 delete 做前缀。返回受影响行数。
    • 如: Long deleteById(String id)
  9. 修改的方法用 update 做前缀。批量修改时返回受影响行数,单个值修改时返回修改后实体。
    • 如: UserDetailDO|Long updateById(UserDetailDO updateDO)
    • 如: Long updateByCreateTime(UserDetailDO updateDO,Date createTime)
  10. 执行特定操作的方法使用其操作名做前缀。如: sendSms 发送短信,noticeUser 通知用户,uploadPic 上传图片,downloadFile 下载文件

数据库命名规则

  1. 数据库库名命名规则:<产品前缀>_<应用简称>命名
    • ng_kboss_auth,其中ng_kboss为产品前缀,auth为应用简称。
    • hneduexam应修改为hn_edu_exam,其中hn_edu为产品前缀,exam为应用简称。
  2. 表名和字段名均采用小写,以下划线分隔,如collection_accountedu_report_operate_loss_record
  3. 如果手动建索引,名称需要使用idx_<表名/表名首字母简写>_<字段名>的模式
  4. 数据库中遇到时间字段,需要使用datetime(3)类型,否则会查询时会存在舍入问题
  5. 请注意:业务状态字段和软删除字段需要分离,即is_delete字段不能进行业务控制
  6. 公共命名规范如下表
    字段名 类型 空/默认值 描述 备注
    is_delete tinyint(4) DEFAULT ‘0’ 软删除字段(0 未删除 1 已删除) -
    create_time datetime(3) DEFAULT CURRENT_TIMESTAMP 创建时间 -
    update_time datetime(3) DEFAULT CURRENT_TIMESTAMP
    ON UPDATE CURRENT_TIMESTAMP
    更新时间 -
    create_user_id varchar(32) DEFAULT NULL 创建者id 非必需,视业务而定
    create_user_name varchar(255) DEFAULT NULL 创建者名称 非必需,视业务而定
    update_user_id varchar(32) DEFAULT NULL 修改者id 非必需,视业务而定
    update_user_name varchar(255) DEFAULT NULL 修改者名称 非必需,视业务而定

编码规则

  1. 尽量避免使用java.sql.Date,应使用java.util.Date

  2. 尽量避免止将SimpleDateFormat等线程不安全的类定义为静态变量。如果定义为 static,必须加锁。

代码开发以及分支规范

分支类型

  • 主分支,唯一主分支为master
  • 功能分支,实际进行开发时,开发人员实际编写的分支,以feature/<功能名称>命名
  • 热修复分支,从某个发布分支迁出,完成修复后合并回发布分支和主分支,以hotfix/<release分支版本号>/<需要修复的功能>命名

版本命名规则

命名规则
Maven工件 Artifact Version <框架版本>/<功能版本>/<修订版本>
  • 框架版本: 框架变更时+1
  • 功能版本: 功能迭代时+1 (累加,不清零)
  • 修订版本: 修复BUG时+1 (累加,不清零)
功能分支 Branch Name feature/<Feature Name>-<Date yyyyMMdd>
测试分支 Branch Name test/<Date yyyyMMdd>/<Feature A>/<Feature B>
热发布分支 Branch Name hotfix/<Feature A>/
发布标签(单体项目) Release Tag <Artifact Version>
发布标签(聚合项目) Release Tag <Artifact Name>/<Artifact Version>

分支流程介绍

1
2
3
4
5
6
7
8
9
10
11
12
flowchart TB
subgraph multi[单功能开发分支流程]
direction LR
s_dev(开发)
s_feature_test(测试)
s_dev -.-> s_feature_test
s_dev --> s_pre
s_pre(预发\nmaster分支)
s_pre_test(预发布测试)
s_prod(发布\n产品验收\n打ReleaseTag)
s_pre --> s_pre_test --> s_prod
end
1
2
3
4
5
6
7
8
9
10
11
12
13
flowchart TB
subgraph multi[多功能开发分支流程]
direction LR
m_fa(开发A功能\nfeature分支)
m_fb(开发B功能\nfeature分支)

m_fa -.-> test
m_fb -.-> test(功能测试\ntest分支)

m_fa --> m_pre_a(预发A功能\nmaster分支) --> m_pord_a(发布\n打ReleaseTag)

m_fb --> m_pre_b(预发B功能\nmaster分支) --> m_pord_b(发布\n打ReleaseTag)
end

分支介绍

分支类型:

  • 主分支,唯一主分支为master
  • 功能分支,实际进行开发时,开发人员实际编写的分支,以feature/<功能名称>命名
  • *测试分支,所有含有test/前缀的分支都为测试分支,以test/<对应功能分支的名称>命名
主分支 master

对应环境:

  • 预发布环境-pre
  • *生产环境-prod

生命周期:

  • 永久有效

分支特征:

  • 该分支受到保护,无法直接通过push提交代码,仅仅可通过合并PullRequest更新
  • 该分支的代码一定是 可用的 代码,随时随地都可以通过流水线完成构建
  • 线上的应用一定是通过主分支打包得到的
  • 主分支上的代码不一定与线上代码一致
  • 开发人员无需在本地建立同名分支以跟踪master
(可选)公共测试分支 test

建议命名规范: test\<Date yyyyMMdd>\<功能名称A>\<功能名称B>

对应环境:

  • 测试环境-test (功能测试-多分支)

生命周期:

  • 当多个功能需要并行进行测试时,从任一feature分支中迁出,并merge所有需要测试的分支
  • 当功能均测试完成或仅剩一个功能后,可以删除此分支

分支特征:

  • 该分支用于支持同一项目同时开发、测试多个新功能
  • 同一个项目串行进行开发任务时,此分支无需存在,直接由feature分支代替本分支功能
  • 由于pre测试并不在本分支上运行,所以pre环境做出的改动不会应用到本分支上,本分支的代码不一定准确,非必要不使用本分支做测试
  • 该分支仅进行功能测试
  • 该分支禁止反向合并到其他任何分支
功能分支 feature/<功能名称>-<Date yyyyMMdd>

对应环境:

  • 开发环境-dev
  • 测试环境-test (功能测试-单分支)

生命周期:

  • 当开发人员接到开发任务并完成任务拆解后,根据具体的任务创建功能分支
  • 当该功能完成发布,顺利上线并创建release分支后,该功能分支应该被删除

分支特征:

  • 该分支必须只能master分支签出
  • 该分支的代码一定是 最新的 代码,由开发人员自行开发和维护
  • 使用该分支的开发人员必须上班前下班前master拉取并合并代码
  • 拉取master发生代码冲突时,如非特意更改,应以master分支代码为准
  • 当测试人员使用此分支进行功能测试
热发布分支 hotfix/<release分支版本号>/<需要修复的功能>

对应环境:

  • 生产环境-prod

生命周期:

  • 当生产环境出现bug时,由开发人员从对应的Release Tag中签出
  • 当该bug修复完成后:
    • 移动签出的Release Tag到当前分支
    • 将该分支并入master分支中
    • 删除热发布分支

分支特征:

  • 该分支由开发人员新建,只能从对应的Release Tag中签出
  • 该分支的代码一定是 准确的 可用于生产的 代码,可以随时进行打包上线
  • 该分支应始终落后或等同master分支

分支管理 GitGraph

图例

  • 方块形状节点: 测试提测节点
  • 中空圆形节点: 由merge产生的commit节点
  • 被标签标记的节点: 实际生产上线的节点

最简流程

同时仅有一个功能进行开发时的最简流程,无需test分支,且无pre环境。

%%{init: { 'logLevel': 'debug', 'theme': 'base' ,'startOnLoad': true } }%% gitGraph commit branch feature-a commit commit type:HIGHLIGHT commit type:HIGHLIGHT checkout main merge feature-a commit tag:"release-A"

Hotfix流程

生产上线后出现重大Bug需要进行线上修复的流程。

1
2
3
4
5
6
7
8
9
10
11
%%{init: { 'logLevel': 'debug', 'theme': 'base' ,'startOnLoad': true } }%%
gitGraph
commit tag:"release-A"
branch hotfix
commit
commit tag:"release-A-2"
checkout main
commit tag:"release-B"
commit tag:"release-C"
commit
merge hotfix

多功能并行开发流程

同时有多个功能进行并行开发时的的复杂管理流程,需要借助一个不可信的临时test分支同时进行多个功能的测试。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
%%{init: { 'logLevel': 'debug', 'theme': 'base' ,'startOnLoad': true } }%%
gitGraph
commit
branch feature-b
branch feature-a
commit
commit
checkout feature-b
commit
commit
branch test
merge feature-a
commit type:HIGHLIGHT
checkout feature-a
commit
commit
checkout test
merge feature-a
checkout main
merge feature-a
commit id:"pre-A-a123" type:HIGHLIGHT
checkout feature-a
commit
checkout main
merge feature-a
commit id:"pre-A-a124" type:HIGHLIGHT
commit tag:"release-A"
merge feature-b
commit id:"pre-B-a125" type:HIGHLIGHT
commit tag:"release-B"

copyright.author:Daizc
copyright.permalink:https://note.bequick.run/%E7%A0%94%E5%8F%91%E7%BC%96%E7%A0%81%E8%A7%84%E8%8C%83-2022%E5%B9%B44%E6%9C%8813%E6%97%A5/
版权声明:本文采用 CC BY-NC-SA 3.0 CN 协议进行许可
×