Java开发规范

元数据起始

 

重要：

每次提交代码前,一定要使用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)

主要是response这个参数,用于标示要返回的类,可在swagger ui上进行展示

我们rest层默认返回ReturnJson类, 为什么不写ReturnJson类呢,  因为ReturnJson里面的data是object,无法在swagger上看到具体的详细

故需要我们自己指定response

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转换。