14-Java开发规范

nobility 发布于 2022-01-29 02-Java面向对象 2981 次阅读

命名规范

类型 约束
项目名 羊肉串式：全部小写，多个单词用中划线分隔
包名 无限制式：全部小写，多个单词不用分隔
类名 大驼峰式：单词首字母大写
变量名和方法名 小驼峰式：首字母小写，除首个单词，其他单词首字母大写，变量名用名词，方法名用动词加宾语
常量名 大蛇形式：全部大写，多个单词用下划线分隔
表名和字段名 小蛇形式：全部小写，多个单词用下划线分隔，表名不要加复数形式

目录命名

项目命名

缩写后缀 全称 直意 特点
CMS Content Management System 内容管理系统
OA Office Automatio System 自动化办公系统
HRM Human Resources Management System 人力资源管理系统
TMS Transportation Management System 运输管理系统
WMS Warehouse Management System 仓库管理系统
OMS Order Management System 订单管理系统
ERP Enterprise Resource Planning System 企业资源计划系统
CRM Customer Relationship Management System 客户关系管理系统
SRM Supplier Relationship Management System 供应商关系管理系统
HIS Hospital Information System 医院信息系统
PMS Property Management System 物业（酒店）管理系统

包命名

包名的构成一般由前缀.发起者名.项目名.模块名组成，常见的前缀可以分为以下几种：

前缀名 例 含义
indi或onem indi.发起者名.项目名.模块名.…… 个体项目，个人发起但非独自完成，copyright主要属于发起者
pers、priv pers.个人名.项目名.模块名.…… 个人项目，独自完成，可公开或私有项目，copyright主要属于个人
team team.团队名.项目名.模块名.…… 团队项目，由该团队开发的项目，copyright属于该团队
顶级域名 com.公司名.项目名.模块名.…… 公司项目，copyright由项目发起的公司所有

类命名

通用类

类别 约束
抽象类 Abstract或Base开头
标记接口 able结尾
枚举类 Enum结尾
常量类 Const结尾
异常类 Exception结尾
配置类 Config结尾
测试类 Test结尾
设计模式相关类 Builder，Factory等后缀
MVC分层 Controller、Service、ServiceImpl、DAO结尾
接口实现类 接口名+ Impl

框架类

类别 约束
映射器 Mapper结尾
拦截器 Interceptor结尾
切面 Aspect结尾

工具类

类别 约束 内容
工具箱、助手 Utils、Tools、Helper结尾 其中的方法用parse、format等
转换器 Converter结尾 其中的方法用convertToXxx等
填充器 filler结尾 可作为转换器的内部类，其中的方法用fillInXXX等
处理器 Handler结尾 其中的方法用xxxHandle等
校验器 Validator结尾 本地参数合法性校验，其中的方法用xxxValidate等
检查员 Checker结尾 远程查库状态校验，其中的方法用xxxCheck等
过滤器 filter结尾 根据条件过滤集合，其中的方法用xxxFilter
发送器 Sender结尾 其中的方法用sendXxx等

领域模型类

类别 约束 内容
响应类 Response结尾 Controller返回对象，必须要有{message, data, code}这三个字段
视图对象类 VO结尾 Service返回对象，必须是向前端展示的内容，即Response中的data中的内容
数据传输对象类 DTO结尾 Service返回对象、Controller和Service非查询方法的参数，向第三方系统提供或从第三方系统取出的传输对象
查询对象类 Query结尾 查询方法所使用的参数

方法名

返回布尔值的方法

单词 位置 意义
is 前缀 对象是否符合期待的状态
can 前缀 对象能否执行所期待的动作
should 前缀 调用方执行某个命令或方法是好还是不好,应不应该，或者说推荐还是不推荐
has 前缀 对象是否持有所期待的数据和属性
needs 前缀 调用方是否需要执行某个命令或方法

用来检查的方法

单词 位置 意义
ensure 前缀 检查是否为期待的状态，不是则抛出异常或返回error code
validate 后缀 检查是否为正确的状态，不是则抛出异常或返回error code
check 前缀 检查是否为正确的状态，不是则抛出异常或返回error code

按需执行的方法

单词 位置 意义
IfNeeded 后缀 需要的时候执行，不需要的时候什么都不做
might 前缀 需要的时候执行，不需要的时候什么都不做
try 前缀 尝试执行，失败时抛出异常或是返回errorcode
OrDefault 后缀 尝试执行，失败时返回默认值
OrElse 后缀 尝试执行、失败时返回实际参数中指定的值
force 前缀 强制尝试执行。error抛出异常或是返回值

异步相关方法

单词 位置 意义
blocking 前缀 线程阻塞方法
InBackground 后缀 执行在后台的线程
Async 后缀 异步方法
Sync 后缀 对应已有异步方法的同步方法
schedule 前缀或单独使用 Job和Task放入队列
post 前缀或单独使用 同上
execute 前缀或单独使用 执行异步方法（注：我一般拿这个做同步方法名）
start 前缀或单独使用 同上
cancel 前缀或单独使用 停止异步方法
stop 前缀或单独使用 同上

回调方法

单词 位置 意义
on 前缀 事件发生时执行
before 前缀 事件发生前执行
pre 前缀 事件发生前执行
will 前缀 事件发生前执行
after 前缀 事件发生后执行
post 前缀 事件发生后执行
did 前缀 事件发生后执行
should 前缀 确认事件是否可以发生时执行

操作对象生命周期的方法

单词 意义
initialize 初始化。也可作为延迟初始化使用
pause 暂停
stop 停止
abandon 销毁的替代
destroy 销毁的替代
dispose 销毁的替代

集合操作相关的方法

单词 意义
contains 是否持有与指定对象相同的对象 contains
add 添加
append 添加
insert 插入到下标n
put 添加与key对应的元素
remove 移除元素
enqueue 添加到队列的最末位
dequeue 从队列中头部取出并移除
push 添加到栈头
pop 从栈头取出并移除
peek 从栈头取出但不移除
find 寻找符合条件的某物

数据相关的方法

单词 意义
create 新创建
new 新创建
from 从既有的某物新建，或是从其他的数据新建
to 转换
update 更新既有某物
load 读取
fetch 远程读取
delete 删除
remove 删除
save 保存
store 保存
commit 保存
apply 保存或应用
clear 清除数据或是恢复到初始状态
reset 清除数据或是恢复到初始状态

其他常用命名

成对动词

正面 反面
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：收集 ggregate：聚集
disabled：禁用 enabled：启用

常用名词

数组使用名词+复数形式，集合使用集合后缀比如map、list、set

单词 含义
result 结果
count 计数
number 数字
flag 标记
base 基础
info 信息
item 项
city 城市
status 状态
type 类型
element 元素
value 值
content 内容
file 文件
other 其他
task 任务
authority 认证
detail 详情
instance 实例

代码格式

基本要求

/**
  * 数组
  */
int[] array = new int[2];
int[] array = {1, 2};
public void test(int[] array) {}
/**
  * 泛型使用菱形语法，或全省略语法
  */
ArrayList<Integer> arrayList = new ArrayList<>();
ArrayList<Integer> arrayList = new ArrayList();
/**
  * 长整型赋值数字后使用大些L
  */
long number = 1L;

注释格式

注释原则

  1. Nothing is strange：没有什么奇怪的，注释一定要写，不仅要解释逻辑，更要说清楚修改，比如：注释掉的代码，为什么要注释掉
  2. Less is more：少即是多，对于逻辑简单、命名规范、能清楚表达功能的代码无需注解
  3. Advance with the time：与时俱进，注释应该随代码变动而改变

包注释

包注释在包的根目录下名为package-info.java，该Java文件仅用来描述该包

/**
 * 包的描述
 * @author nobility
 * @date 下午4:42 2021/7/14
 */
package com.公司名.项目名.模块名;

类注释

/**
 * 类的描述
 * @author nobility
 * @date 下午4:47 2021/7/14
 * @version 1.0
 */
public class Main{}

属性注解

/**
 * 属性的描述
 */
private String property;
/**
 * 枚举项的描述
 */
STATUS(1, "启用"),

方法注释

在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。

/**
  * 方法的描述
  * @author nobility
  * @param 参数名1 参数描述
  * @return 返回类型 返回结果情况描述，若是构造方法无需这条
  * @exception 异常类型 抛出异常情况描述
  */
public static void main(String[] args) throws Exception {}

/**
  * {@inheritDoc} // 继承实现方法的注释
  */
@Override
public void test() {}

单行注释

单行注释双斜线和内容之间有空格，且应该在解释代码的上方

// 注释
int a;

代码缩紧

括号问题

/**
  * if/for/while/switch/do等保留字与小括号之间必须有空格
  * 不能与括号边界出现缝隙
  */
if (true) {
  return 1;
}
// 以及else要和大括号之间必须有空格
if (true) {
  return 1;
} else {
  return 0;
}
/**
  * 强制类型转换括号不能加空格
  */
int number = (int)1.0;

空格缩进

  • 换行符使用Unix格式，缩进采用4个空格而且禁止使用tab
  • 单行字符不能超过120个，超过需要换行（括号前不能换行）
    • 换行后的所有行应该相对第一行缩进四个空格
    • 运算符、方法调用的点应该在下一行
    • 方法调用中的多个参数逗号在上一行
  • 单个方法总行数不能超过80行，不同逻辑、语意、业务之间应该插入一个空行
/**
  * 二目、三目运算符左右需有空格，单目运算符不能有空格
  */
int max = a > b ? 1 :2;
if (!true) {
  return;
}
/**
  * 方法参数在定义和调用时都逗号后加空格
  */
public void test(int one, int two) {
  test(1, 2);
}

其他原则规范

单元测试原则

  • Service中的public方法要有单测
    • 对于查询方法的测试，只需要将查询结果输出即可
    • 对于插入更新删除方法，如果不想将测试数据保留在数据库，可以给测试方法或类添加事务，让其回滚，在测试类或方法中使用@Transactional在方法结束后会默认回滚，如果不放心，可与@Rollback一起使用
  • 单元测试最好要使用@ActiveProfiles("环境")指定测试环境的application-环境.yml配置文件
  • 被测试的bean不能手动new，需要使用Spring的方式注入，否则测试bean中用到了Spring的注解将失效

日志记录原则

  • 日志输出原则，如果异常影响业务进行输出error日志，否则输出warn日志
  • 记录方法调用情况需要如下几步，对于对象的打印可将其转为json
    1. 入参校验：判空、集合判空、字符串判空，若为空则打印warn日志
    2. 捕获式调用：正常打印info日志{被调用方法｜请求URL地址, 入参, 出参}，异常打印error日志{被调用方法｜请求URL地址, 入参, e}
    3. 出参校验：尽量不返回空，如果为null可返回空集合或空字符串
    4. 返回内容封装：过滤多余数据，只要自己使用的数据
加油啊！即便没有转生到异世界，也要拿出真本事！！！＼(`Δ’)／
最后更新于 2022-01-29