6：RestFul API-Java Spring

你的名字 2024-04-03 08:42 93阅读 0赞

#### 目录 ####

*  6.1 RestFul API介绍
 *  6.2 URL构成
 *  6.3 RestFul API原理
 *  6.4 RestFul API映射注解
 *  6.5 RestFul API操作

## 6.1 RestFul API介绍 ##

Rest表示性状态转移（Representation State Transfer），用URI表示资源，用HTTP方法(GET, POST, PUT, DELETE)表征对这些资源的操作，用于 Web 数据接口的设计，Rest的最基本特征是面向资源

*  Resource 资源，资源是构成应用系统的所有的基本概念，即数据
 *  Representational 表述，REST的资源可以用XML，JSON，纯文本等多种方式表述
 *  State Transfer 状态转移，客户端通过HTTP的GET/POST/PUT/DELETE/PATCH对资源进行操作，实现资源的状态转移

## 6.2 URL构成 ##

Restful API用URL表示特定的资源或资源集合，例如`http://www.xxx.com/goods`

*  URI（统一资源标识符）用于标识一个资源，提供标识资源的方法
 *  URL（统一资源定位符）用于提供找到某个资源的路径，比如网址
 *  URL是URI的子集

<table> 
 <thead> 
  <tr> 
   <th align="left">URL</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">/categories</td> 
   <td align="left">商品的所有一级分类categories</td> 
  </tr> 
  <tr> 
   <td align="left">/categories/1</td> 
   <td align="left">id为1的一级分类</td> 
  </tr> 
  <tr> 
   <td align="left">/categories/1/goods</td> 
   <td align="left">id为1的一级分类下所有商品</td> 
  </tr> 
  <tr> 
   <td align="left">/categories/1/subcategories</td> 
   <td align="left">id为1的一级分类下的所有二级分类</td> 
  </tr> 
  <tr> 
   <td align="left">/subcategories/2</td> 
   <td align="left">id为2的二级分类</td> 
  </tr> 
  <tr> 
   <td align="left">/subcategories/2/goods</td> 
   <td align="left">id为2的二级分类下所有商品</td> 
  </tr> 
  <tr> 
   <td align="left">/goods/5</td> 
   <td align="left">id为5的商品</td> 
  </tr> 
 </tbody> 
</table>

## 6.3 RestFul API原理 ##

RESTful API 是一种指REST设计风格的API，采用HTTP做传输协议，用一套协议来规范多种形式的前端和同一个后台的交互方式

用户在Android、IOS、PC等终端平台向服务端发送请求后，需要为每个平台的数据请求单独定义相应的返回格式，需要为每个平台单独写一个后台系统

而RESTful API 要求前端用一套协议来规范的语法格式发送请求，并与同一个后台系统交互，服务端只需要定义一个统一的响应接口（API）即可

![在这里插入图片描述][3e8f1db1285c4da28b4fdf67c2fd97b5.png]

传统API

*  http://localhost:8080/user/queryUser （GET查询用户）
 *  http://localhost:8080/user/addUser（POST添加用户）
 *  http://localhost:8080/user/updateUser （PUT更新用户）
 *  http://localhost:8080/user/deleteUser （DELETE删除用户）

RestFul API

*  http://localhost:8080/user/1 （`@GetMapping("/user/{userId}")` 查询）
 *  http://localhost:8080/user （`@PostMapping("/user")` 添加或修改）
 *  http://localhost:8080/user （`@PutMapping("/user")` 修改）
 *  http://localhost:8080/user/1 （`@DeleteMapping("/user/{userId}")` 删除）

## 6.4 RestFul API映射注解 ##

<table> 
 <thead> 
  <tr> 
   <th align="left">请求方法</th> 
   <th align="left">用途</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">@Controller</td> 
   <td align="left">表明了这个类或方法是一个控制器，用于返回对象</td> 
  </tr> 
  <tr> 
   <td align="left">@ResponseBody</td> 
   <td align="left">将返回的Java对象转为JSON格式的数据</td> 
  </tr> 
  <tr> 
   <td align="left">@RestController</td> 
   <td align="left">包含了<code>@Controller</code>和<code>@ResponseBody</code></td> 
  </tr> 
  <tr> 
   <td align="left">@RequestMapping</td> 
   <td align="left">全注解，将 HTTP 请求映射到 MVC 和 REST 控制器的处理方法上</td> 
  </tr> 
  <tr> 
   <td align="left">@GetMapping</td> 
   <td align="left">接收GET的请求方式，等同于 <code>@RequestMapping(value ="/user", method = RequestMethod.GET)</code></td> 
  </tr> 
  <tr> 
   <td align="left">@PostMapping</td> 
   <td align="left">接收Post的请求方式，等同于 <code>@RequestMapping(value ="/user", method = RequestMethod.POST)</code></td> 
  </tr> 
  <tr> 
   <td align="left">@PutMapping</td> 
   <td align="left">接收Put的请求方式，等同于<code>@RequestMapping(value ="/user", method = RequestMethod.PUT)</code></td> 
  </tr> 
  <tr> 
   <td align="left">@DeleteMapping</td> 
   <td align="left">接收Delete的请求方式，等同于<code>@RequestMapping(value ="/user", method = RequestMethod.DELETE)</code></td> 
  </tr> 
  <tr> 
   <td align="left">@RequestParam</td> 
   <td align="left">将请求参数绑定到控制器的方法参数上</td> 
  </tr> 
  <tr> 
   <td align="left">@PathVariable</td> 
   <td align="left">接收请求路径中占位符的值</td> 
  </tr> 
  <tr> 
   <td align="left">@RequestBody</td> 
   <td align="left">接收前端传递给后端的json字符串中的数据(请求体中的数据的)</td> 
  </tr> 
 </tbody> 
</table>

## 6.5 RestFul API操作 ##

RestFul API接口响应的资源（返回给前端的数据格式）的表现形式是， `@RestController`与`@Controller`标签相同，用于标注在类定义前面，使得类会被认定为Controller对象，用于告知Spring容器，该类所有方法的返回值需要以JSON或XML格式写到`@ResponseBody`内

*  可在控制类（@Controller类）上添加`@ResponseBody` 注解
 *  可在每个接口的方法上添加`@ResponseBody` 注解
 *  可把`@ResponseBody`注解提取到控制器上，这个控制器中所有的返回值会写到`@ResponseBody`内
 *  可在控制类（@Controllerr类）上合并`@Controller`和`@ResponseBody`成一个`@RestController`注解

RestFul API通过两种方式实现定义接口的URL

1.指定请求方式

*  `@RequestMapping(value ="/user", method = RequestMethod.GET)` 查询

2.特定请求方式

*  `@PostMapping("/user")` 添加或修改

HTTP的五种请求方法

<table> 
 <thead> 
  <tr> 
   <th align="left">请求方法</th> 
   <th align="left">用途</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">POST</td> 
   <td align="left">创建一个新的资源并返回新资源</td> 
  </tr> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left">查询特定资源</td> 
  </tr> 
  <tr> 
   <td align="left">PUT</td> 
   <td align="left">修改资源的全部属性并返回修改后的资源</td> 
  </tr> 
  <tr> 
   <td align="left">PATCH</td> 
   <td align="left">修改资源的特定属性并返回修改后的资源</td> 
  </tr> 
  <tr> 
   <td align="left">DELETE</td> 
   <td align="left">删除资源</td> 
  </tr> 
 </tbody> 
</table>

HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">2**</td> 
   <td align="left">操作成功接收并处理</td> 
  </tr> 
  <tr> 
   <td align="left">3**</td> 
   <td align="left">重定向</td> 
  </tr> 
  <tr> 
   <td align="left">4**</td> 
   <td align="left">客户端错误，请求包含语法错误</td> 
  </tr> 
  <tr> 
   <td align="left">5**</td> 
   <td align="left">服务器错误，服务器在处理请求的过程中发生了错误</td> 
  </tr> 
 </tbody> 
</table>

共用HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">400</td> 
   <td align="left">参数格式错误（缺少或不符合要求）</td> 
  </tr> 
  <tr> 
   <td align="left">401</td> 
   <td align="left">用户需登录访问</td> 
  </tr> 
  <tr> 
   <td align="left">403</td> 
   <td align="left">用户无权限访问</td> 
  </tr> 
  <tr> 
   <td align="left">409</td> 
   <td align="left">资源冲突或资源被锁定（由于事务回滚造成的）</td> 
  </tr> 
  <tr> 
   <td align="left">500</td> 
   <td align="left">服务器通用错误（服务器程序错误）</td> 
  </tr> 
  <tr> 
   <td align="left">503</td> 
   <td align="left">服务当前无法处理请求（服务器忙）</td> 
  </tr> 
 </tbody> 
</table>

GET请求

<table> 
 <thead> 
  <tr> 
   <th align="left">URL</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">GET /categories</td> 
   <td align="left">获取所有的一级商品分类</td> 
  </tr> 
  <tr> 
   <td align="left">GET /categories/1</td> 
   <td align="left">获取id为1的一级商品分类对象</td> 
  </tr> 
  <tr> 
   <td align="left">GET /categories/1/goods</td> 
   <td align="left">获取id为1的一级商品分类下所有商品</td> 
  </tr> 
  <tr> 
   <td align="left">GET /categories/1/subcategories</td> 
   <td align="left">获取id为1的分类下的所有子分类</td> 
  </tr> 
  <tr> 
   <td align="left">GET /goods?name=电视机 &amp;sort=price&amp;order=acend</td> 
   <td align="left">获取商品名称为电视机的商品，按照价格升 序排序</td> 
  </tr> 
 </tbody> 
</table>

Get请求的HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">200</td> 
   <td align="left">请求成功，数据在Response中返回</td> 
  </tr> 
 </tbody> 
</table>

POST请求

<table> 
 <thead> 
  <tr> 
   <th align="left">URL</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">POST /categories</td> 
   <td align="left">创建一个新的一级商品分类</td> 
  </tr> 
  <tr> 
   <td align="left">POST /categories/1/subcategories</td> 
   <td align="left">在id为1的一级商品分类下创建一个二级分类</td> 
  </tr> 
  <tr> 
   <td align="left">POST /subcategories/1/goods/1</td> 
   <td align="left">在id为1的二级商品分类下增加id为1的商品</td> 
  </tr> 
  <tr> 
   <td align="left">POST /orders/1000/payments</td> 
   <td align="left">为id为1000的订单付款</td> 
  </tr> 
  <tr> 
   <td align="left">POST /login</td> 
   <td align="left">用户登录</td> 
  </tr> 
 </tbody> 
</table>

Post请求的HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">201</td> 
   <td align="left">新资源成功，数据在Response中返回</td> 
  </tr> 
  <tr> 
   <td align="left">202</td> 
   <td align="left">已经接受处理请求但尚未完成（异步处理）</td> 
  </tr> 
 </tbody> 
</table>

PUT请求

<table> 
 <thead> 
  <tr> 
   <th align="left">URL</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">PUT /categories/1</td> 
   <td align="left">修改id为1的一级商品分类</td> 
  </tr> 
  <tr> 
   <td align="left">PUT /subcategories/1</td> 
   <td align="left">修改id为1的二级商品分类</td> 
  </tr> 
  <tr> 
   <td align="left">PUT /goods/5/onshelves</td> 
   <td align="left">将id为5的商品上架</td> 
  </tr> 
  <tr> 
   <td align="left">PUT /goods/5/offshelves</td> 
   <td align="left">将id为5的商品下架</td> 
  </tr> 
 </tbody> 
</table>

PUT请求的HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">200</td> 
   <td align="left">修改成功</td> 
  </tr> 
  <tr> 
   <td align="left">202</td> 
   <td align="left">已经接受处理请求但尚未完成（异步处理）</td> 
  </tr> 
 </tbody> 
</table>

DELETE请求

<table> 
 <thead> 
  <tr> 
   <th align="left">URL</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">DELETE /categories/1</td> 
   <td align="left">删除id为1的一级商品分类</td> 
  </tr> 
  <tr> 
   <td align="left">DELETE /categories/1/goods/5</td> 
   <td align="left">在id为1的分类中将id为5的商品移除</td> 
  </tr> 
 </tbody> 
</table>

Delete请求的HTTP状态码

<table> 
 <thead> 
  <tr> 
   <th align="left">HTTP状态码</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">200</td> 
   <td align="left">删除成功</td> 
  </tr> 
  <tr> 
   <td align="left">202</td> 
   <td align="left">已经接受处理请求但尚未完成（异步处理）</td> 
  </tr> 
 </tbody> 
</table>

[3e8f1db1285c4da28b4fdf67c2fd97b5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/fe1587bdc4404de398354a4ef7ed6689.png