接口

一、接口规约：RESTful API

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。

1.1.GET：读取（Select）

说明：

• 安全且幂等

示例：

// 根据id获取用户
GET /user/{id}
// 获取全部用户
GET /user
// 分页获取用户
GET /user/page

1.2.POST：新建（Create）

说明：

• 不安全且不幂等

示例：

// 新建用户
POST /user

1.3.PUT：更新（Update）

说明：

• 不安全但幂等

示例：

// 修改用户
PUT /user/{id}

1.4.DELETE：删除（Delete）

说明：

• 不安全但幂等

示例：

// 根据id删除用户
DELETE /user/{id}

二、接口文档：Swagger文档

swagger常用注解说明：

2.1.类上注解：@Api说明该类的作用

示例：@Api(tags = "自动补货需求推送")

2.2.方法注解：@ApiOperation用在方法上，说明方法的作用

示例：@ApiOperation(value = "分页查询自动补货需求", notes = "描述")

2.3.实体类注解：@ApiModel用于类 ；表示对类进行说明，用于参数用实体类接收 。

示例：@ApiModel("自动补货需求")

2.4.实体类字段注解：@ApiModelProperty用于方法，字段； 表示对model属性的说明或者数据操作更改 。

示例：@ApiModelProperty("事业部")

三、服务返回数据格式

序号	字段名称	字段描述	数据类型	备注
1.	status	服务标识	Boolean	标识服务执行结果，true/false
2.	message	服务消息	String	提示消息。
3.	code	状态码	int	自定义状态码
4.	data	返回数据	Object	服务返回数据

四、参数校验推荐

推荐使用JSR 303 – Bean Validation 规范，然后通过AOP进行统一拦截异常将提示信息返回给前端。

4.1.下列情形，需要进行参数校验：

1） 调用频次低的方法。
2） 执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致
中间执行回退，或者错误，那得不偿失。
3） 需要极高稳定性和可用性的方法。
4） 对外提供的开放接口，不管是 RPC/API/HTTP 接口。
5） 敏感权限入口。

4.2.Bean Validation常用注解

Bean Validation 中内置的 constraint

注解	作用
@Valid	被注释的元素是一个对象，需要检查此对象的所有字段值
@Null	被注释的元素必须为 null
@NotNull	被注释的元素必须不为 null
@AssertTrue	被注释的元素必须为 true
@AssertFalse	被注释的元素必须为 false
@Min(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@Max(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@DecimalMin(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@DecimalMax(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@Size(max, min)	被注释的元素的大小必须在指定的范围内
@Digits (integer, fraction)	被注释的元素必须是一个数字，其值必须在可接受的范围内
@Past	被注释的元素必须是一个过去的日期
@Future	被注释的元素必须是一个将来的日期
@Pattern(value)	被注释的元素必须符合指定的正则表达式

Hibernate Validator 附加的 constraint

注解	作用
@Email	被注释的元素必须是电子邮箱地址
@Length(min=, max=)	被注释的字符串的大小必须在指定的范围内
@NotEmpty	被注释的字符串的必须非空
@Range(min=, max=)	被注释的元素必须在合适的范围内
@NotBlank	被注释的字符串的必须非空
@URL(protocol=,host=, port=, regexp=, flags=)	被注释的字符串必须是一个有效的url
@CreditCardNumber	被注释的字符串必须通过Luhn校验算法，银行卡，信用卡等号码一般都用Luhn计算合法性
@ScriptAssert(lang=,script=,alias=)	要有Java Scripting API 即JSR 223(“Scripting for the JavaTMPlatform”)的实现
@SafeHtml (whitelistType=,additionalTags=)	classpath中要有jsoup包

版本	更新时间	备注
V1.0	2020-04-26

五、各层命名规约：

Service/DAO 层方法命名规约

1） 获取单个对象的方法用 get 做前缀。如：getUser。
2） 获取多个对象的方法用 list 做前缀，复数结尾。如：listUsers。
3） 获取统计值的方法用 count 做前缀。如：countUsers。
4） 插入的方法用 save/insert 做前缀。如：insertUser。
5） 删除的方法用 remove/delete 做前缀。如：deleteUser。
6） 修改的方法用 update 做前缀。如：updateUser。