最近朋友们都在讨论项目Api规范的问题,大家对Restful风格的Api都或多或少有所了解,但是没人能明确说明Restful到底是什么情况下才能认为是Restful,比如说下面的这类代码算Restful 嘛?
@RequestMapping(value = "/addUser", method = RequestMethod.POST)
public boolean updateUser( User user) {
return userService.updateUser(user);
}
初步的觉得存在的问题是,Restful一般url中表示的应该是一种资源,而不是动作+资源这种形式,为此它不是Restful风格的API。当时的疑问是,如果我用user来定义一个资源,再通过动作来判定是更新还是修改,那样的话岂不是每种资源都会有四种类型的接口。然而,在Restful风格的设计中确实是这样的。通过这种方式可以让我们很清楚的知道该API的一个具体实现效果是什么,以及操作的是哪类资源。第一部分介绍Restful API的相关规范,第二部分是具体的实践部分,参考//www.greatytc.com/p/d6424d98b02e宅楠军的文章,在他的基础上,结合mybatis + lombok 实现Restful风格的设计。
1 Restful API的相关概念
1.1 版本
API的版本应该在URL中体现,如:
https://api.jerry.com/v1/
另一种做法是,将版本号放在HTTP头信息中,但没有放在URL中那么直观。
1.2 路径
路径又称"终点"(endpoint),表示API的具体网址。
在Restful架构中,每一种网址代表一种资源(resource),所有网址中不能有动词,只能有名词,而且所有名词往往与数据库的表名一致,且API中的名词也应该用复数。示例如下:
https://api.jerry.com/v1/zoos
https://api.jerry.com/v1/animals
https://api.jerry.com/v1/employees
1.3 HTTP动词
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有如下五个(括号里是对应的SQL类型)
-
GET(SELECT)
:从服务器取出资源(一项或多项); -
POST(CREATE)
:在服务器新建一个资源; -
PUT(UPDATE)
:在服务器更新资源(客户端提供改变后的完整资源); -
PATCH(UPDATE)
:在服务器更新资源(客户端提供改变的属性); -
DELETE(DELETE)
:从服务器删除资源。
还有两个不常用的HTTP动词:
-
HEAD
:获取资源的元数据; -
OPTIONS
:获取信息,关于资源的哪些属性是客户端可以改变的;
动词使用示例:
-
GET /zoos
:列出所有动物园 -
POST /zoos
:新建一个动物园 -
GET /zoos/ID
:获取某个指定动物园的信息 -
PUT /zoos/ID
:更新某个指定动物园的信息(提供该动物园的全部信息) -
PATCH /zoos/ID
:更新某个指定动物园的信息(提供该动物园的部分信息) -
DELETE /zoos/ID
:删除某个动物园 -
GET /zoos/ID/animals
:列出某个指定动物园的所有动物 -
DELETE /zoos/ID/animals/ID
:删除某个指定动物园的指定动物
1.4 过滤信息(Filtering)
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供响应的参数来过滤返回的结果。常见参数示例如下:
-
?limit=5
:指定返回的记录的数量; -
?offset=10
:指定返回记录的开始位置; -
?page=2&per_page=100
:指定第几页,以及每页的记录数; -
?sortby=name&order=asc
:指定返回结果按照哪个属性排序,以及排序顺序; -
?animal_type_id=1
:指定筛选条件。
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals
与GET /animals?zoo_id=ID
的含义是相同的。
1.5 状态码(Status Codes)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
-
200 OK - [GET]
:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
+201 CREATED - [POST/PUT/PATCH]
:用户新建或修改数据成功。 -
202 Accepted - [*]
:表示一个请求已经进入后台排队(异步任务) -
204 NO CONTENT - [DELETE]
:用户删除数据成功。 -
400 INVALID REQUEST - [POST/PUT/PATCH]
:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。 -
401 Unauthorized - [*]
:表示用户没有权限(令牌、用户名、密码错误)。 -
403 Forbidden - [*]
:表示用户得到授权(与401错误相对),但是访问是被禁止的。 -
404 NOT FOUND - [*]
:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。 -
406 Not Acceptable - [GET]
:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。 -
410 Gone -[GET]
:用户请求的资源被永久删除,且不会再得到的。 -
422 Unprocesable entity - [POST/PUT/PATCH]
当创建一个对象时,发生一个验证错误。 -
500 INTERNAL SERVER ERROR - [*]
:服务器发生错误,用户将无法判断发出的请求是否成功。
1.6 错误处理(Error handling)
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{
error: "Invalid API key"
}
1.7 返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范。
-
GET /collection
:返回资源对象的列表(数组) -
GET /collection/resource
:返回单个资源对象 -
POST /collection
:返回新生成的资源对象 -
PUT /collection/resource
:返回完整的资源对象 -
PATCH /collection/resource
:返回完整的资源对象 -
DELETE /collection/resource
:返回一个空文档
2 Restful Api 设计
//www.greatytc.com/p/d6424d98b02e宅楠军的文章整体项目搭建过程已经讲的很详细了,在他的基础上,我没使用jpa来实现与数据库交互,而是使用的mybatis,使用mybatis可以很方便的解决宅男军文章3.2中提到的空值问题,我们不考虑复制的问题,而是通过在mapperxml中的动态SQL来实现空值的判定,具体代码如下:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
<mapper namespace="com.jerry.restful.mapper.UserMapper">
<resultMap id="userList" type="com.jerry.restful.domain.User">
<id column="id" property="id" jdbcType="INTEGER"/>
<result column="user_name" property="userName" jdbcType="VARCHAR"/>
<result column="account" property="account" jdbcType="VARCHAR"/>
<result column="password" property="password" jdbcType="VARCHAR"/>
<result column="age" property="age" jdbcType="INTEGER"/>
</resultMap>
<update id="updateUser">
UPDATE t_user
SET
<if test="user.account != null">
account = #{user.account},
</if>
<if test="user.userName != null">
user_name = #{user.userName},
</if>
<if test="user.password != null">
password = #{user.password},
</if>
<if test="user.age != null">
age = #{user.age}
</if>
WHERE id = id
</update>
</mapper>
而使用lombok的目的是使实体类的代码更简洁,如下:
@Data
public class User {
private Integer id;
private String userName;
private Integer age;
private String account;
private String password;
public User(){}
}
项目中用到的部分注解解释
spring注解:
-
@GetMapping
:等同于@RequestMapping(method = RequestMethod.GET),其他类似; -
@PostMapping
: 同上,只是动作变成了POST; -
@DeleteMapping
:同上; -
@PutMapping
:同上; -
@pathVariable
:获取URL变量; -
@RequestBody
:将request body中的Json/xml对象解析成该参数类型的Javabean对象; -
@RequestParam
:获取前端传递给后端的参数,其中如果前端传递的参数和后端要接收的参数名字一致的,可以省略不写,如果不一致一定要完整写,不然获取不到想要的值。
swagger注解:
@ApiOperation
:接口说明注解;
@ApiParam
:解释api的参数的含义;
本文改进源码链接:https://github.com/JeryLiang/Restful-API-Demo
参考
阮一峰大神的文章《RESTful API 设计指南》
//www.greatytc.com/p/d6424d98b02e宅楠军的文章