如何设计风格良好的Restful API

最近朋友们都在讨论项目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/animalsGET /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宅楠军的文章

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 211,123评论 6 490
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,031评论 2 384
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 156,723评论 0 345
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,357评论 1 283
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,412评论 5 384
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,760评论 1 289
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,904评论 3 405
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,672评论 0 266
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,118评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,456评论 2 325
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,599评论 1 340
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,264评论 4 328
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,857评论 3 312
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,731评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,956评论 1 264
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,286评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,465评论 2 348