如果你要问 Spring Boot 做什么最厉害,我想答案就在本章标题 RESTful API 简称 REST API 。

本项目源码下载

1 RESTful API 概述

1.1 什么是 RESTful API

Rest 是一种规范,符合 Rest 的 Api 就是 Rest Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有URI标识的服务器资源,返回统一格式的资源信息,包括 JSON、XML、CSV、ProtoBuf、其他格式。

1.2 RESTful API 设计规范

1.2.1 协议

建议使用基于 HTTPS 协议

1.2.2 域名

建议使用 api.domain.com

1.2.3 版本

  • 建议把版本放到 URL 中,即显式设计。如 https://api.domain.com/v1
  • 建议吧版本放到 HTTP 头信息中。不如放到 URL 中直观。

1.2.4 路径

在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。

1.2.5 HTTP 动词

常用的动词包括了5个

  • GET(SELECT):从服务器取出资源(一项或多项)。
  • POST(CREATE):在服务器新建一个资源。
  • PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
  • PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
  • DELETE(DELETE):从服务器删除资源。

1.2.6 过滤信息

如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。

  • api.domain.com/v1/users?limit=10 :指定返回记录的数量
  • api.domain.com/v1/users?offset=10:指定返回记录的开始位置
  • api.domain.com/v1/users?page=2&per_page=100:指定第几页,以及每页的记录数
  • api.domain.com/v1/users?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
  • api.domain.com/v1/users?animal_type_id=1:指定筛选条件

1.2.7 状态码

建议使用 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.2.8 错误处理

返回指定错误信息内容

{
"error":"err message"
}

1.2.9 返回结果

针对不同操作,服务器向用户返回的结果应该符合以下规范。

  • GET /collection:返回资源对象的列表(数组)
  • GET /collection/resource:返回单个资源对象
  • POST /collection:返回新生成的资源对象
  • PUT /collection/resource:返回完整的资源对象
  • PATCH /collection/resource:返回完整的资源对象
  • DELETE /collection/resource:返回一个空文档

1.2.10 超级链接

RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。

以上信息主要来自RESTful API 设计指南

2 Spring Boot 中如何使用 RESTful API

本章节需要编写的是对一个用户的增删改查操作,如下表是一个非 RESTful 和 标准 RESTful 的对比表。

Api Name 非RESTful RESTful Api
获取用户 /user/query/1 /users/1 GET
新增用户 /user/add /users POST
更新用户 /user/edit /users PUT
删除用户 /user/delete /users DELETE

2.1 新建 Spring Boot 项目

1)File > New > Project,如下图选择 Spring Initializr 然后点击 【Next】下一步

2)填写 GroupId(包名)、Artifact(项目名) 即可。点击 下一步

groupId=com.fishpro

artifactId=restful

3)选择依赖 Spring Web Starter 前面打钩。

4)项目名设置为 spring-boot-study-restful

2.2 编写示例代码

本次新增2个文件,其中UserController类中包括了对用户的4个操作增删改查。

  1. controller/UserController.java
  2. domain/UserDO.java

2.2.1 UserDO 实体类代码

public class UserDO {
private Integer userId;
private String userName; public Integer getUserId() {
return userId;
} public void setUserId(Integer userId) {
this.userId = userId;
} public String getUserName() {
return userName;
} public void setUserName(String userName) {
this.userName = userName;
}
}

2.2.2 UserController 类代码

/**
* RESTful API 风格示例 对资源 user 进行操作
* 本示例没有使用数据库,也没有使用 service 类来辅助完成,所有操作在本类中完成
* */
@RestController
@RequestMapping("/api/user")
public class UserController { /**
* 模拟一组数据
* */
private List<UserDO> getData(){
List<UserDO> list=new ArrayList<>(); UserDO userDO=new UserDO();
userDO.setUserId(1);
userDO.setUserName("admin");
list.add(userDO); userDO=new UserDO();
userDO.setUserId(2);
userDO.setUserName("heike");
list.add(userDO); userDO=new UserDO();
userDO.setUserId(3);
userDO.setUserName("tom");
list.add(userDO); userDO=new UserDO();
userDO.setUserId(4);
userDO.setUserName("mac");
list.add(userDO); return list;
} /**
* SELECT 查询操作,返回一个JSON数组
* 具有幂等性
* */
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers(){
List<UserDO> list=new ArrayList<>(); list=getData(); return list;
} /**
* SELECT 查询操作,返回一个新建的JSON对象
* 具有幂等性
* */
@GetMapping("/users/{id}")
@ResponseStatus(HttpStatus.OK)
public Object getUser(@PathVariable("id") String id){ if(null==id){
return null;
} List<UserDO> list= getData();
UserDO userDO=null;
for (UserDO user:list
) {
if(id.equals(user.getUserId().toString())){
userDO=user;
break;
}
} return userDO;
} /**
* 新增一个用户对象
* 非幂等
* */
@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public Object addUser(@RequestBody UserDO user){ List<UserDO> list= getData();
list.add(user);//模拟向列表中增加数据
return user;
} /**
* 编辑一个用户对象
* 幂等性
* */
@PutMapping("/users/{id}")
@ResponseStatus(HttpStatus.CREATED)
public Object editUser(@PathVariable("id") String id,@RequestBody UserDO user){
List<UserDO> list= getData();
for (UserDO userDO1:list
) {
if(id.equals(userDO1.getUserId().toString())){
userDO1=user;
break;
}
} return user;
} /**
* 删除一个用户对象
* 幂等性
* */
@DeleteMapping("/users")
@ResponseStatus(HttpStatus.NO_CONTENT)
public Object deleteUser(@PathVariable("id") String id){
List<UserDO> list= getData();
UserDO userDO=null;
for (UserDO user:list
) {
if(id.equals(user.getUserId().toString())){
//删除用户
userDO=user;
break;
}
}
return userDO;//返回被删除的对象
}
}

2.2.3 使用 PostMan 测试

获取全部资源 获取所有用户

GET http://localhost:8086/api/user/users/

[
{
"userId": 1,
"userName": "admin"
},
{
"userId": 2,
"userName": "heike"
},
{
"userId": 3,
"userName": "tom"
},
{
"userId": 4,
"userName": "mac"
}
]

获取单个资源 获取用户

GET http://localhost:8086/api/user/users/3

{
"userId": 3,
"userName": "tom"
}

新增一个资源 新增一个用户

POST http://localhost:8086/api/user/users

请求参数

{
"userId": 4,
"userName": "newname"
}

编辑更新一个资源

POST http://localhost:8086/api/user/users

请求参数

{
"userId": 1,
"userName": "editname"
}

删除一个资源

DELETE http://localhost:8086/api/user/users

请求参数

{
"userId": 1
}

2.2.4 其他辅助设计

RESTful API 可以结合 @RestControllAdvie 做全局异常处理,可以使用自定义标签做日志拦截,可以做全局日志拦截,可以做自动数据验证等等。

3 为什么不推荐使用 RESTful API

RESTful API 固然很好但大多数互联网公司都没有按照其规则来设计。因为 REST 本来就是一种风格,并没有什么固定的规则来约束,基于过于理想的 RESTful API 只会付出更多的人力成本和时间成本。

3.1 操作方式繁琐,没有效率,且意义不大

使用 HTTP 的 GET\POST\PUT\DELETE 来区分操作资源,HTTP Method 本身就对外部不友好,是隐藏的方法,把动词加入到 url 中,反而清晰可见,简单易懂,为什么一定要用 url 来表示资源而不能加动词呢。

GET\POST\PUT\DELETE 的兼容性有待认证,首先是兼容老的系统,大部分 HTTP 应用是基于 GET/POST 来实现的。

3.2 过分强调单一资源

这可能是人的理解问题,就看我们对资源的定义,太多的场景,如果使用 Restful API 规则行事,势必要把一个 API 拆分多个 API,框架多个 API 之间的状态又成了问题。

3.3 返回值问题

使用 HTTP Status 状态码是没有问题的,但使用不常见的状态码表示操作层面的含义,对开发不是很友好。

对返回集中定义 status、message 例如下面的 json 返回是很常见的返回,简单易懂。并没有什么不妥,但在 RESTful Api 拥护者眼里就是错误的格式,错误的返回。

{
"status":1,
"message":"",
"data":[]
}

3.4 更高的成本

统一为 RESTful API 风格,强化要求做的完美,比如带来更多的时间成本、人力成本。沟通成本。

本项目源码下载


关联阅读:

Spring Boot Log 日志使用教程

Spring Boot 全局异常处理

SpringBoot RESTful API 架构风格实践的更多相关文章

  1. 4 种主流的 API 架构风格对比

    1RPC:调用另一个系统的函数 RPC 的工作机制 客户端调用一个远程的过程,将参数和附加信息序列化为消息,然后将消息发送到服务端.服务端在接受到消息后,将信息的内容反序列化,执行所请求的操作,然后将 ...

  2. RESTful API 架构解读

    RESTful API 架构解读 首先我们还是先介绍下 RESTful api 的来龙去脉. 首先, RESTful (下文都简称 RESTful api 为 RESTful ) 1.RESTful ...

  3. RESTful API 设计指南,RESTful API 设计最佳实践

    RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...

  4. 关于RestFul API 介绍与实践

    之前演示的PPT,直接看图...     •参考链接: •RESTful API 设计最佳实践 •RESTful API 设计指南 •SOAPwebserivce和RESTfulwebservice对 ...

  5. RESTful API架构和oauth2.0认证机制(概念版)

    1. 什么是REST REST全称是Representational State Transfer,中文意思是表述(编者注:通常译为表征)性状态转移. 它首次出现在2000年Roy Fielding的 ...

  6. 深入理解 RESTful Api 架构

    转自https://mengkang.net/620.html 一些常见的误解 不要以为 RESTful Api  就是设计得像便于 SEO 的伪静态,例如一个 Api 的 URL 类似于 http: ...

  7. RESTful 服务架构风格 * .NET的RESTful框架 OpenRasta

    REST 的约束采用的就是掌控 Web 的基本原则.这些原则是: 用户代理与资源交互,任何可命名和表达的事物都可称为资源.每项资源都有一个唯一的统一资源标识符 (URI). 与资源的交互(通过其唯一的 ...

  8. Restful API 架构与设计参考原则

    1. 什么是RESTREST全称是Representational State Transfer,中文意思是表述(编者注:通常译为表征)性状态转移. 它首次出现在2000年Roy Fielding的博 ...

  9. (转载https://segmentfault.com/a/1190000016313947)了解RestFul Api架构风格设计

    最近几年REST API越来越流行,特别是随着微服务的概念被广泛接受和应用,很多Web Service都使用了REST API. REST是HTTP规范主要编写者之一的Roy Fielding提出的, ...

随机推荐

  1. windows7安装 npm和cnpm

    1.node.js下载地址: https://nodejs.org/en/download/ 我选择的安装路径是D:\files\nodejs 2.查看安装是否成功 3.创建文件夹 在D:\files ...

  2. win10显示“没有有效的IP地址”

    可能你没有新建该宽带连接!!!(本人就是蠢到如此地步了_(:з)∠)_)

  3. 大白话Web三大组件之一Servlet

    很多学习到Servlet这里的童鞋,听到那么多专业名词解释这个Servlet,相信都是很蒙圈的,在这里我先不跟大家扯Servlet的大概念,先跟大家探讨一下关于Servlet的作用 相信MVC这个概念 ...

  4. BZOJ 2342 [Shoi2011]双倍回文(Manacher)

    题目链接:https://www.lydsy.com/JudgeOnline/problem.php?id=2342 题意:求最长子串使得它有四个相同的回文串SSSS相连组成. 首先跑一边Manach ...

  5. 网关集成Swagger出现404错误

    原因是忘了在需要生成api的类上加入注解  @EnableSwagger2Doc

  6. leetcode78.子集➕90.子集2

    78子集 dfs dfs1: 和全排列的区别就是对于当前考察的索引i,全排列如果不取i,之后还要取i,所以需要一个visited数组用来记录.对于子集问题如果不取i,之后也不必再取i. 单纯递归回溯 ...

  7. Python结束当前运行的代码

    import sys print(0) print(1) print(2) # 到此结束运行 sys.exit() # 已结束,以下不会执行 print(4) print(5)

  8. 安装ipython[win/linux]

    首先以win7  64位系统, python2.7.9为例,linux见底部 1.下载材料http://files.cnblogs.com/files/smileyes/ipython-win64.z ...

  9. 深入理解JDK、JRE(两套)、JVM、以及不同目录下的java.exe

    内容来自:http://blog.sina.com.cn/s/blog_7ffb8dd501011sgc.html 1.jdk下bin目录里的java.exe与外部jre中的java.exe的秘密   ...

  10. snowflake 雪花算法 分布式实现全局id生成

    snowflake是Twitter开源的分布式ID生成算法,结果是一个long型的ID. 这种方案大致来说是一种以划分命名空间(UUID也算,由于比较常见,所以单独分析)来生成ID的一种算法,这种方案 ...