接口

最新推荐文章于 2025-03-11 18:06:47 发布

原创最新推荐文章于 2025-03-11 18:06:47 发布 · 363 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#java

规范专栏收录该内容

0 篇文章

订阅专栏

本文档详细介绍了RESTful API的设计原则，包括读取、新建、更新和删除等操作的接口规约。同时，阐述了Swagger文档的使用，如类、方法和实体类注解的解释。此外，讨论了服务返回数据格式、参数校验的重要性及其推荐注解，以及Service/DAO层的命名规约。

文章目录

一、接口规约：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。