整理最全规范之Git仓库管理规范，Java开发规范，最全Java命名规范，数据库开发设计规范，接口设计规范
Posted 爱是与世界平行
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了整理最全规范之Git仓库管理规范，Java开发规范，最全Java命名规范，数据库开发设计规范，接口设计规范相关的知识，希望对你有一定的参考价值。
一、代码仓库创建规范
1、 项目创建需符合Group规范。
2、 创建项目必须添加Project description说明。
3、 每个项目都需要README.md文件。
4、 除文档说明类型仓库，所有代码仓库都需要.gitignore。
注：有模板的项目，要以统一的模板创建项目
1.1 README文件规范
README文件结构如下：
<项目简介/Introduction>
<快速使用/Quick start>
<文档说明/Documentation>
Introduction用于阐述项目基本情况和功能（是什么，用来做什么的）。Quick Start主要包括两部分内容：简易的安装部署说明(Deployment)和使用案例(Example)。Documentation部分是核心的文档，对于大型项目可以使用超链接代替。
参考：
1.2 版本管理规范
项目代码release包括三类：
- 大版本(x.0.0)
- 小版本(x.x.0)
- 补丁(x.x.x)
1.3 Git Commit代码提交规范
1.3.1 commit message格式
git commit 提交样式规范：
:
注意：冒号后面又空格
<类型>: <标题>
<空一行>
<内容>
1.3.2 格式说明
1. <类型>
用于说明 commit 的类别(type)，只允许使用下面7个标识。
# 主要type
feat: 增加新功能
fix: 修复bug
# 特殊type
docs: 只改动了文档相关的内容
style: 不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
build: 构造工具的或者外部依赖的改动，例如webpack，npm
refactor: 代码重构时使用,重构（即不是新增功能，也不是修改bug的代码变动）
revert: 执行git revert打印的message
# 暂不使用type
test: 添加测试或者修改现有测试
perf: 提高性能的改动
ci: 与CI（持续集成服务）有关的改动
chore: 不修改src或者test的其余修改，例如构建过程或辅助工具的变动
当一次改动包括主要type与特殊type时，统一采用主要type。
2. <标题>
commit 目的的简短描述，不超过50个字符
3. <内容>
对本次 commit 的详细描述，可以分成多行，可详细说明代码变动的动机。
1.3.3 示例
feat(compiler): 题目 #10286
对本次 commit 的详细描述，可以分成多行，可详细说明代码变动的动机
1.4 分支管理规范（新增PR规范，目前阶段非必要）
1.4.1 远程仓库
1.4.1.1 分支约束
远程仓库只允许出现五种类型的分支：
- 主分支：项目的主要分支也就是master分支。用于正式发布，该分支禁止任何人直接提交，提交合并请求由对应项目主管人员确认合并。
- 开发分支：项目的开发迭代分支，用于开发发布，常规开发任务的代码直接提交至该分支或者由临时分支合并至该分支。
- 测试分支：项目的测试迭代分支，用户测试发布，该分支禁止任何人直接提交，提交合并请求由对应项目主管人员确认合并。
- 归档分支：项目的里程碑版本保留分支，由测试负责人、项目负责人、产品负责人直接定义版本，从测试分支归档出新分支。
- 临时分支：由项目的开发人员建立的临时分支，禁止交叉提交，谁建立的分支便由谁负责管理，用于合并至开发分支，合并完成之后禁止新提交应当立刻删除。
1.4.1.2 主分支
主分支全局仓库唯一，分支名称固定为master，任何对主分支的直接提交定性为严重违规行为，需要尝试对主分支进行合并应当由对应仓库的开发负责人提交合并请求并由上级负责人通过合并实现对主分支的变更。
1.4.1.3 开发分支
开发分支全局仓库唯一，分支名称固定为devLoop，开发人员允许对该分支直接提交，任何向开发分支提交的代码在提交之前应当保证能够正常通过编译、部署并运行，无法部署的提交应当立刻修复并重新提交。开发分支部署的代码应当由开发人员完成所有的单元测试，全部通过之后再向测试分支提交。
1.4.1.4 测试分支
测试分支全局仓库唯一，分支名称固定为testLooop，禁止直接对该分支提交，测试分支应当由开发分支提交合并请求而来，由开发人员提交合并请求，由主要开发人员通过合并请求实现测试部署。小型项目、中间件研发可以酌情省略测试分支，由开发分支部署交于测试进行质量校验，大型项目或产品必须保证有测试分支。
1.4.1.5 归档分支
归档分支全局仓管可以具备多个，直接由测试分支或主分支派生，除特殊情况下禁止任何提交行为，归档分支名称格式为release-版本号（如：release-1.2.0），分支由对应项目的开发主要负责人再与测试负责人沟通之后创建，已经后续无论是BUG、还是功能性问题都不应当项归档分支提交。
1.4.1.6 临时分支
临时分支全局仓库可以具备多个，临时分支名称格式为tem-开发者-创建时间（如：tem-tangyuecan-20200724），由开发人员自行创建，临时分支的提交进制交叉提交，只允许分支创建者提交，临时分支只能合并到开发分支一旦完成合并之后应当立即删除，可以直接本地合并之后向开发分支提交或者提交合并请求由开发负责人进行合并，临时分支的生命周期原则上不超过三个工作日。临时分支主要用于无法在短时间之内完成的开发工作，或者整合至开发分支之后无法运行情况，这样考虑之下才有临时分支的概念。
1.4.2 提交描述
所以代码的提交、合并都应该通过文字目前描述出改此提交、合并的目的如下面几种：
修复问题：#xxxx（禅道BUG的ID或者ISSUE）修复问题：xxxx（BUG的名称）完成功能：#xxxx（禅道的任务ID）完成功能：xxxxx（功能的名称）
任何无意义或者具体目的的提交禁止同步至远程仓库，包括远程临时分支（禁止commit）
1.4.3 合并流程
二、Java命名规范
2.1 Java中的命名规范
好的命名能体现出代码的特征，含义或者是用途，让阅读者可以根据名称的含义快速厘清程序的脉络。不同语言中采用的命名形式大相径庭，Java 中常用到的命名形式共有三种，既首字母大写的 UpperCamelCase ，首字母小写的 lowerCamelCase 以及全部大写的并用下划线分割单词的UPPER_CAMEL_UNSER_SCORE。通常约定，类一般采用大驼峰命名，方法和局部变量使用小驼峰命名，而大写下划线命名通常是常量和枚举中使用。
| 类型 | 约束 | 例 |
|---|---|---|
| 项目名 | 全部小写，多个单词用中划线分隔‘-’ | spring-cloud |
| 包名 | 全部小写 | com.alibaba.fastjson |
| 类名 | 单词首字母大写 | Feature, ParserConfig,DefaultFieldDeserializer |
| 变量名 | 首字母小写，多个单词组成时，除首个单词，其他单词首字母都要大写 | password, userName |
| 常量名 | 全部大写，多个单词，用’_'分隔 | CACHE_EXPIRED_TIME |
| 方法 | 同变量 | read(), readObject(), getById() |
2.2 包命名
包名统一使用小写，点分隔符之间有且仅有一个自然语义的英文单词或者多个单词自然连接到一块（如 springframework，deepspace 不需要使用任何分割）。包名统一使用单数形式，如果类命有复数含义，则可以使用复数形式。
包名的构成可以分为以下几四部分【前缀】 【发起者名】【项目名】【模块名】。常见的前缀可以分为以下几种：
| 前缀名 | 例 | 含义 |
|---|---|---|
| indi（或onem ） | indi.发起者名.项目名.模块名.…… | 个体项目，指个人发起，但非自己独自完成的项目，可公开或私有项目，copyright主要属于发起者。 |
| pers | pers.个人名.项目名.模块名.…… | 个人项目，指个人发起，独自完成，可分享的项目，copyright主要属于个人 |
| priv | priv.个人名.项目名.模块名.…… | 私有项目，指个人发起，独自完成，非公开的私人使用的项目，copyright属于个人。 |
| team | team.团队名.项目名.模块名.…… | 团队项目，指由团队发起，并由该团队开发的项目，copyright属于该团队所有 |
| 顶级域名 | com.公司名.项目名.模块名.…… | 公司项目，copyright由项目发起的公司所有 |
2.3 类命名
类名使用大驼峰命名形式，类命通常时名词或名词短语，接口名除了用名词和名词短语以外，还可以使用形容词或形容词短语，如 Cloneable，Callable 等，表示实现该接口的类有某种功能或能力。对于测试类则以它要测试的类开头，以 Test 结尾，如 HashMapTest。
对于一些特殊特有名词缩写也可以使用全大写命名，比如XMLHttpRequest，不过笔者认为缩写三个字母以内都大写，超过三个字母则按照要给单词算。这个没有标准如阿里巴巴中fastjson用JSONObject作为类命，而google则使用JsonObjectRequest 命名，对于这种特殊的缩写，原则是统一就好。
| 属性 | 约束 | 例 |
|---|---|---|
| 抽象类 | Abstract 或者 Base 开头 | BaseUserService |
| 枚举类 | Enum 作为后缀 | GenderEnum |
| 工具类 | Utils作为后缀 | StringUtils |
| 异常类 | Exception结尾 | RuntimeException |
| 接口实现类 | 接口名+ Impl | UserServiceImpl |
| 领域模型相关 | /DO/DTO/VO/DAO | 正例：UserDAO 反例： UserDo， UserDao |
| 设计模式相关类 | Builder，Factory等 | 当使用到设计模式时，需要使用对应的设计模式作为后缀，如ThreadFactory |
| 处理特定功能的 | Handler，Predicate, Validator | 表示处理器，校验器，断言，这些类工厂还有配套的方法名如handle，predicate，validate |
| 测试类 | Test结尾 | UserServiceTest， 表示用来测试UserService类的 |
| MVC分层 | Controller，Service，ServiceImpl，DAO后缀 | UserManageController，UserManageDAO |
2.4 方法
方法命名采用小驼峰的形式，首字小写，往后的每个单词首字母都要大写。 和类名不同的是，方法命名一般为动词或动词短语，与参数或参数名共同组成动宾短语，即动词 + 名词。一个好的函数名一般能通过名字直接获知该函数实现什么样的功能。
2.4.1 返回真伪值的方法
注：Prefix-前缀，Suffix-后缀，Alone-单独使用
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix | is | 对象是否符合期待的状态 | isValid |
| Prefix | can | 对象能否执行所期待的动作 | canRemove |
| Prefix | should | 调用方执行某个命令或方法是好还是不好,应不应该，或者说推荐还是不推荐 | shouldMigrate |
| Prefix | has | 对象是否持有所期待的数据和属性 | hasObservers |
| Prefix | needs | 调用方是否需要执行某个命令或方法 | needsMigrate |
2.4.2 用来检查的方法
| 单词 | 意义 | 例 |
|---|---|---|
| ensure | 检查是否为期待的状态，不是则抛出异常或返回error code | ensureCapacity |
| validate | 检查是否为正确的状态，不是则抛出异常或返回error code | validateInputs |
2.4.3 按需求才执行的方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Suffix | IfNeeded | 需要的时候执行，不需要的时候什么都不做 | drawIfNeeded |
| Prefix | might | 同上 | mightCreate |
| Prefix | try | 尝试执行，失败时抛出异常或是返回errorcode | tryCreate |
| Suffix | OrDefault | 尝试执行，失败时返回默认值 | getOrDefault |
| Suffix | OrElse | 尝试执行、失败时返回实际参数中指定的值 | getOrElse |
| Prefix | force | 强制尝试执行。error抛出异常或是返回值 | forceCreate, forceStop |
2.4.4 异步相关方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix | blocking | 线程阻塞方法 | blockingGetUser |
| Suffix | InBackground | 执行在后台的线程 | doInBackground |
| Suffix | Async | 异步方法 | sendAsync |
| Suffix | Sync | 对应已有异步方法的同步方法 | sendSync |
| Prefix or Alone | schedule | Job和Task放入队列 | schedule, scheduleJob |
| Prefix or Alone | post | 同上 | postJob |
| Prefix or Alone | execute | 执行异步方法（注：我一般拿这个做同步方法名） | execute, executeTask |
| Prefix or Alone | start | 同上 | start, startJob |
| Prefix or Alone | cancel | 停止异步方法 | cancel, cancelJob |
| Prefix or Alone | stop | 同上 | stop, stopJob |
2.4.5 回调方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix | on | 事件发生时执行 | onCompleted |
| Prefix | before | 事件发生前执行 | beforeUpdate |
| Prefix | pre | 同上 | preUpdate |
| Prefix | will | 同上 | willUpdate |
| Prefix | after | 事件发生后执行 | afterUpdate |
| Prefix | post | 同上 | postUpdate |
| Prefix | did | 同上 | didUpdate |
| Prefix | should | 确认事件是否可以发生时执行 | shouldUpdate |
2.4.6 操作对象生命周期的方法
| 单词 | 意义 | 例 |
|---|---|---|
| initialize | 初始化。也可作为延迟初始化使用 | initialize |
| pause | 暂停 | onPause ，pause |
| stop | 停止 | onStop，stop |
| abandon | 销毁的替代 | abandon |
| destroy | 同上 | destroy |
| dispose | 同上 | dispose |
2.4.7 与集合操作相关的方法
| 单词 | 意义 | 例 |
|---|---|---|
| contains | 是否持有与指定对象相同的对象 | contains |
| add | 添加 | addJob |
| append | 添加 | appendJob |
| insert | 插入到下标n | insertJob |
| put | 添加与key对应的元素 | putJob |
| remove | 移除元素 | removeJob |
| enqueue | 添加到队列的最末位 | enqueueJob |
| dequeue | 从队列中头部取出并移除 | dequeueJob |
| push | 添加到栈头 | pushJob |
| pop | 从栈头取出并移除 | popJob |
| peek | 从栈头取出但不移除 | peekJob |
| find | 寻找符合条件的某物 | findById |
2.4.8 与数据相关的方法
| 单词 | 意义 | 例 |
|---|---|---|
| create | 新创建 | createAccount |
| new | 新创建 | newAccount |
| from | 从既有的某物新建，或是从其他的数据新建 | fromConfig |
| to | 转换 | toString |
| update | 更新既有某物 | updateAccount |
| load | 读取 | loadAccount |
| fetch | 远程读取 | fetchAccount |
| delete | 删除 | deleteAccount |
| remove | 删除 | removeAccount |
| save | 保存 | saveAccount |
| store | 保存 | storeAccount |
| commit | 保存 | commitChange |
| apply | 保存或应用 | applyChange |
| clear | 清除数据或是恢复到初始状态 | clearAll |
| reset | 清除数据或是恢复到初始状态 | resetAll |
2.4.9 成对出现的动词
| 单词 | 意义 |
|---|---|
| get获取 | set 设置 |
| add 增加 | remove 删除 |
| create 创建 | destory 移除 |
| start 启动 | stop 停止 |
| open 打开 | close 关闭 |
| read 读取 | write 写入 |
| load 载入 | save 保存 |
| create 创建 | destroy 销毁 |
| begin 开始 | end 结束 |
| backup 备份 | restore 恢复 |
| import 导入 | export 导出 |
| split 分割 | merge 合并 |
| inject 注入 | extract 提取 |
| attach 附着 | detach 脱离 |
| bind 绑定 | separate 分离 |
| view 查看 | browse 浏览 |
| edit 编辑 | modify 修改 |
| select 选取 | mark 标记 |
| copy 复制 | paste 粘贴 |
| undo 撤销 | redo 重做 |
| insert 插入 | delete 移除 |
| add 加入 | append 添加 |
| clean 清理 | clear 清除 |
| index 索引 | sort 排序 |
| find 查找 | search 搜索 |
| increase 增加 | decrease 减少 |
| play 播放 | pause 暂停 |
| launch 启动 | run 运行 |
| compile 编译 | execute 执行 |
| debug 调试 | trace 跟踪 |
| observe 观察 | listen 监听 |
| build 构建 | publish 发布 |
| input 输入 | output 输出 |
| encode 编码 | decode 解码 |
| encrypt 加密 | decrypt 解密 |
| compress 压缩 | decompress 解压缩 |
| pack 打包 | unpack 解包 |
| parse 解析 | emit 生成 |
| connect 连接 | disconnect 断开 |
| send 发送 | receive 接收 |
| download 下载 | upload 上传 |
| refresh 刷新 | synchronize 同步 |
| update 更新 | revert 复原 |
| lock 锁定 | unlock 解锁 |
| check out 签出 | check in 签入 |
| submit 提交 | commit 交付 |
| push 推 | pull 拉 |
| expand 展开 | collapse 折叠 |
| begin 起始 | end 结束 |
| start 开始 | finish 完成 |
| enter 进入 | exit 退出 |
| abort 放弃 | quit 离开 |
| obsolete 废弃 | depreciate 废旧 |
| collect 收集 | aggregate 聚集 |
2.5 变量&常量命名
2.5.1 变量命名
变量是指在程序运行中可以改变其值的量，包括成员变量和局部变量。变量名由多单词组成时，第一个单词的首字母小写，其后单词的首字母大写，俗称骆驼式命名法（也称驼峰命名法），如 computedValues，index、变量命名时，尽量简短且能清楚的表达变量的作用，命名体现具体的业务含义即可。
变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。pojo中的布尔变量，都不要加is(数据库中的布尔字段全都要加 is_ 前缀)。
2.5.2 常量命名
常量命名CONSTANT_CASE，一般采用全部大写（作为方法参数时除外），单词间用下划线分割。那么什么是常量呢？
常量是在作用域内保持不变的值，一般使用final进行修饰。一般分为三种，全局常量（public static final修饰），类内常量（private static final 修饰）以及局部常量（方法内，或者参数中的常量），局部常量比较特殊，通常采用小驼峰命名即可。
public class HelloWorld {
/**
* 局部常量(正例)
*/
public static final long USER_MESSAGE_CACHE_EXPIRE_TIME = 3600;
/**
* 局部常量(反例，命名不清晰）
*/
public static final long MESSAGE_CACHE_TIME = 3600;
/**
* 全局常量
*/
private static final String ERROR_MESSAGE = " error message";
/**
* 成员变量
*/
private int currentUserId;
/**
* 控制台打印 {@code message} 信息
*
* @param message 消息体，局部常量
*/
public void sayHello(final String message){
System.out.println("Hello world!");
}
}
常量一般都有自己的业务含义,不要害怕长度过长而进行省略或者缩写。如，用户消息缓存过期时间的表示，那种方式更佳清晰，交给你来评判。
2.5.3 通用命名规则
- 尽量不要使用拼音；杜绝拼音和英文混用。对于一些通用的表示或者难以用英文描述的可以采用拼音，一旦采用拼音就坚决不能和英文混用。 正例： BeiJing， HangZhou 反例： validateCanShu
- 命名过程中尽量不要出现特殊的字符，常量除外。
- 尽量不要和jdk或者框架中已存在的类重名，也不能使用java中的关键字命名。
- 妙用介词，如for(可以用同音的4代替), to(可用同音的2代替), from, with，of等。 如类名采用User4RedisDO，方法名getUserInfoFromRedis，convertJson2Map等。
2.6 代码注解
2.6.1 注解的原则
好的命名增加代码阅读性，代码的命名往往有严格的限制。而注解不同，程序员往往可以自由发挥，单并不意味着可以为所欲为之胡作非为。优雅的注解通常要满足三要素。
- Nothing is strange 没有注解的代码对于阅读者非常不友好，哪怕代码写的在清除，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。
- Less is more 从代码维护角度来讲，代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。
// 根据id获取信息【废话注解】
getMessageById(id)
- Advance with the time 注解应该随着代码的变动而改变，注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。
2.6.2 注解格式
注解大体上可以分为两种，一种是javadoc注解，另一种是简单注解。javadoc注解可以生成JavaAPI为外部用户提供有效的支持javadoc注解通常在使用IDEA，或者Eclipse等开发工具时都可以自动生成，也支持自定义的注解模板，仅需要对对应的字段进行解释。参与同一项目开发的同学，尽量设置成相同的注解模板。
a. 包注解
包注解在工作中往往比较特殊，通过包注解可以快速知悉当前包下代码是用来实现哪些功能，强烈建议工作中加上，尤其是对于一些比较复杂的包，包注解一般在包的根目录下，名称统一为package-info.java。
/**
* 落地也质量检测
* 1. 用来解决什么问题
* 对广告主投放的广告落地页进行性能检测，模拟不同的系统，如android，ios等; 模拟不同的网络：2G，3G，4G，wifi等
*
* 2. 如何实现
* 基于chrome浏览器，用chromedriver驱动浏览器，设置对应的网络，OS参数，获取到浏览器返回结果。
*
* 注意： 网络环境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常规速度，可以根据实际情况进行调整
*
* @author author
* @time 2019/12/7 20:3 下午
*/
package cn.mycookies.landingpagecheck;
b. 类注接
javadoc注解中，每个类都必须有注解。
/**
* Copyright (C), 2019-2020, Jann balabala...
*
* 类的介绍：这是一个用来做什么事情的类，有哪些功能，用到的技术.....
*
* @author 类创建者姓名 保持对齐
* @date 创建日期 保持对齐
* @version 版本号 保持对齐
*/
c. 属性注解
在每个属性前面必须加上属性注释，通常有一下两种形式，至于怎么选择，你高兴就好，不过一个项目中要保持统一。
/** 提示信息 */
private String userName;
/**
* 密码
*/
private String password;
d. 方法注释
在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。
/**
* 方法的详细说明，能干嘛，怎么实现的，注意事项...
*
* @param xxx 参数1的使用说明， 能否为null
* @return 返回结果的说明， 不同情况下会返回怎样的结果
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
e. 构造方法注释
在每个构造方法前面必须加上注释，注释模板如下：
/**
* 构造方法的详细说明
*
* @param xxx 参数1的使用说明， 能否为null
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
而简单注解往往是需要工程师字节定义，在使用注解时应该注意一下几点：
- 枚举类的各个属性值都要使用注解，枚举可以理解为是常量，通常不会发生改变，通常会被在多个地方引用，对枚举的修改和添加属性通常会带来很大的影响。
- 保持排版整洁，不要使用行尾注释；双斜杠和星号之后要用1个空格分隔。
int id = 1;// 反例：不要使用行尾注释
//反例：换行符与注释之间没有缩进
int age = 18;
// 正例：姓名
String name;
/**
* 1. 多行注释
*
* 2. 对于不同的逻辑说明，可以用空行分隔
*/
三、代码开发规范
3.1 工程名称命名
- 工程命名由三部分组成：前缀-项目名称-后缀。
- 工程根据功能分为：手机工程和一般性工程，手机工程主要给手机端及app提供页面和接口，除手机之外的工程统一称为一般性工程，由前缀决定。
- 工程根据访问渠道分为：外部工程和内部工程，外部工程的主要用户为外部注册用户，对公网开放，内部工程的访问用户为公司内部人员，只能在公司内网访问，由后缀决定。
3.1.1 前缀：前缀决定工程的功能
| 前缀 | 说明 |
|---|---|
| mobile | 基于手机浏览器的web项目，主要提供h5页面 |
| android | 关于安卓手机的native app项目 |
| ios | 关于ios手机的native app项目 |
| ins | 公司的一般项目，非手机类项目都使用该前缀 |
3.1.2 项目名称
项目名称需要和项目内容非常贴切，让人一看就知道项目是干什么的，命名需要leader、部门总监，一起评审，通过后才能使用。
3.1.3 后缀：后缀决定工程的功能和使用用户
| 后缀 | 说明 |
|---|---|
| front | 前端项目 |
| web | 外部工程，提供json请求，不能提供RPC接口，此类工程偏向于提供web页面业务为主 |
| proxy | 外部工程，提供对外调用接口，不能提供RPC接口，此类工程偏向于提供外部接口为主 |
| platform | 内部工程，主要提供RPC接口服务，另：可以只为技术人员提供一些监控管理的页面，此类工程偏向于RPC接口为主且只能内网访问 |
| internal | 内部工程，即可以提供RPC接口服务也可以提供json请求，但以json请求为主。此类工程偏向于提供后台页面为主且只能内网访问，如果此类工程的业务名跟platform工程的业务名同名，则在业务名后跟admin，以免他们的client重名冲突。比如：ins-xy-platform 和 ins-xy-internal 后者应该改为ins-xyadmin-internal. |
| task | 以main函数存在的，通常是以jar包的形式，不需要容器，独立运行 |
| app | 手机上安装的软件 |
| client | 提供sdk的客户端 |
| util | 工具包（ins-utility应该改名为ins-common-util） |
3.1.3.1 示例
1、车路协同单体提供pc端访问的项目应该叫：ins-cvis-web，为车路协同提供手机端页面访问的项目应该叫：mobile-cvis-web。
2、车路协同给其他端提供业务接口调用的项目应该叫：ins-cvis-platform，为公司内部业务人员提供页面访问的项目应该叫：ins-cvis-internal。
3、给app提供外部接口支持的项目应该叫：ins-xxx-proxy。
4、像文件系统(lpfs)即需要提供管理页面，又需要提供RPC接口调用，还需要给外网提供接口和页面的项目需要根据访问渠道分成外部工程和内部工程两个工程，
外部工程应该命名为：ins-lpfs-proxy，因为主要以提供外部接口为主所以后缀应该为proxy。
5、内部工程应该命名为：ins-lpfs-platform，因为主要以RPC接口为主，且提供的页面只为内部技术人员使用，所以后缀应该为platform，如果提供的页面是给业务人员使用则应该为：ins-lpfs-internal。
3.1.4 工程结构包名
com.hiacent.项目名称.web/platform【.模块名】。
如果只有一个业务模块，则业务模块级可以省略。
例如 :
-
ins-biz-web: 工程结构包名:com.hiacent.biz.web【.模块名】
-
ins-user-platform:工程结构包名：com.hiacent.user.platform【.模块名】
工程字符集: 工程符集全部设定为UTF-8格式
3.2 继承结构及工程规范
| 模块名称 | 模块说明 | 示例 | 备注 |
|---|---|---|---|
| entity层 | 实体类命名与表名相同，首字母大写，如果表名存在_那么将_这去掉后首字母大写。 | 表名:like_log 实体名 LikeLog | 实体类属性必须与数据库字段名保持一致。 |
| dao层 | 继承com.baomidou.mybatisplus.core.mapper.BaseMapper 要求实体泛型dao层下接口命名：实体名+Mapper 。 | LikeLogMapper | |
| service层 | 要求：接口继承com.baomidou.mybatisplus.extension.service.IService要求实体泛型 | ||
| service.impl层类 | 继承com.baomidou.mybatisplus.extension.service.impl.ServiceImpl，service层下接口命名：业务名称+Service 。service.impl层命名： 业务名称+ServiceImpl 。 | LikeLogService；LikeLogServiceImpl | service层可以调用service层和dao层和其他项目。 service层下可再包一层bean层，用以存放数据结构的类，必须以Bean结尾。 平台service层内部调用的方法可以返回entity，但是被manage层调用的service方法只能返回dto或基本数据类型，不能返回entity到manage。 |
| manage层 | 调用其他服务的接口，通常使用Feign来实现 | ILikeLogMange | manage层下接口命名：I+业务名称+Manage。 |
| controller层 | 继承: org.jeecg.common.system.base.controller.JeecgController<T, S extends IService>controller层命名：以Controller结尾。 | LikeLogController | web/proxy/internal可用；controller层不能出现dto |
| form层 | web/proxy/internal可用；form下类命名：以Form结尾。 | LikeBaseInfoForm | form可以引用其他form form中不可以包含dto |
| dto层 | internal/platform 可用；dto层命名：以Dto结尾，前缀不一定是entity。 | LikeLogDto | dto不能引用别人的dto |
| schedule类 | schedule层命名: 以业务名称开头，以Schedule结尾，前缀不一定是entity。 | SendEmailSchedule | |
| Idp类 | idp层命名：以IdpHandler结尾。 | ResumeIdpHandler | |
| util层 | util层命名：以Util或Utils结尾。 | MoneyUtil | |
| consts层 | 静态变量类consts层命名：以Const结尾。 | LikeLogConst | |
| helper层 | helper层命名：client名+Helper结尾。 | UserPlatformClientHelper | Helper层主要放置调用其它端client的工具类； Helper只可以出现调平台的代码和处理平台返回错误的代码； Helper不允许调其他helper； |
| filter | filter命名：以Filter结尾。 | AuthFilter | 只能出现在common包下面的filter包中 |
| resolver | 包名只能叫resolver且同一工程下只能有一个resolve包，只能出现在common包下的resolver包中，此包下只能有一个类文件且名称为：MvcExceptionResolver。 |
3.3 数据结构体标准
dto，form，entity，bean四者间的转换只能通过手动get，set方式赋值。
类的静态变量、静态区域块、构造函数中，不允许出现数据库的调用和RPC的调用。
3.3.1 命名标准
同一工程下的受spring管理的类的类名不能相同，即使包名不同也不允许类名相同。
3.3.2 通用标准
Ajax方法里不能声明callback参数，因为此参数在使用跨域时做为系统占用参数。
所有可以通过网页端访问的URL命名统一全小写，可以在单词之间用“-”（减号）分隔，controller采用骆峰格式命名两者除了大小写之外其他尽量保持相同。
例：@RequestMapping("/getassesseeandbranch")
-
所有RPC接口统一用驼峰形式。
-
返回值是json格式URL名必须是以.json结尾.
3.4 Web URL标准
- Controller中URL的requestMapping不能以＂/＂结尾 。
例：@RequestMapping("/getassesseeandbranch")
- 在前端页面中书写的URL必须以“/”结尾。
- 所有非登录能访问的目录型url（不是以.*结尾的url），如果访问时没有“/”结尾，则需要自动加上“/”并作301跳转。
例如：http://www.hiacent.com/login?name=xxx应该301跳转到http://www.hiacent.com/login/?name=xxx。此条只针对get请求。
- 所有非登录能访问的列表页面，所有翻页都需要修改成 http://www.hiacent.com/list/pnX/ (X为页码）的形式。
- ajax翻页的不用遵循这个规范。
3.4.1 Ajax URL标准
- Ajax方法必须以.json结尾。
例：@RequestMapping("/getuser.json")
- header头信息里包括X-Requested-With=XMLHttpRequest 或者 带有callback参数。
3.4.2 APP URL标准
- APP方法必须以.json结尾。
例：@RequestMapping("/getuser.json")
- 请求都是压缩格式，header头信息里包括accept-encoding=gzip，不能包含X-Requested-With=XMLHttpRequest头信息或callback参数。
3.4.3 Ajax使用
ajax请求以.json结尾，header头信息里包括X-Requested-With=XMLHttpRequest 或者 带有callback参数请求并且是.json后缀的访问也属于ajax请求。
- ajax和web根据功能放在同一controller里。
请求参数放在方法行参里，不在使用reqeust获取请求参数，扁平化参数或封装form对象，controller方法参数扁平话后，大家写对象时一定要定义成Form，不要用弱对象map这些类型。
-
controller方法参数不再有HttpServletRequest、HttpServletResponse，统一在继承的父类AbstractController提供方法操作，如cookie、文件下载等。
-
返回结果使用方法直接返回ajax方法并且，返回值是json格式的方法的返回值不需要自己转换json。
请求形式：http://domain.hiacent.com/uri?key1=value1&key2=value2&...
返回协议体：{"flag":1,"data":{},"code":"","msg":""}
例：
@RequestMapping("/aap.json")
public List<Integer> aaph(Model model) throws BizException {
List<Integer> list = new ArrayList<Integer>();
list.add(1);
list.add(2);
return list;
}
3.4.4 Ajax返回数据规范
// 正常返回
{
"flag": 1, // 数据状态标识
"data": { // 正常返回的相关数据，可以是 Object / Array
...
}
}
// 异常返回
{
"flag": 0, // 数据状态标识
"code": "***", // 异常标识code
"msg": "some error message." // 异常提示信息
}
在正常情况下，后台只返回 flag 和 data 两个字段，异常情况下，返回 flag / code 和 msg 三个字段。
对于复杂业务场景，返回正常数据可能包含多种情况，以下面的方式来约束：
{
"flag": 1,
"data": {
"biz_code": "***",
"msg": "some notice message.",
"***": some value
}
}
和前端约定：成功失败的返回值（成功flag=1，失败flag=0）。
3.5 手机app请求手机app请求
请求以.json结尾，请求都是压缩格式，header头信息里包括accept-encoding=gzip。
请求参数放在方法行参里，不在使用reqeust获取请求参数，扁平化参数或封装form对象，请求参数放在方法行参里，不在使用reqeust获取请求参数，扁平化参
数或封装form对象，controller方法参数扁平话后，大家写对象时一定要定义成Form，不要用弱对象map这些类型。
返回结果使用方法直接返回。
请求参数形式：http://domain.lietou.com/uri?mustKey1=v1&mustKey2=v2&data={}
兼容版本 返回的协议体：
{
"message": "OK",
"status": 0,
"data": {},
"flag": 1
}
最终版本和ajax返回一样。
3.6 Cache使用
关于缓存的使用规范
-
所有业务缓存、二级缓存缓存都用redis，不能用memcache。
-
redis只用作不持久化的缓存
四、数据库设计规范
4.1 数据库命令规范
1、所有数据库对象名称必须使用小写字母并用下划线分割
2、所有数据库对象名称禁止使用mysql保留关键字（如果表名中包含关键字查询时，需要将其用单引号括起来）
3、数据库对象的命名要能做到见名识意，并且最后不要超过32个字符
4、临时库表必须以tmp_为前缀并以日期为后缀，备份表必须以bak_为前缀并以日期(时间戳)为后缀
5、所有存储相同数据的列名和列类型必须一致（一般作为关联列，如果查询时关联列类型不一致会自动进行数据类型隐式转换，会造成列上的索引失效，导致查询效率降低）
4.1.1 数据库命名规范
采用小写字母、数字（通常不需要）和下划线组成。禁止使用’-’，命名简洁、含义明确。
4.1.2 表命名
-
根据业务类型不同，采用不同的前缀，小写字母、下划线组成
-
长度控制在30个字符以内
推荐的命名规则
类型 前缀 说明 业务表 tb_ 关系表 tr_ 历史表 th_ 统计表 ts_ 日志表 tl_xx_log 系统表、字典表、码表 sys_ 临时表 tmp_ 禁止使用 备份表 bak_xx_ymd 视图 view_ 避免使用
4.2 数据库基本设计规范
4.2.1 所有表必须使用Innodb存储引擎
没有特殊要求（即Innodb无法满足的功能如：列存储，存储空间数据等）的情况下，所有表必须使用Innodb存储引擎（mysql5.5之前默认使用Myisam，5.6以后默认的为Innodb）Innodb 支持事务，支持行级锁，更好的恢复性，高并发下性能更好。
4.2.2 数据库和表的字符集统一使用utf8mb4
兼容性更好，统一字符集可以避免由于字符集转换产生的乱码，不同的字符集进行比较前需要进行转换会造成索引失效。
- 解读：在Mysql中的UTF-8并非“真正的UTF-8”，而utf8mb4”才是真正的“UTF-8”。
4.2.3 所有表和字段都需要添加注释
使用comment从句添加表和列的备注 从一开始就进行数据字典的维护
4.2.4 尽量控制单表数据量的大小，建议控制在500万以内
500万并不是MySQL数据库的限制，过大会造成修改表结构，备份，恢复都会有很大的问题
可以用历史数据归档（应用于日志数据），分库分表（应用于业务数据）等手段来控制数据量大小。
4.2.5 谨慎使用MySQL分区表
分区表在物理上表现为多个文件，在逻辑上表现为一个表 谨慎选择分区键，跨分区查询效率可能更低 建议采用物理分表的方式管理大数据
4.2.6 尽量做到冷热数据分离，减小表的宽度
MySQL限制每个表最多存储4096列，并且每一行数据的大小不能超过65535字节 减少磁盘IO,保证热数据的内存缓存命中率（表越宽，把表装载进内存缓冲池时所占用的内存也就越大,也会消耗更多的IO） 更有效的利用缓存，避免读入无用的冷数据 经常一起使用的列放到一个表中（避免更多的关联操作）
4.2.7 禁止在表中建立预留字段
预留字段的命名很难做到见名识义 预留字段无法确认存储的数据类型，所以无法选择合适的类型 对预留字段类型的修改，会对表进行锁定
4.2.8 禁止在数据库中存储图片，文件等大的二进制数据
通常文件很大，会短时间内造成数据量快速增长，数据库进行数据库读取时，通常会进行大量的随机IO操作，文件很大时&#
以上是关于整理最全规范之Git仓库管理规范，Java开发规范，最全Java命名规范，数据库开发设计规范，接口设计规范的主要内容，如果未能解决你的问题，请参考以下文章