元数据起始
重要:
每次提交代码前,一定要使用idea工具来格式化代码 快捷键 Ctrl+Alt+L 与 Ctrl+Alt+O
规范&规则
1 命名规范
项目目录结构
├── main
│ ├── java
│ │ └── com.paic.loancloud.config
│ │ └─ user
│ │ ├── mapper \\mapper包,主要存放数据库操作类,相当于以前的dao
│ │ │ └── UserMapper.java
│ │ ├── model
│ │ │ ├── entity \\对应数据库中的表结构
│ │ │ │ └── User.java
│ │ │ └── form \\对应HTTP请求提交的json或表单
│ │ │ └── UserForm.java
│ │ │ └── json \\对应HTTP返回的json
│ │ │ └── UserJson.java
│ │ ├── service \\业务处理层
│ │ │ ├── UserService.java
│ │ │ └── impl \\业务处理实现层
│ │ │ └── UserServiceImpl.java
│ │ └── web \\REST层
│ │ └── UserRest.java
│ └── resources \\应用资源目录
│ └── mapper \\sql map
│ └── UserMapper.xml
└── test \\测试案例目录
├── java
│ └── com.paic.loancloud.config
│ └── user
│ └── mapper
│ └── web
│ └── service
│ └── TestUserService.java
└── resources
├──
├── application.properties
1.1 package命名
格式 com.paic.loancloud.[组件名].[子组件名]
比如:
com.paic.loancloud.config.xxx
1.2 Java 对象名, 成员变量名, 方法名
按照Java常用的驼峰规则。
类名每个单词首字母大写(特殊含义缩写除外)。
成员变量名首字母小写,其他每个单词首字母大写(特殊含义缩写除外),如: lastLoginTime, password, username
方法名同成员变量名(特殊含义缩写除外),如:getUserInfo, updateUser
service 实现类以Impl结尾
1.3 服务接口方法取名规则
- service层的方法不要出以select, insert等数据库关键字相关的命名
按照如下规范:(非以下举例外的方法命名 都是不允许的)
removeXxx 负责删除单个对象的方法 返回 boolean
updateXxx 负责更新单个对象的方法, 返回 boolean
addXxx 负责新增单个对象的方法 返回 boolean
addOrUpdateXxx 负责新增或更新单个对象的方法 返回 boolean
saveXxx 负责保存多个对象的方法 返回 boolean 或 int 视情况而定
getXxx 负责查询单个对象的方法 返回entity
queryXxx 负责查询多个对象的方法 queryListOfXxxByXxx queryMapOfXxxByXxx
- mapper层的方法名就是mapper的SQL ID
1.4 静态常量名
单词全大写, 每个单词下划线分割开
比如: CONN_URL, CONNECTION_PASSWORD
1.5测试用例命名
测试类命名:
TestXXXXXX 使用Test+测试的类命名
测试用例遵循格式为:
方法名: test_方法名_when_条件_then_结果
如果通过命名无法理解含义,需要做中文注释,或者直接在方法名上写中文
如: test_getFieldStandardById_when_传入ID为1000_then_对象存在
2 分层规则
2.1 展现控制层
web包中在类名上加上 @RestController("xxXX") 在类上@RequestMapping(/xxx/xxx),要写明请求方式,如POST/GET
注意:
1.不允许驼峰,所有的请求路径都是小写的,如 "/user/list"
2.路径含组合名词的请用下划线间隔, 如 "enterprise/enterprise_channel_relation"
而不是"enterprise/enterprise/channel/relation"或"enterprise/enterpriseChannelRelation"
2.2 业务逻辑层
src:
service包
包含子包:impl
在实现类名上加上 @Service
2.3 数据持久化层
src:
mapper包
resource:
mapper包
在接口上增加@Mapper注解
若查询是list, 要限制list的最大数量,默认设置为200
2.4 实体层
src:
model包
包含子包:form, entity,json
form包主要用于前端传递的参数
entity主要是跟数据库表一一对应
josn主要是返回的数据
主键必须使用Long类型
3 Swagger使用规则
系统使用swagger作为api文档生成器 ,开发与测试均需要通过swagger来测试系统,故需要开发人员维护好swagger
swagger只针对web层
3.1标注类
@Api(description= "字段标准系统API")
对每个类进行说明
3.2标注方法
@ApiOperation(value = "获取字段列表", notes = "通过单个查询条件获取fieldStandard列表数据", response = FieldStandardJson.class)
value方法名
notes 方法描述
response 代表返回的类
3.3标注方法入参
@ApiImplicitParam(name = "queryField", value = "模糊查询字段", required = true, dataType = "String", paramType = "body")
对字段进行相应说明
3.4标注方法出参
@ApiOperation(value = "获取字段列表", notes = "通过单个查询条件获取fieldStandard列表数据", response = FieldStandardJson.class)
4 异常处理规范
4.1 统一的异常捕获机制
参考代码 GlobalExceptionHandler 可统一捕获系统抛出的异常,并且格式化输出异常
现在系统中已捕获了两种异常,后续可进行补充
一种是MethodArgumentNotValidException , 输出如下:
{
"resultCode": "-1",
"resultMesg": "系统异常, 请联系系统管理员",
"data": [
{
"exceptionName": "MethodArgumentNotValidException",
"errorMessage": "ID不能为空",
"fieldCode": "id",
"rejectedValue": 0
},
{
"exceptionName": "MethodArgumentNotValidException",
"errorMessage": "数据库字段编码长度不能超过50个字符",
"fieldCode": "fieldCode",
"rejectedValue": "striffffffffffffffff'fffffff'\"ffffffffffffffffffffffffffffffffffffng"
}
]
}
另一种是全局的捕获异常Exception,输出如下:
{
"resultCode": "-1",
"resultMesg": "系统异常, 请联系系统管理员",
"data": [
{
"exceptionName": "HttpMessageNotReadableException",
"errorMessage": "Could not read document: Unexpected character ('n' (code 110)): was expecting comma to se",
"fieldCode": null,
"rejectedValue": null
}
]
}
5 其他规则
5.1 工具类
字符串工具类: 使用 org.apache.commons.lang3.StringUtils
集合工具类: 使用 org.apache.commons.collections.CollectionUtils
5.2 代码格式化
使用统一的idea默认格式化风格
5.3 代码review流程
1. 代码编写完,自我重构,梳理逻辑,接口注释,思路注释。
2. 通过工具对比,自我Review,确保文件改动,防止提交无用代码,测试代码,无关配置。
3. 提交本地分支前或后,找至少一个资深工程师Review代码, 主动说明改动内容, 影响范围。
4. 启动单测 或 启动服务 常规功能(比如登录)没有任何编译错误。
5. 提交归并至CI 测人负责人, 并主动告知影响范围。
5.4 Rest层 错误代码定义
1. 在ResponseCode.java定义 错误码 和错误码的消息内容, 注意不要加感叹号。
2. 在具体用到的rest中声明 错误代码的业务含义, 比如 XX_XX_FAIL等。
3. 使用错误码 如 Return.fail(XX_XX_FAIL)。
5.5 接口参数和返回对象的封装
1. 禁止使用Map<String, String>作为查询参数或查询返回值,这种可读性极差。
2. 一般3个或3个以上参数, 可选择性抽象为对象。 请封装一个 XxxQueryParam 或XxxParam作为 查询接口的参数。比如queryListOfXxx(XxxQueryParam params) updateXxx(XxxParam params)
3. 需要返回给客户端的对象, 根据实体对象中属性的敏感程度,或必要性, 进行保护, 可采用转换器转成model.json.Xxx。
比如model.entity.User ---》model.json.UserInfo UserInfo中是属性是暴露出去的必要属性。通过UserToUserInfoConverter转换。